4、错误码与HTTP状态码映射

在构建Go语言微服务或RESTful API时，业务错误码与HTTP状态码的映射是API契约的核心环节。错误的映射策略会导致客户端解析混乱、监控告警失真，甚至引发安全漏洞（如信息泄露）。本章将系统梳理常见HTTP状态码的语义边界，并给出可落地的映射策略与Go实现模式。

4.1 常见HTTP状态码语义边界

HTTP状态码按类别分为1xx（信息）、2xx（成功）、3xx（重定向）、4xx（客户端错误）、5xx（服务端错误）。在业务API中，最常使用的是2xx、4xx和5xx。下表列出核心状态码及其在业务错误码映射中的典型含义：

4.2 业务错误码与HTTP状态码映射策略

映射策略的核心原则是：HTTP状态码表达传输层语义（谁的问题），业务错误码表达领域层语义（什么问题）。两者是正交关系，但需要建立稳定的映射规则。

4.2.1 一对一映射

每个业务错误码唯一对应一个HTTP状态码。适用于错误类型清晰、边界固定的场景。例如：

• ErrUserNotFound (1001) → 404
• ErrInvalidParam (1002) → 400
• ErrTokenExpired (1003) → 401

4.2.2 多对一映射

多个业务错误码映射到同一个HTTP状态码。适用于同一类错误的不同细分原因。例如：

• ErrInsufficientBalance (2001) → 422
• ErrOrderStatusInvalid (2002) → 422
• ErrDuplicateTransaction (2003) → 409

4.2.3 层级映射（推荐）

将业务错误码设计为层级结构，高位表示HTTP状态码类别，低位表示具体错误。例如：

• 400001 → 400 (参数错误-必填字段缺失)
• 400002 → 400 (参数错误-格式不合法)
• 401001 → 401 (认证失败-Token过期)
• 403001 → 403 (权限不足-角色不匹配)
• 404001 → 404 (资源不存在-用户)
• 500001 → 500 (内部错误-数据库连接失败)

4.3 映射策略的Go实现模式

以下是一个基于层级映射策略的Go实现示例，包含错误码定义、映射函数和HTTP响应封装：

// errcode/errcode.go
package errcode

// 错误码定义：前两位为HTTP状态码，后四位为业务细分
type ErrCode int

const (
    // 4xx 客户端错误
    ErrParamRequired   ErrCode = 400001 // 必填字段缺失
    ErrParamFormat     ErrCode = 400002 // 参数格式错误
    ErrTokenExpired    ErrCode = 401001 // Token过期
    ErrPermissionDeny  ErrCode = 403001 // 权限不足
    ErrUserNotFound    ErrCode = 404001 // 用户不存在
    ErrOrderConflict   ErrCode = 409001 // 订单状态冲突

    // 5xx 服务端错误
    ErrDBConnection    ErrCode = 500001 // 数据库连接失败
    ErrServicePanic    ErrCode = 500002 // 服务panic
)

// 错误码对应的HTTP状态码映射表
var httpStatusMap = map[ErrCode]int{
    ErrParamRequired:  400,
    ErrParamFormat:    400,
    ErrTokenExpired:   401,
    ErrPermissionDeny: 403,
    ErrUserNotFound:   404,
    ErrOrderConflict:  409,
    ErrDBConnection:   500,
    ErrServicePanic:   500,
}

// ToHTTPStatus 根据错误码返回HTTP状态码
func ToHTTPStatus(code ErrCode) int {
    if status, ok := httpStatusMap[code]; ok {
        return status
    }
    // 默认返回500
    return 500
}

// 业务错误结构体
type BusinessError struct {
    Code    ErrCode `json:"code"`
    Message string  `json:"message"`
}

func (e *BusinessError) Error() string {
    return e.Message
}

// NewBusinessError 创建业务错误
func NewBusinessError(code ErrCode, msg string) *BusinessError {
    return &BusinessError{Code: code, Message: msg}
}

// middleware/response.go
package middleware

import (
    "encoding/json"
    "net/http"

    "yourproject/errcode"
)

// APIResponse 统一响应结构
type APIResponse struct {
    Code    int         `json:"code"`
    Message string      `json:"message"`
    Data    interface{} `json:"data,omitempty"`
}

// WriteError 写入错误响应
func WriteError(w http.ResponseWriter, bizErr *errcode.BusinessError) {
    httpStatus := errcode.ToHTTPStatus(bizErr.Code)
    w.Header().Set("Content-Type", "application/json; charset=utf-8")
    w.WriteHeader(httpStatus)

    resp := APIResponse{
        Code:    int(bizErr.Code),
        Message: bizErr.Message,
    }
    json.NewEncoder(w).Encode(resp)
}

// WriteSuccess 写入成功响应
func WriteSuccess(w http.ResponseWriter, data interface{}) {
    w.Header().Set("Content-Type", "application/json; charset=utf-8")
    w.WriteHeader(http.StatusOK)

    resp := APIResponse{
        Code:    0,
        Message: "success",
        Data:    data,
    }
    json.NewEncoder(w).Encode(resp)
}

4.4 映射策略的边界与安全考量

在Go服务中实施映射策略时，需要关注以下边界与安全规则：

• 禁止将5xx映射为4xx： 服务端内部错误（如数据库超时）不应伪装成客户端错误，否则会误导调用方重试或错误归因。
• 禁止将4xx映射为5xx： 客户端参数错误不应返回500，否则会触发服务端告警，造成运维噪音。
• 敏感信息过滤： 在映射为4xx或5xx响应前，必须过滤掉堆栈、SQL语句、内部IP等敏感信息。Go中可使用errors.Unwrap提取业务错误，丢弃底层实现细节。
• 限流与熔断的映射： 限流应返回429（Too Many Requests），熔断应返回503（Service Unavailable），两者不可混用。

4.5 映射策略的SVG架构图

下图展示了从HTTP请求到业务错误码映射的完整流程，包含请求入口、中间件、业务层、错误码映射表以及最终响应输出的关键节点：

4.6 常见映射错误与避坑指南