17370845950

Go 的 error 接口仅含 Error() 方法，无法自带状态码或堆栈；必须定义导出字段的自定义结构体（如 AppError），实现 error、Unwrap()、Is() 等方法，并规范序列化与日志透传。

为什么 error 接口本身不能直接携带状态码或堆栈？

Go 的 error 是一个只含 Error() string 方法的接口，它不提供字段、类型断言之外的结构信息。这意味着如果你只用 errors.New 或 fmt.Errorf，所有错误在运行时都

是“扁平”的——无法区分是数据库超时、权限拒绝，还是参数校验失败，更没法附带 StatusCode、RequestID 或调用位置。

所以必须定义自己的错误类型，让错误可识别、可分类、可序列化。

如何定义带字段和行为的自定义错误结构？

典型做法是定义一个 struct，实现 error 接口，并额外提供访问方法。关键点在于：字段要导出（否则外部无法读取），Error() 方法应尽量简洁（避免嵌套格式化开销），且建议实现 Unwrap() 支持错误链。

• StatusCode 字段用于 HTTP 响应码，如 400、503
• Code 字段用于业务错误码，如 "USER_NOT_FOUND"
• Details 字段存 map 或 struct，用于透传调试信息
• stack（未导出）配合 runtime.Caller 捕获堆栈，但只在 debug 模式下填充

示例：

type AppError struct {
    StatusCode int
    Code       string
    Message    string
    Details    map[string]interface{}
    err        error // 用于 Unwrap
}

func (e *AppError) Error() string { return e.Message }
func (e *AppError) Unwrap() error { return e.err }
func (e *AppError) WithDetail(key string, value interface{}) *AppError {
    if e.Details == nil {
        e.Details = make(map[string]interface{})
    }
    e.Details[key] = value
    return e
}

什么时候该用 fmt.Errorf("... %w") 而不是新建结构体？

当错误只是「上下文增强」而非「语义升级」时，优先用包装（wrapping）。比如函数 A 调用函数 B，B 返回了 *AppError，A 只需补充“调用下游服务失败”，就该用 fmt.Errorf("failed to call X: %w", err)，而不是 new 一个新 AppError。

• 包装后的错误仍能通过 errors.As(err, &target) 提取原始 *AppError
• 过度新建结构体会割裂错误链，导致 errors.Is 和 errors.As 失效
• 只有当你需要改变错误的分类（如把 DB 错误转为用户可见错误）、添加新字段、或统一处理逻辑时，才新建实例

容易被忽略的细节：错误比较、序列化与日志透传

自定义错误若没实现 Is() 或 As() 方法，在用 errors.Is(err, myErr) 判断时会失败；若字段含指针或 map，直接 JSON 序列化会 panic；日志框架（如 zap）默认只调 Error()，不会输出 Code 或 Details。

• 实现 Is(target error) bool 方法，通常比对 Code 字段即可
• 导出字段名保持小驼峰（如 StatusCode），JSON tag 写成 json:"status_code"
• 给日志加字段时，别写 zap.Error(err)，改用 zap.String("code", appErr.Code) + zap.Any("details", appErr.Details)
• HTTP handler 中返回错误前，务必检查 err 是否实现了 StatusCode() int，再决定响应头状态码

真正麻烦的从来不是定义结构体，而是让整个错误从 panic 现场、中间件、日志、监控到前端展示，都保持语义一致——这要求每个环节都明确知道该读哪个字段、该调哪个方法、该忽略哪层包装。