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 聚合比拼接字符串更可靠：
AlegroCart
下载
AlegroCart新功能：维类：包括在这两种线性长宽高或面积或体积长波产品尺寸允许与期权产品：让产品/期权组合独特的数量，尺寸，图像和型号。选择店铺标识管理 图片放大镜：显示一个图片放大上空盘旋时，产品形象弹出框。自定义错误报告：设置在管理员启用。 开发者只可以显示详细的信息。错误信息都写入到错误日志文件每天可以通过电子邮件发送给管理员。仓库皮卡航运模块：允许客户指定产品在商店的位置回升。增加了
立即学习“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 重复判断逻辑
真正难的不是定义结构体，而是团队对错误分类边界的共识——比如 “连接拒绝” 算网络层错误还是服务发现错误？这类边界一旦模糊，自定义类型就容易变成新包袱。
