3. 领域错误码设计原则：业务语义优先、可枚举、可扩展、可国际化

领域错误码是领域边界断言失败后的第一道“可读防线”。在 Go 语言中，错误码的设计质量直接决定了调用方能否快速定位问题、运维能否自动化告警、国际化团队能否协同排查。本章围绕四个核心原则展开：业务语义优先、可枚举、可扩展、可国际化。

3.1 业务语义优先：错误码应直接反映领域行为

传统 HTTP 状态码（如 400、500）只能表达“请求错误”或“服务器错误”，无法区分“订单金额超限”与“用户余额不足”。领域错误码必须携带业务含义。

// 业务语义错误码定义
type DomainErrorCode string

const (
    ErrOrderAmountExceedsLimit DomainErrorCode = "ORDER_AMOUNT_EXCEEDS_LIMIT"
    ErrUserBalanceInsufficient DomainErrorCode = "USER_BALANCE_INSUFFICIENT"
    ErrProductOutOfStock       DomainErrorCode = "PRODUCT_OUT_OF_STOCK"
)

// 断言函数返回带语义的错误码
func AssertOrderAmount(amount, limit float64) error {
    if amount > limit {
        return &DomainError{
            Code:    ErrOrderAmountExceedsLimit,
            Message: fmt.Sprintf("订单金额 %.2f 超出单笔限额 %.2f", amount, limit),
        }
    }
    return nil
}

3.2 可枚举：所有错误码必须在编译期可见

可枚举意味着错误码集合在代码库中是封闭的、可穷举的。Go 语言中推荐使用 const + 自定义类型实现编译期检查，避免运行时字符串拼写错误。

// 推荐做法：自定义类型 + const 枚举
type OrderErrorCode string

const (
    OrderAmountExceeds OrderErrorCode = "ORDER_AMOUNT_EXCEEDS"
    OrderAlreadyPaid   OrderErrorCode = "ORDER_ALREADY_PAID"
    OrderNotFound      OrderErrorCode = "ORDER_NOT_FOUND"
)

// 编译期检查示例
func handleError(code OrderErrorCode) {
    switch code {
    case OrderAmountExceeds:
        // 业务处理
    case OrderAlreadyPaid:
        // 业务处理
    default:
        // 编译期不会漏掉新增枚举
    }
}

3.3 可扩展：错误码体系支持版本演进

业务系统会持续迭代，错误码必须支持向后兼容的扩展。设计时需考虑：

• 命名空间隔离：不同领域（订单、支付、库存）使用独立前缀，如 ORDER_、PAY_、STOCK_。
• 版本号嵌入：对于重大变更，可在错误码中嵌入版本标识，如 V2_ORDER_AMOUNT_EXCEEDS。
• 保留区间：为每个领域预留 20% 的编码空间，避免未来重构时重新编号。

3.4 可国际化：错误消息与错误码分离

错误码本身是语言无关的标识符，而错误消息需要支持多语言。设计上必须将“码”与“消息”解耦：

// 错误码定义（语言无关）
type I18nErrorCode string

const (
    ErrOrderAmountExceeds I18nErrorCode = "ORDER_AMOUNT_EXCEEDS"
)

// 国际化消息映射
var i18nMessages = map[string]map[I18nErrorCode]string{
    "zh-CN": {
        ErrOrderAmountExceeds: "订单金额 %v 超出单笔限额 %v",
    },
    "en-US": {
        ErrOrderAmountExceeds: "Order amount %v exceeds single limit %v",
    },
}

// 断言函数：返回错误码 + 国际化消息
func AssertOrderAmountI18n(amount, limit float64, locale string) error {
    if amount > limit {
        msgTemplate := i18nMessages[locale][ErrOrderAmountExceeds]
        return &DomainError{
            Code:    ErrOrderAmountExceeds,
            Message: fmt.Sprintf(msgTemplate, amount, limit),
        }
    }
    return nil
}

3.5 四原则综合对比