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

在Go语言开发中，清晰区分业务错误与系统错误是构建健壮、可观测微服务的关键实践：业务错误（如余额不足、订单已取消）必须通过结构化`*BizError`封装，携带可识别的`Code`、`Message`和`TraceID`，确保前端精准响应与后端统一分类处理；系统错误（如网络超时、DB连接中断）则需用`%w`保留完整error链以支持重试判断与根因追踪，严禁裸字符串或破坏性包装；HTTP handler据此智能分流——业务错误映射为语义明确的4xx状态码及结构化响应，系统错误统一返回500并脱敏透出提示；同时，正确使用`errors.As`断言、合理安排中间件顺序及适配gRPC等场景，才能真正发挥该错误治理体系的价值。

业务错误必须用自定义 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学习网公众号！