应为业务错误定义具名结构体类型以支持断言、携带上下文和统一处理，避免使用 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），序列化日志时可能意外打印整个用户数据——务必检查结构体字段是否都经过显式控制。
