如何在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 响应。

关键点在于：不要在 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"。