Documentation
¶
Overview ¶
Package codes 维护 i18n 错误码注册表。所有 user-visible 错误码都必须在此 通过 Register 登记，AST extractor 以 Register 为唯一数据源生成 goi18n message marker（D18）。
设计要点：
- ID 是稳定的 i18n key（如 "err.shared.auth.required"），全局唯一， 运行期通过 Lookup 检索；Register 检测到重复 ID 直接 panic（启动期问题）。
- DefaultMessage 是 source（en-US）文案，AST extractor 输出到 active.en-US.toml。
- DefaultMessages 仅作极端故障兜底（缺译 + go-i18n bundle 加载失败）； 正常运营依赖 bundle 里的 translate.<lang>.toml，不要塞业务文案到这里。
- SafeDetailKeys 是 details 字段白名单——renderer 渲染时只透传白名单内的 key， 防止业务层不小心把 uid/token/raw_err 泄露给客户端。
- Internal=true 标记 5xx 一类错误；renderer 看到 Internal=true 时输出 占位文案，避免内部 message 泄露给客户端（D11/D13）。
调用顺序约定：codes 包通过 init() 注册；errcode 包同样在 init() 注册业务码； init 顺序由 Go 包依赖图决定（registry → shared → server），重复注册 panic 保证开发期立刻发现冲突。
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
Types ¶
type Code ¶
type Code struct {
ID string
HTTPStatus int
DefaultMessage string
DefaultMessages map[string]string
SafeDetailKeys []string
Internal bool
}
Code 描述一个稳定 i18n 错误码及其元信息。
字段语义：
- ID: 全局唯一稳定 key，如 "err.shared.auth.required"。
- HTTPStatus: canonical HTTP status（401/403/429/...）。兼容期内 renderer 可能把响应头固定为 400（D14），但 error.http_status body 字段 仍暴露真值。
- DefaultMessage: source 文案（en-US），AST extractor 生成的 message marker 用它做 Other 字段；运行期当 bundle 缺译时也用它做最后兜底。
- DefaultMessages: 极端故障兜底（bundle 加载失败 / 全部 lang 缺译时使用）。 key 是 BCP-47 lang tag，如 "zh-CN"。
- SafeDetailKeys: ResponseErrorL 调用方传入 details 时，renderer 只透传 此列表内的 key；其余键被丢弃并记 i18n_unsafe_details_dropped_total。
- Internal: 5xx 类错误标记。renderer 看到时不输出 spec.DefaultMessage， 改用「服务器内部错误」之类占位文案。
Source Files
Click to show internal directories.
Click to hide internal directories.