Golang错误分类实现与分级错误体系构建

错误处理在Golang中应通过分级错误体系提升可维护性与可观测性。1. 错误需分类以区分类型、统一错误码、便于日志记录与监控；2. 设计包含Code、Message、Cause字段的AppError结构体，并提供构造函数及包装函数；3. 根据严重程度将错误分为业务错误、系统错误、内部错误，并添加Level字段标识级别；4. 统一Web服务错误响应格式，通过中间件将AppError转换为标准JSON输出。构建该体系的关键在于结构统一、分层明确、封装合理与输出一致。

在 Golang 项目中，错误处理往往容易变得杂乱无章，特别是当系统复杂度上升时。如果只是简单地用 error 类型返回错误信息，会很难区分错误类型、追踪问题来源，也不利于对外暴露统一的错误码体系。因此，构建一个带错误码的分级错误体系，是提升代码可维护性和服务可观测性的重要一步。

错误为什么要分类

Golang 的原生错误机制简洁但不够结构化。如果不做分类，所有错误都只是一个字符串或简单的 error 类型，就难以做到：

• 快速判断错误类型（比如是否需要重试）
• 统一返回给前端或调用方的错误格式
• 日志中更清晰地记录错误等级和上下文
• 实现自动化的告警、监控等机制

所以，我们需要一种方式，让错误本身携带更多信息，尤其是错误码、错误级别和原始错误上下文。

如何设计带错误码的错误结构

一个实用的错误结构体通常包含以下字段：

type AppError struct {
    Code    int
    Message string
    Cause   error
}

其中：

• Code 是整数类型的错误码，用于外部系统识别错误种类。
• Message 是对错误的简要描述，方便日志和调试。
• Cause 是原始错误，便于链式追踪。

例如，数据库连接失败可以定义为：

var ErrDatabaseConnection = &AppError{
    Code:    1001,
    Message: "数据库连接失败",
}

你还可以封装一个构造函数来创建错误：

func NewError(code int, message string) *AppError {
    return &AppError{
        Code:    code,
        Message: message,
    }
}

或者带上下文包装功能：

func WrapError(err error, code int, message string) *AppError {
    return &AppError{
        Code:    code,
        Message: message,
        Cause:   err,
    }
}

这样在调用链中可以层层包装错误，又不丢失原始信息。

错误的分级与使用场景

我们可以根据错误的严重程度进行分级，比如分为：

• 业务错误：用户输入不合法、权限不足等，这类错误通常不需要打报警日志。
• 系统错误：数据库连接失败、网络超时等，可能影响整个服务运行。
• 内部错误：程序逻辑错误、空指针等，属于 bug 级别。

对应的错误结构可以加上一个 Level 字段：

type AppError struct {
    Code    int
    Message string
    Cause   error
    Level   string // 比如 "info", "warn", "error"
}

然后根据不同级别决定是否上报、是否触发监控告警等。

举个实际例子：

if err != nil {
    wrappedErr := WrapError(err, 2001, "获取用户信息失败")
    log.Printf("[ERROR] %v", wrappedErr)
    return wrappedErr
}

在日志里就能看到完整的错误信息，同时也能提取 Code 做进一步处理。

配合 HTTP 响应统一输出格式

如果你开发的是 Web 服务，建议统一错误响应格式。比如返回 JSON 结构如下：

{
  "code": 2001,
  "message": "获取用户信息失败",
  "error": "具体错误信息（可选）"
}

你可以写一个中间件或工具函数，将 *AppError 转换成这种格式返回给客户端：

func WriteErrorResponse(w http.ResponseWriter, err *AppError) {
    w.WriteHeader(http.StatusInternalServerError)
    json.NewEncoder(w).Encode(map[string]interface{}{
        "code":    err.Code,
        "message": err.Message,
        "error":   err.Cause.Error(),
    })
}

这样前端或其他服务就可以统一解析错误码并做出相应处理。

基本上就这些。构建一个带错误码的错误体系并不复杂，但能大大提升系统的可维护性和可观测性。关键在于统一结构、分层设计、合理封装和统一输出。