如何使用Golang实现错误码与信息映射_统一管理错误响应_技术教程

推荐用错误码常量+映射表+封装响应结构三者结合的方式统一管理Go项目错误码与信息；定义自定义ErrorCode类型配合iota、构建errorCodeMsgMap映射表、封装APIResult响应结构及NewError等构造函数，并可选实现error接口支持上下文与堆栈。

在 Go 项目中，统一管理错误码与错误信息是提升 API 响应一致性、可维护性和国际化支持的关键。推荐用「错误码常量 + 映射表 + 封装错误响应结构」三者结合的方式实现，避免硬编码字符串或散落的 switch-case。

定义标准化错误码常量

使用自定义类型（如 ErrorCode）配合 iota 定义清晰、易检索的错误码，同时为每个码赋予语义化名称：

例如：

type ErrorCode int

const (
    Success ErrorCode = iota
    ErrInvalidParam
    ErrUserNotFound
    ErrUnauthorized
    ErrInternalServer
)

func (e ErrorCode) String() string {
    return errorCodeMsgMap[e]
}

构建错误码-消息映射表（支持多语言可选）

用 map 或结构体初始化静态映射，确保错误码与默认提示一一对应。若需国际化，可将 msg 替换为 key，再通过 i18n 包动态翻译：

基础单语言映射示例：

var errorCodeMsgMap = map[ErrorCode]string{
    Success:           "success",
    ErrInvalidParam:   "请求参数错误",
    ErrUserNotFound:   "用户不存在",
    ErrUnauthorized:   "未授权访问",
    ErrInternalServer: "服务内部错误",
}

小技巧：可在 init() 中校验所有码是否已注册，防止遗漏：

遍历所有 ErrorCode 常量，检查是否存在于 map 中
缺失时 panic 或记录 warning，便于 CI 阶段发现

封装统一错误响应结构与构造函数

定义标准响应结构（如 APIResult），并提供便捷方法快速生成带错误码和信息的响应：

type APIResult struct {
    Code    int         `json:"code"`
    Message string      `json:"message"`
    Data    interface{} `json:"data,omitempty"`
}

func NewSuccess(data interface{}) APIResult {
    return APIResult{Code: int(Success), Message: errorCodeMsgMap[Success], Data: data}
}

func NewError(errCode ErrorCode, data ...interface{}) APIResult {
    msg := errorCodeMsgMap[errCode]
    // 可选：支持格式化消息，如 NewError(ErrUserNotFound, "id=123")
    if len(data) > 0 {
        msg = fmt.Sprintf(msg, data...)
    }
    return APIResult{Code: int(errCode), Message: msg}
}

使用示例：

w.WriteHeader(http.StatusOK); json.NewEncoder(w).Encode(NewSuccess(user))
w.WriteHeader(http.StatusBadRequest); json.NewEncoder(w).Encode(NewError(ErrInvalidParam, "email 格式不合法"))

进阶：集成 error 接口，支持堆栈与上下文

若需保留错误链路（如日志追踪），可让 ErrorCode 实现 error 接口，并嵌入原始 error：

type AppError struct {
    Code    ErrorCode
    Message string
    Err     error // 原始底层错误（如 database/sql.ErrNoRows）
}

func (e *AppError) Error() string {
    if e.Err != nil {
        return fmt.Sprintf("%s: %v", e.Message, e.Err)
    }
    return e.Message
}

// 提供快捷构造函数
func E(errCode ErrorCode, err error) error {
    return &AppError{Code: errCode, Message: errorCodeMsgMap[errCode], Err: err}
}