17370845950

Go 错误应避免硬编码字符串，须用自定义 LocalizableError 接口延迟翻译，MessageID 作纯标识符，i18n 资源按 JSON 结构支持占位符，响应体需同时返回 code、error_id 和 localized message。

错误信息不能硬编码字符串

Go 的 error 类型本质是接口，一旦用 errors.New("用户不存在") 或 fmt.Errorf("数据库连接失败: %w", err) 直接写死中文，后续国际化就只能靠反射或字符串替换——这两种方式在生产环境都不可靠，且破坏错误链和类型判断逻辑。

实操建议：

• 所有业务错误统一通过自定义 error 类型构造，例如 type AppError struct { Code string; MessageID string; Args []interface{} }
• MessageID 是纯标识符（如 "user_not_found"），不带语言、不带格式，只用于查表
• 避免在 error 实现中直接调用 i18n 翻译函数，否则会把语言上下文（locale）耦合进错误创建过程，导致同一错误在不同请求中翻译不一致

翻译时机必须延迟到 error 处理时

错误的生成和展示通常跨多个调用层级，比如 HTTP handler → service → repo。只有在最终响应前（如 middleware 或 handler 末尾）才明确知道当前请求的 Accept-Language 和用户偏好，这时才应做翻译。

实操建议：

• 定义可翻译的 error 接口：type LocalizableError interface { error; Localize(*i18n.Bundle) string }
• HTTP 中间件中注入 *i18n.Bundle（来自 go-i18n/i18n 或类似库），并调用 err.(LocalizableError).Localize(bundle)
• 对非本地化 error（如标准库 os.PathError），保持原样透传，不强行翻译；可加前缀标注来源，例如 "system_error: permission denied"

i18n 资源文件结构要支持嵌套与复用

错误消息常需动态参数（如用户名、资源 ID），且不同语言的语序差异大（如中文“用户 {name} 未找到”，日语可能是“{name} というユーザーは見つかりません”）。硬编码模板字符串会很快失控。

实操建议：

• 使用 go-i18n 的 JSON 格式，每个 MessageID 对应一个对象，支持 description 和带占位符的 translation：

{
  "user_not_found": {
    "description": "User with given name does not exist",
    "translation": "用户 {{.Name}} 不存在"
  }
}

• 调用时传入 map： bundle.Localize(&i18n.LocalizeConfig{MessageID: "user_not_found", TemplateData: map[string]interface{}{"Name": "alice"}})
• 避免在资源文件里写逻辑（如条件分支），复杂文案拆成多个独立 MessageID，由 Go 代码控制分支

HTTP 错误响应体需同时携带 code、id、localized message

前端不仅需要显示文案，还依赖 code 做逻辑判断（如跳转登录页），MessageID 用于埋点或 fallback，而 message 仅用于展示。三者缺一不可。

实操建议：

• 定义统一错误响应结构，例如：

type ErrorResponse struct {
  Code      int    `json:"code"`       // HTTP status or business code
  ErrorID   string `json:"error_id"`   // e.g. "user_not_found"
  Message   string `json:"message"`    // localized, ready-to-show
  RequestID string `json:"request_id,omitempty"`
}

• 不要把 Args 原样塞进响应体——存在敏感信息泄露风险（如密码、token）；只传脱敏后的键名（如 "user_id"），不传值
• 测试时用 bundle.MustGetMessage 替代 bundle.Localize，让缺失翻译直接 panic，避免上线后静默回退到英文

最容易被忽略的是错误链中底层 error 的 MessageID 可能被上层覆盖或丢失。如果 service 层 wrap 了 repo 层的 AppError，必须显式保留原始 MessageID 字段，而不是只保留 Error() 字符串。