如何在Golang中对错误进行统一包装_Golang错误中间层设计_技术教程

errors.Wrap和%w仅支持链式包装，无法携带错误码、HTTP状态码等业务语义；需定义AppError结构体封装Code/Message/Err，并实现Is/Unwrap方法，配合错误码注册表与NewAppError工厂函数统一创建，再通过中间件自动映射HTTP响应。

为什么直接用 `errors.Wrap` 不够用

项目规模稍大后，errors.Wrap（来自 github.com/pkg/errors）或 Go 1.13+ 的 fmt.Errorf("...: %w", err) 只解决「链式包装」问题，但无法承载业务语义：比如错误码、HTTP 状态码、日志标记、重试策略等。你不能靠 errors.Is 或 errors.As 判断「这是数据库超时还是权限不足」，除非手动加类型断言或字符串匹配——这脆弱且难维护。

定义带错误码的自定义错误类型

核心是让错误本身携带结构化元数据，而不是靠 message 字符串解析。推荐用接口 + 结构体组合方式：

type AppError struct {
	Code    int    `json:"code"`
	Message string `json:"message"`
	Err     error  `json:"-"` // 不序列化底层错误
}

func (e *AppError) Error() string {
	if e.Err != nil {
		return fmt.Sprintf("%s: %v", e.Message, e.Err)
	}
	return e.Message
}

func (e *AppError) Unwrap() error { return e.Err }
func (e *AppError) Is(target error) bool {
	if t, ok := target.(*AppError); ok {
		return e.Code == t.Code
	}
	return false
}

这样就能用 errors.Is(err, &AppError{Code: ErrCodeDBTimeout}) 安全判断，也支持嵌套包装（fmt.Errorf("failed to fetch user: %w", &AppError{Code: 5001, Message: "db timeout"})）。

中间层统一构造函数与错误码注册表

避免散落各处的 &AppError{Code: 1002, ...}。建一个全局错误码映射，并提供语义化构造函数：

var (
	ErrCodeInvalidParam = 4001
	ErrCodeNotFound     = 4041
	ErrCodeDBTimeout    = 5001
)

var ErrRegistry = map[int]string{
	ErrCodeInvalidParam: "invalid parameter",
	ErrCodeNotFound:     "resource not found",
	ErrCodeDBTimeout:    "database operation timeout",
}

func NewAppError(code int, msg string, err error) error {
	if desc, ok := ErrRegistry[code]; ok {
		msg = desc // 优先用注册描述，msg 作为补充上下文
	}
	return &AppError{Code: code, Message: msg, Err: err}
}

// 使用示例：
// return NewAppError(ErrCodeNotFound, "user id=123", sql.ErrNoRows)

所有错误创建走 NewAppError，保证一致性
错误码数字建议按模块+类型分段（如 400x 表示客户端错误，500x 表示服务端错误）
msg 参数不是用来覆盖错误描述的，而是追加上下文（如 "user id=123"），便于排查

HTTP 层自动映射错误到响应状态码

在 Gin / Echo / net/http 中间件里，统一拦截 *AppError 并转成 HTTP 响应：

func ErrorHandler(next http.Handler) http.Handler {
	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		defer func() {
			if rec := recover(); rec != nil {
				http.Error(w, "internal error", http.StatusInternalServerError)
			}
		}()
		next.ServeHTTP(w, r)
		if err := getErrorFromContext(r.Context()); err != nil {
			var appErr *AppError
			if errors.As(err, &appErr) {
				w.Header().Set("Content-Type", "application/json; charset=utf-8")
				w.WriteHeader(statusCodeForAppError(appErr))
				json.NewEncoder(w).Encode(map[string]interface{}{
					"code":    appErr.Code,
					"message": appErr.Message,
				})
				return
			}
		}
	})
}

func statusCodeForAppError(e *AppError) int {
	switch {
	case e.Code >= 4000 && e.Code < 5000:
		return http.StatusBadRequest
	case e.Code >= 5000 && e.Code < 6000:
		return http.StatusInternalServerError
	default:
		return http.StatusInternalServerError
	}
}

注意：getErrorFromContext 需要你在 handler 内部把错误存进 r.Context()（例如用 context.WithValue），或者更推荐用中间件链式传递错误（如通过自定义 ResponseWriter 拦截 WriteHeader 前检查 panic 或 error）。

真正难的是错误边界控制：不是所有错误都要包装成 *AppError，比如 io.EOF、context.Canceled 这类系统级错误应原样透传，不包装也不记录为异常。漏掉这个判断，日志里全是“resource not found”但实际是客户端断连，就很难定位问题了。