Golang错误类型区分：业务与系统错误解析

本文深入解析了Go语言中业务错误与系统错误的科学区分与规范处理方案：业务错误必须通过结构化的`BizError`类型封装，携带可识别的Code、Message和TraceID等字段，确保上下文完整、分类清晰、便于统一响应和日志追踪；系统错误则需严格使用`%w`包装以保留原始error链，支持`errors.Is()`精准判断可恢复性（如超时、连接中断），并为重试和运维排查提供依据；在HTTP handler中，两类错误须明确分流——`*BizError`映射为4xx状态码并返回结构化业务提示，系统错误统一返回500但响应体脱敏、日志详尽；同时强调了类型断言必须用`errors.As`而非反射比较、中间件顺序影响错误捕获逻辑等易被忽视的关键实践，帮助开发者构建健壮、可观测、易维护的Go微服务错误体系。

业务错误必须用自定义 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 显式包装，并在必要时标记可重试性：

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，会丢失结构化字段

好了，本文到此结束，带大家了解了《Golang错误类型区分：业务与系统错误解析》，希望本文对你有所帮助！关注golang学习网公众号，给大家分享更多Golang知识！