errors.New 和 fmt.Errorf 不够用，因无法携带上下文、支持类型断言或区分错误分支；应定义带字段和方法的结构体自定义错误类型，并合理使用 errors.Join 与统一错误响应转换。
为什么 errors.New 和 fmt.Errorf 不够用
当错误需要携带上下文（如请求 ID、失败的资源 ID、重试次数）、支持类型断言、或需区分不同错误分支时，errors.New 返回的纯字符串错误无法满足。比如 HTTP 服务中要判断是「数据库超时」还是「第三方 API 拒绝连接」，靠字符串匹配极易出错且脆弱。
自定义错误类型的核心价值不是“看起来高级”，而是让错误可识别、可分类、可携带结构化信息。
如何定义带字段和方法的自定义错误类型
推荐用结构体实现 error 接口，同时嵌入 fmt.Stringer 保证可打印，并提供额外方法用于业务判断：
type DatabaseTimeoutError struct {
Query string
ElapsedMs int64
ReqID string
}
func (e *DatabaseTimeoutError) Error() string {
return fmt.Sprintf("database timeout on %q after %dms (req=%s)", e.Query, e.ElapsedMs, e.ReqID)
}
func (e *DatabaseTimeoutError) IsTimeout() bool { return true }
func (e *DatabaseTimeoutError) RequestID() string { return e.ReqID }
- 务必导出关键字段（如
ReqID），否则调用方无法访问 - 不要在
Error()方法里做耗时操作（如日志、网络请求） - 若需兼容
errors.Is/errors.As，结构体字段应为指针类型（如*DatabaseTimeoutError），否则类型断言可能失败
何时该用 errors.Join 或嵌套错误
当一个错误由多个底层错误组合而成（如并发请求中部分失败），用 errors.Join 聚合比拼接字符串更可靠：
Golang Uber Dig
下载
使用 uber-go/dig 在 Golang 中实现依赖注入——基于反射容器，提供 Provide/Invoke、dig.In/dig.Out 参数与结果对象，支持命名依赖等
立即学习“go语言免费学习笔记（深入）”；
err := errors.Join(
&DatabaseTimeoutError{Query: "SELECT users", ElapsedMs: 2500, ReqID: "req-123"},
&HTTPClientError{URL: "https://api.example.com", StatusCode: 503},
)
// 后续可用 errors.Is(err, &DatabaseTimeoutError{}) 判断是否含某类错误
-
errors.Join返回的错误仍支持errors.Is和errors.As，但注意：它不保留原始错误的字段值，只保留类型和Error()输出 - 若需透传子错误的结构化字段（如所有子错误的
ReqID），得自己实现聚合结构体，而不是依赖errors.Join - 避免过度嵌套——三层以上嵌套会让错误溯源变困难，日志中展开也易被截断
在 HTTP handler 中怎么返回结构化错误响应
不要直接把自定义错误转成 JSON 返回，而应在中间层统一转换：
func errorResponse(err error) (int, map[string]any) {
var dbErr *DatabaseTimeoutError
if errors.As(err, &dbErr) {
return http.StatusGatewayTimeout, map[string]any{
"code": "DB_TIMEOUT",
"message": err.Error(),
"request_id": dbErr.ReqID,
"retry_after": 2,
}
}
// 其他类型...
return http.StatusInternalServerError, map[string]any{"code": "INTERNAL", "message": "server error"}
}
- HTTP 状态码不能仅靠错误类型名决定（比如
ValidationError通常对应 400，但某些场景可能是 422） - 别把敏感字段（如 SQL 查询原文、堆栈路径）直接塞进响应体；生产环境应过滤或脱敏
- 如果用了 Gin/Echo 等框架，建议封装成统一的
ctx.AbortWithError(status, err)方法，避免每个 handler 重复判断逻辑
真正难的不是定义结构体，而是团队对错误分类边界的共识——比如 “连接拒绝” 算网络层错误还是服务发现错误？这类边界一旦模糊，自定义类型就容易变成新包袱。
