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, ...}。建一个全局错误码映射，并提供语义化构造函数：
立即学习“go语言免费学习笔记（深入）”；
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”但实际是客户端断连，就很难定位问题了。
