Go如何定义业务错误及区分方法

今日不肯埋头，明日何以抬头！每日一句努力自己的话哈哈~哈喽，今天我将给大家带来一篇《Go如何定义业务错误及区分方法》，主要内容是讲解等等，感兴趣的朋友可以收藏或者有更好的建议在评论提出，我都会认真看的！大家一起进步，一起学习！

Go中应定义实现error接口及Is/As方法的自定义错误类型（如InsufficientBalanceError），用于明确标识和安全判断业务错误，避免字符串匹配；业务错误需与系统错误分离处理，HTTP层统一转换为结构化响应。

Go里怎么定义一个业务错误

业务错误不是程序崩溃或运行时panic，而是业务逻辑明确拒绝的场景，比如“用户余额不足”“订单已取消”“手机号已被注册”。这类错误需要被上层捕获、分类、返回给前端或记录审计日志，但不触发告警或中断服务流程。

最直接的方式是用 errors.New 或 fmt.Errorf 构造带上下文的错误值：

err := fmt.Errorf("insufficient balance: want %d, have %d", amount, balance)

但这种方式无法区分错误类型，也不利于后续判断。更推荐的做法是定义自定义错误类型：

type InsufficientBalanceError struct {
    OrderID string
    Want    int64
    Have    int64
}

func (e *InsufficientBalanceError) Error() string {
    return fmt.Sprintf("order %s: insufficient balance (want %d, have %d)", e.OrderID, e.Want, e.Have)
}

func (e *InsufficientBalanceError) Is(target error) bool {
    _, ok := target.(*InsufficientBalanceError)
    return ok
}

• 必须实现 Error() 方法才能满足 error 接口
• 建议实现 Is() 方法，方便用 errors.Is(err, &InsufficientBalanceError{}) 判断类型
• 避免在 Error() 中拼接敏感字段（如用户身份证号），日志里再单独打结构化字段

如何区分业务错误和系统错误

关键不在错误“长什么样”，而在它“从哪来”和“怎么处理”：

• 系统错误：来自底层调用，如 os.Open 失败、http.Client.Do 超时、数据库连接中断。它们代表基础设施异常，通常不可预期，需重试、降级或告警
• 业务错误：来自领域规则校验，如 “优惠券已过期”“收货地址超出配送范围”。它们是正常流程分支，不应打 ERROR 日志，更不该触发监控告警

一个典型反例：

if err := db.QueryRowContext(ctx, sql, id).Scan(&user); err != nil {
    // ❌ 把数据库查询失败（系统错误）当成业务不存在（业务错误）
    if errors.Is(err, sql.ErrNoRows) {
        return fmt.Errorf("user not found") // 丢失了原始 err，掩盖了真实问题
    }
    return err // ✅ 其他数据库错误原样返回
}

正确做法是保留原始错误链，并用 errors.As 或 errors.Is 分离处理：

if err := db.QueryRowContext(ctx, sql, id).Scan(&user); err != nil {
    if errors.Is(err, sql.ErrNoRows) {
        return &UserNotFoundError{ID: id} // 显式构造业务错误
    }
    return fmt.Errorf("query user %s: %w", id, err) // 包裹系统错误，保留栈信息
}

为什么不能只用字符串匹配判断错误类型

靠 strings.Contains(err.Error(), "not found") 做判断，短期能跑通，长期必踩坑：

• 错误文案可能随版本更新被修改（比如从 “user not found” 改成 “user does not exist”）
• 多语言支持时文案动态变化，字符串匹配彻底失效
• 中间件或日志库可能重写错误信息（例如加 traceID 前缀），导致匹配失败
• 无法区分同文案不同语义的错误（如 “timeout” 可能是 HTTP 超时，也可能是 Redis 锁等待超时）

真正可靠的判断方式只有两个：

• 用 errors.Is(err, target) 检查是否为某个已知错误实例或其包装
• 用 errors.As(err, &target) 尝试类型断言，获取结构化错误数据

所以定义业务错误时，一定要让类型可识别、可比较、可包裹。

HTTP handler中怎么透传和序列化业务错误

Web 层是业务错误落地的关键出口。不能把 error 直接塞进 JSON 返回体，而要统一转换：

func (h *Handler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
    err := h.service.DoSomething(r.Context(), req)
    if err != nil {
        var be *BusinessError
        if errors.As(err, &be) {
            w.Header().Set("Content-Type", "application/json")
            w.WriteHeader(be.HTTPStatus())
            json.NewEncoder(w).Encode(map[string]string{
                "code": be.Code(),
                "msg":  be.Message(),
            })
            return
        }
        // 其他错误走系统错误流程（500 + 告警）
        http.Error(w, "Internal Server Error", http.StatusInternalServerError)
        log.Error("unhandled error", "err", err)
        return
    }
}

• 所有业务错误类型建议实现统一接口，如 BusinessError，含 Code()、Message()、HTTPStatus()
• 不要在 handler 里用 switch err.(type)，容易漏 case；用 errors.As 更安全
• 避免把原始错误详情（如 SQL 语句、堆栈）返回给前端，仅暴露必要提示

业务错误不是“不够格的错误”，而是经过设计的控制流分支。定义不清、混用、裸抛，都会让可观测性变差，也让排查变得依赖猜。

今天带大家了解了的相关知识，希望对你有所帮助；关于Golang的技术知识我们会一点点深入介绍，欢迎大家关注golang学习网公众号，一起学习编程~