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 语句、堆栈）返回给前端，仅暴露必要提示
业务错误不是“不够格的错误”，而是经过设计的控制流分支。定义不清、混用、裸抛，都会让可观测性变差，也让排查变得依赖猜。
