真正可行的统一错误码方案需在创建、传递、序列化、响应四环节保持结构化，核心是自定义实现error接口并含ErrorCode()方法的CodeError类型，禁用裸fmt.Errorf，通过工厂函数构造，中间件统一提取code返回标准化响应。
Go 项目里靠 errors.New 或 fmt.Errorf 拼字符串报错，很快就会失控：前端看不懂、日志难聚合、错误无法分类拦截。真正可行的统一错误码方案，核心不是“加个码”，而是让错误在创建、传递、序列化、响应四个环节都保持结构化和可识别。
定义带码的错误类型必须实现 error 接口且支持提取码和消息
不能只靠全局常量映射（比如 ErrUserNotFound = 1001），因为调用栈里一包 fmt.Errorf("failed to get user: %w", err) 就丢码。必须自定义错误类型：
type CodeError struct {
Code int
Message string
Err error // 原始底层错误，用于链式包装
}
func (e *CodeError) Error() string {
if e.Err != nil {
return fmt.Sprintf("%s: %v", e.Message, e.Err)
}
return e.Message
}
func (e *CodeError) Unwrap() error { return e.Err }
// 提供标准方法供上层读取
func (e *CodeError) ErrorCode() int { return e.Code }
func (e *CodeError) ErrorMessage() string { return e.Message }
关键点：
- 必须实现
Unwrap()，否则errors.Is()和errors.As()无法穿透包装获取原始*CodeError -
ErrorCode()方法名要固定，中间件、日志器、HTTP 响应层才好统一反射或断言提取 - 不要把
Code设为字符串——整数更易比较、存储、索引，也避免拼写错误
所有错误创建入口必须走工厂函数，禁用裸 fmt.Errorf
放任开发者直接用 fmt.Errorf 是统一方案失败的最常见原因。应该封死裸创建路径，只暴露带码构造函数：
var (
ErrUserNotFound = NewCodeError(1001, "user not found")
ErrInvalidParam = NewCodeError(1002, "invalid request parameter")
)
func NewCodeError(code int, msg string) *CodeError {
return &CodeError{Code: code, Message: msg}
}
// 支持包装底层错误（保留原始 error 链）
func WrapCodeError(code int, msg string, err error) *CodeError {
return &CodeError{Code: code, Message: msg, Err: err}
}
使用时：
- 业务逻辑中直接用
return ErrUserNotFound—— 简洁、可测试、无歧义 - 调用下游出错需包装时，用
return WrapCodeError(1003, "failed to call auth service", err) - 禁止出现
fmt.Errorf("user not found: %w", err)这类写法；如有必要，先转成*CodeError再包装
HTTP 中间件自动提取 ErrorCode() 并生成标准化响应
错误不该由每个 handler 自己判断怎么返回 JSON。用 Gin（或其他框架）时，在 recover 或全局 error handler 中统一处理：
func ErrorHandler(c *gin.Context) {
c.Next()
err := c.Errors.Last()
if err == nil {
return
}
var codeErr *CodeError
if errors.As(err.Err, &codeErr) {
c.JSON(http.StatusOK, map[string]interface{}{
"code": codeErr.ErrorCode(),
"msg": codeErr.ErrorMessage(),
"data": nil,
})
return
}
// 未识别的 panic 或非 CodeError，降级为 500
c.JSON(500, map[string]interface{}{
"code": 50000,
"msg": "internal server error",
"data": nil,
})
}
注意：
- 用
errors.As()而非类型断言，才能正确穿透多层%w包装 - 不要在中间件里 log 全量 error（含 stack），容易刷爆日志；只记录
code+msg，stack 留给 recover 后单独捕获并打到 error 日志系统 - 如果需要返回详细 debug 信息（如开发环境），可在
CodeError里加一个DebugMsg字段，但默认不输出到响应体
错误码注册表必须与 HTTP 状态码、业务域解耦管理
别把错误码硬编码成 4041001（前三位表 HTTP 状态码）。这种设计看似“自解释”，实则带来三重问题：
- 同一个业务错误可能在不同接口需返回不同 HTTP 状态码（如“用户不存在”在 GET 是 404，在 DELETE 可能是 200）
- 错误码一旦绑定 HTTP 码就无法复用到 RPC、消息队列等非 HTTP 场景
- 团队协作时，后端定义
4041001，前端查文档得记住“404 开头=客户端错”，徒增认知负担
推荐做法：
- 错误码纯数字，按业务域分段：1xxx 用户域、2xxx 订单域、5xxx 系统通用
- HTTP 状态码由 handler 或中间件根据错误码规则映射（例如：
switch code { case 1001: return 404; case 1002: return 400; default: return 500 }） - 维护一份
error_codes.yaml文件，包含code、message、zh-CN、en-US、http_status字段，构建时生成 Go const 或供前端拉取
最常被忽略的一点：错误码的语义必须稳定。一旦上线，1001 就永远代表“用户不存在”，哪怕后续新增了“租户用户不存在”“第三方用户不存在”，也应该用 1001 + 更精确的 message 区分，而不是另开 10011。否则前端 switch 分支会迅速失控。
