Go中通过自定义BusinessError和SystemError接口区分业务异常与系统异常，结合errors.As类型断言、错误包装及中间件统一处理，实现可识别、可分类、可携带上下文的错误处理机制。
在 Go 中没有传统意义上的“异常”（如 Java 的 throw / catch），但可以通过自定义错误类型 + 接口判断 + 错误包装，清晰地区分业务异常（如“用户不存在”、“余额不足”）和系统异常（如数据库连接失败、网络超时）。关键在于：**让错误可识别、可分类、可携带上下文，且不破坏 Go 的错误处理习惯。**
定义两个基础错误接口，明确语义边界
用接口而非结构体来标识错误类型，更符合 Go 的组合思想，也便于后续扩展：
业务异常接口：
表示预期内、可被上层业务逻辑捕获并友好处理的错误（比如返回 HTTP 400）
type BusinessError interface {
error
IsBusinessError() bool // 显式标记
}
系统异常接口：
表示非预期、需记录日志、可能触发告警或降级的底层问题（比如返回 HTTP 500）
type SystemError interface {
error
IsSystemError() bool
}
实现具体错误类型，携带状态码与上下文
每个业务场景定义自己的错误结构，嵌入通用字段（如 code、message、traceID），同时实现对应接口：
- 业务错误示例（用户未找到）：
type UserNotFoundError struct {
Code int `json:"code"`
Message string `json:"message"`
TraceID string `json:"trace_id,omitempty"`
}
func (e *UserNotFoundError) Error() string {
return fmt.Sprintf("[BUSINESS:%d] %s (trace:%s)", e.Code, e.Message, e.TraceID)
}
func (e *UserNotFoundError) IsBusinessError() bool { return true }
// 构造函数保持简洁
func NewUserNotFound(traceID string) *UserNotFoundError {
return &UserNotFoundError{
Code: 40401,
Message: "user not found",
TraceID: traceID,
}
}
- 系统错误示例（数据库查询失败）：
type DBQueryError struct {
Err error `json:"-"`
Code int `json:"code"`
Message string `json:"message"`
TraceID string `json:"trace_id,omitempty"`
}
func (e *DBQueryError) Error() string {
return fmt.Sprintf("[SYSTEM:%d] %s: %v (trace:%s)",
e.Code, e.Message, e.Err, e.TraceID)
}
func (e *DBQueryError) IsSystemError() bool { return true }
func (e *DBQueryError) Unwrap() error { return e.Err } // 支持 errors.Is/As
func NewDBQueryError(err error, traceID string) *DBQueryError {
return &DBQueryError{
Err: err,
Code: 50001,
Message: "database query failed",
TraceID: traceID,
}
}
在 handler 或 service 层统一识别并响应
利用 errors.As 和 errors.Is 进行类型断言，避免字符串匹配或反射：
立即学习“go语言免费学习笔记（深入）”；
func handleUserRequest(ctx context.Context, userID string) (Response, error) {
user, err := userService.GetByID(ctx, userID)
if err != nil {
// 先尝试匹配业务错误（优先处理）
var be BusinessError
if errors.As(err, &be) {
return Response{Code: be.(*UserNotFoundError).Code, Msg: be.Error()}, nil
}
// 再匹配系统错误（记录日志 + 返回 500）
var se SystemError
if errors.As(err, &se) {
log.Error("system error", "err", err, "trace_id", se.(interface{ TraceID() string }).TraceID())
return Response{Code: 500, Msg: "internal server error"}, nil
}
// 兜底：未知错误，按系统错误处理
log.Warn("unknown error", "err", err)
return Response{Code: 500, Msg: "unknown error"}, nil
}
return Response{Code: 200, Data: user}, nil
}
进阶技巧：用错误工厂 + 中间件自动分类
避免重复写 errors.As 判断，可封装一个错误处理器：
- 定义统一错误响应结构
- 提供
HandleError(err)函数，内部自动识别类型并返回对应 HTTP 状态码和 body - 在 Gin/Fiber 等框架中注册全局错误中间件，对
c.Error()统一处理
例如 Gin 中间件片段：
func ErrorHandler() gin.HandlerFunc {
return func(c *gin.Context) {
c.Next()
if len(c.Errors) > 0 {
err := c.Errors.Last().Err
resp := errorhandler.Handle(err, c.GetString("trace_id"))
c.JSON(resp.StatusCode, resp.Body)
}
}
}
这样业务代码只需 c.Error(myErr)，无需关心如何响应。
