如何在Golang中统一处理错误_Golang集中式错误处理方案

go 错误处理应使用可断言的自定义 *appError 类型携带上下文与分类码，http 层统一拦截转响应，避免包装堆叠、panic 替代和 context 传 error。

Go 语言没有异常机制，error 是一等公民，但直接在每处 if err != nil 处理会导致重复、分散、难以追踪错误来源。真正的统一处理不是“抹掉错误”，而是建立可追溯、可分类、可干预的错误流转链路。

用自定义 error 类型携带上下文和分类标识

标准 errors.New 或 fmt.Errorf 生成的 error 不带类型信息，无法做 switch 分支处理。必须让 error 可识别、可断言。

推荐做法是定义带字段的结构体 error，并实现 Error() 方法：

type AppError struct { 	Code    int    `json:"code"` 	Message string `json:"message"` 	TraceID string `json:"trace_id,omitempty"` 	Op      string `json:"op,omitempty"` // 操作名，如 "user.login" }  func (e *AppError) Error() string { 	return fmt.Sprintf("[%d] %s", e.Code, e.Message) }  func NewAppError(code int, msg string, op string) *AppError { 	return &AppError{ 		Code:    code, 		Message: msg, 		Op:      op, 		TraceID: getTraceID(), // 从 context 或全局获取 	} }

• 避免用 errors.Wrap 堆叠多层包装——它只适合调试，不便于下游判断类型
• 所有业务错误都应返回 *AppError，而非 error 接口，方便 if e, ok := err.(*AppError) 断言
• Code 建议按域划分：4xx（客户端错）、5xx（服务端错）、1xx（业务逻辑错），例如 401 表示未授权，1001 表示用户不存在

在 HTTP handler 中集中拦截并标准化响应

HTTP 层是错误出口的统一闸口，所有 handler 都应返回 error，由中间件捕获并转为 HTTP 状态码与 JSON 响应。

立即学习“go语言免费学习笔记（深入）”；

关键点在于：不要在 handler 内部写 w.WriteHeader() 和 json.Marshal，交给中间件做：

func ErrorHandler(next http.Handler) http.Handler { 	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { 		defer func() { 			if r := recover(); r != nil { 				http.Error(w, "Internal Server Error", http.StatusInternalServerError) 				log.Printf("panic: %v", r) 			} 		}()  		next.ServeHTTP(w, r) 	}) }  // 更实用的是基于 error 返回值的 wrapper（配合 handler 函数签名变更） type HandlerFunc func(http.ResponseWriter, *http.Request) error  func Handle(h HandlerFunc) http.HandlerFunc { 	return func(w http.ResponseWriter, r *http.Request) { 		err := h(w, r) 		if err == nil { 			return 		}  		var appErr *AppError 		if errors.As(err, &appErr) { 			w.Header().Set("Content-Type", "application/json; charset=utf-8") 			w.WriteHeader(appErr.HTTPStatus()) 			json.NewEncoder(w).Encode(appErr) 			return 		}  		// 非 AppError，当作 500 处理 		w.WriteHeader(http.StatusInternalServerError) 		json.NewEncoder(w).Encode(&AppError{ 			Code:    50000, 			Message: "Unknown server error", 			Op:      "unknown", 		}) 	} }

• 不要依赖 http.Error —— 它只能写字符串，无法控制 status code 细粒度或加 trace_id
• 务必检查 errors.As 而非 == 或 errors.Is，因为业务 error 往往是包装过的
• panic 捕获仅用于兜底，不能替代 error 处理；真实错误应显式返回，而非 panic

用 context.Value 透传错误上下文（谨慎使用）

有些场景需要跨多层函数传递错误元信息，比如重试次数、上游服务名、是否允许重试。此时可将轻量级结构体塞进 context.Context，但绝不能用来“代替 error 返回”。

正确用法示例：

type ErrorContextKey string const ErrCtxKey ErrorContextKey = "error_ctx"  type ErrorMeta struct { 	RetryCount int 	Upstream   string 	CanRetry   bool }  func WithErrorMeta(ctx context.Context, meta ErrorMeta) context.Context { 	return context.WithValue(ctx, ErrCtxKey, meta) }  func GetErrorMeta(ctx context.Context) (ErrorMeta, bool) { 	v, ok := ctx.Value(ErrCtxKey).(ErrorMeta) 	return v, ok }

• 仅存元数据，不存 error 实例本身——避免 context 泄露或生命周期混乱
• 不要在 middleware 中覆盖已有 ErrorMeta，应 merge 而非 replace
• 若 error 已含足够字段（如 TraceID、Op），优先复用 error 结构，而非额外塞 context

最易被忽略的一点：统一错误处理 ≠ 统一掩盖错误。每个 *AppError 的 Op 字段必须真实反映出错位置（如 "order.create_payment"），否则日志聚合和链路追踪就失去意义。宁愿多写一行 return NewAppError(1002, "payment timeout", "order.create_payment")，也不要图省事返回一个泛化的 "operation failed"。