Go语言如何定义业务层的错误类型_Golang业务错误处理规范

应为业务错误定义具名结构体类型以支持断言、携带上下文和统一处理，避免使用 Errors.New 或 fmt.Errorf。

为什么不能直接用 errors.New 或 fmt.Errorf 包装业务错误

业务错误（如“用户余额不足”“订单状态非法”）不是程序崩溃或 I/O 失败这类底层问题，它们是领域逻辑的一部分。直接用 errors.New 或 fmt.Errorf 会丢失错误分类能力、无法携带上下文字段（如订单 ID、错误码），也难以统一处理（比如日志脱敏、http 状态码映射）。更麻烦的是，下游调用方只能靠字符串匹配判断错误类型，脆弱且不可维护。

实操建议：

• 为每类业务错误定义独立的结构体类型，实现 error 接口
• 在结构体中嵌入标准字段：Code（int 或 String 错误码）、Message（用户/前端可见提示）、Details（调试用的 map[string]Interface{} 或结构体）
• 避免在错误构造时拼接敏感信息（如完整身份证号），细节字段应支持按需序列化

如何设计可区分、可断言的业务错误类型

go 的错误判断依赖类型断言或 errors.Is/errors.As，所以业务错误必须是具名类型，不能是字符串或匿名 Struct。

示例：

立即学习“go语言免费学习笔记（深入）”；

type InsufficientBalanceError struct {     OrderID string     Balance float64     Required float64     Code    int }  func (e *InsufficientBalanceError) Error() string {     return "insufficient balance" }  func (e *InsufficientBalanceError) ErrorCode() int {     return e.Code }

这样调用方可安全断言：

if err != nil {     var e *InsufficientBalanceError     if errors.As(err, &e) {         // 处理余额不足逻辑         log.Warn("balance check failed", "order_id", e.OrderID)         return http.StatusbadRequest, e.Error()     } }

关键点：

• 错误类型首字母大写，导出供其他包使用
• 不实现 Unwrap() 除非你明确需要链式错误（多数业务错误是终端错误，不该被忽略）
• 若错误码需全局唯一，建议集中定义在 pkg/errors/codes.go 中，用 const 常量管理

HTTP 层如何把业务错误转成响应？

业务层只负责抛出带语义的错误，API 层统一拦截并映射为 HTTP 状态码和 jsON 响应。不要让 handler 里满屏 if err != nil { ... }。

推荐做法：

• 定义中间件或统一返回封装函数，接收 error 并根据类型/错误码决定 status code 和 body 字段
• 对已知业务错误（如 *InsufficientBalanceError）返回 400 Bad Request；对系统级错误（如 DB 连接失败）返回 500 internal Server Error
• 避免把原始 Error() 消息直接透传给前端，而是取 e.Message 或查表翻译

常见陷阱：

• 忘记在中间件中调用 errors.Unwrap 多层解包，导致嵌套错误无法被正确识别
• 用 errors.Is(err, xxxErr) 判断时，xxxErr 是零值变量（未取地址），断言永远失败

日志记录时怎么避免泄露敏感信息又保留调试价值

业务错误本身可能含订单号、手机号等，直接 log.Error("failed", "err", err) 很危险。但全打码又失去定位能力。

实操方案：

• 错误类型实现自定义 LogValue() []interface{} 方法（适配主流日志库如 zap、zerolog）
• 在该方法中只暴露脱敏后字段：如 OrderID → "ORD-***1234"，Phone → "138****5678"
• 完整原始错误对象仅在 debug 日志级别输出，且限定在内部运维日志通道，不进用户行为日志流

容易被忽略的一点：错误实例如果包含指针字段（如指向用户实体的 *User），序列化日志时可能意外打印整个用户数据——务必检查结构体字段是否都经过显式控制。