2、错误码设计原则：HTTP 状态码与业务错误码的区别、错误码分段规则、错误码可读性设计

在构建 GoBFF（Go Backend For Frontend）层时，错误码设计是接口契约中最容易被忽视却又影响最大的环节。一个设计良好的错误码体系，能让前端断言、监控告警、问题排查都变得清晰高效；反之，混乱的错误码会导致前端逻辑臃肿、后端定位困难。本章从三个核心维度展开：HTTP 状态码与业务错误码的职责分离、错误码分段规则、错误码可读性设计。

2.1 HTTP 状态码与业务错误码的区别

很多团队在早期直接将 HTTP 状态码当作业务错误码使用，例如用 400 表示“参数错误”，用 500 表示“服务内部错误”。这种做法在单体应用时代尚可接受，但在微服务 + BFF 架构下会带来严重问题：HTTP 状态码只描述传输层的语义，而业务错误码描述应用层的具体错误原因。

2.2 错误码分段规则

业务错误码通常是一个整数或字符串，为了便于管理和快速定位，需要按照分段规则进行设计。推荐使用 6 位数字码，分为三段：AB C DDD。

2.3 错误码可读性设计

错误码不仅要让机器能解析，更要让人能快速理解。可读性设计包含三个层面：错误消息模板、错误码与消息的映射、国际化支持。

2.3.1 错误消息模板

每个错误码对应一个固定的消息模板，模板中可包含占位符用于动态填充上下文信息。例如：

// GoBFF 错误码定义示例
type BizError struct {
    Code    int    `json:"code"`
    Message string `json:"message"`
    Detail  string `json:"detail,omitempty"`
}

// 错误码常量
const (
    ErrUserNotFound      = 103001 // 用户不存在
    ErrOrderAlreadyPaid  = 204002 // 订单已支付
    ErrInsufficientStock = 305001 // 库存不足
)

// 错误消息映射
var errorMessages = map[int]string{
    ErrUserNotFound:      "用户不存在",
    ErrOrderAlreadyPaid:  "订单 %s 已支付，请勿重复操作",
    ErrInsufficientStock: "商品 %s 库存不足，当前剩余 %d 件",
}

2.3.2 错误码与消息的映射

在 GoBFF 层，建议使用 集中式错误码注册表，所有错误码在启动时加载到内存中，避免每次请求都查询数据库或配置文件。前端 SDK 也可以同步维护一份精简的错误码映射表，用于本地化提示。

2.3.3 国际化支持

BFF 层通常需要面向多语言前端。错误码本身不携带语言信息，但 message 字段应根据请求头中的 Accept-Language 动态返回对应语言版本。Go 中可以使用 golang.org/x/text 或自定义的 locale 映射表实现。

// 国际化错误消息示例
var errorMessagesI18n = map[int]map[string]string{
    ErrUserNotFound: {
        "zh-CN": "用户不存在",
        "en-US": "User not found",
        "ja-JP": "ユーザーが見つかりません",
    },
    ErrOrderAlreadyPaid: {
        "zh-CN": "订单 %s 已支付，请勿重复操作",
        "en-US": "Order %s has been paid, do not repeat",
        "ja-JP": "注文 %s は既に支払われています",
    },
}