业务错误必须用自定义BizError结构体封装，携带Code、Message、TraceID等字段，便于识别、分类和统一处理；系统错误需用%w包装保留原始error链，区分可恢复性；HTTP handler中依错误类型分流返回4xx或500状态码。
业务错误必须用自定义 error 类型封装
Go 中没有 checked exception，但业务逻辑出错（如用户余额不足、订单已取消）不能直接返回 errors.New("余额不足") 这类裸字符串 error。裸 error 无法携带上下文、无法被下游准确识别和分类处理。
推荐做法是定义带字段的结构体 error：
type BizError struct {
Code int `json:"code"`
Message string `json:"message"`
TraceID string `json:"trace_id,omitempty"`
}
func (e *BizError) Error() string {
return e.Message
}
func NewInsufficientBalanceError(traceID string) error {
return &BizError{
Code: 4001,
Message: "insufficient balance",
TraceID: traceID,
}
}
- 所有业务错误统一返回
*BizError，便于中间件或 HTTP handler 统一提取Code渲染状态码与响应体 - 避免用
fmt.Errorf("xxx: %w", err)包裹业务 error —— 会丢失原始类型，errors.Is()和errors.As()失效 - 日志中记录业务 error 时，应显式打点
log.WithField("biz_code", e.Code)，而非只打e.Error()
系统错误要保留原始 error 链并区分可恢复性
系统错误指 I/O 失败、网络超时、数据库连接中断等底层异常，这类错误往往带有重试价值，且需暴露底层原因供运维排查。
关键原则是：不吞掉原始 error，用 %w 显式包装，并在必要时标记可重试性：
立即学习“go语言免费学习笔记（深入）”；
func (s *OrderService) FetchFromPayment(ctx context.Context, id string) (*PaymentResp, error) {
resp, err := s.client.Do(ctx, req)
if err != nil {
// 不写 errors.New("fetch payment failed")，而是包装原始 err
return nil, fmt.Errorf("failed to fetch payment for order %s: %w", id, err)
}
return resp, nil
}
- 使用
errors.Is(err, context.DeadlineExceeded)或net.ErrClosed等标准 error 判断是否可重试，而不是靠字符串匹配 - 不要对系统错误调用
errors.Unwrap()后丢弃 —— 会破坏 error 链，导致errors.Is()在上层失效 - HTTP handler 中遇到系统错误，应返回 500，但响应体里仍可包含
"error": "timeout: context deadline exceeded"（脱敏后），方便前端区分“服务暂时不可用”和“用户操作非法”
HTTP handler 中如何分流处理两类错误
一个请求进来，最终返回什么 HTTP 状态码、响应体结构，取决于错误类型。不能全走 http.StatusInternalServerError。
- 遇到
*BizError：取e.Code映射为 4xx 状态码（如 4001 → 400），响应体含{"code": 4001, "message": "insufficient balance"} - 遇到系统错误（即非
*BizError的 error）：统一返回 500，但记录完整 error 链到日志，响应体仅返回泛化提示如{"error": "service unavailable"} - 特别注意：
json.Unmarshal失败、time.Parse失败等输入解析错误，属于业务边界问题，应转为*BizError（如 4000），而非当作系统错误抛出
容易被忽略的细节：error 类型断言与中间件顺序
很多团队写了自定义 error，却在中间件里用错判断方式，导致业务错误被当成系统错误兜底处理。
- 必须用
errors.As(err, &target)判断是否为业务错误，而不是reflect.TypeOf(err) == reflect.TypeOf(&BizError{})—— 因为 error 可能被多层%w包装 - recover 中间件必须放在所有业务中间件之后（如 JWT 验证、限流之后），否则 panic 会绕过业务 error 处理逻辑
- gRPC 场景下，业务错误应映射为
status.Code（如codes.InvalidArgument），系统错误才用codes.Internal；别把*BizError直接传给status.Errorf，会丢失结构化字段
