小游戏平台错误码规范（扩展工程版）

1. 错误码分层设计

为了便于定位和统一管理，可以采用 分层 + 分模块 的设计：

1.1 分层

• 前端层错误（1xx）：网络错误、版本不兼容、SDK 调用失败
• 服务端业务错误（2xx）：用户、游戏、广告、支付、风控等业务逻辑错误
• 系统级错误（5xx）：服务器异常、数据库/缓存不可用
• 第三方依赖错误（3xx）：支付通道、CDN、云存储、广告平台

1.2 分模块（业务域划分）

同前面约定：用户(01)、游戏(02)、支付(03)、广告(04)、开发者(05)、数据(06)、风控(07)、系统(99)

2. SDK 与前端错误处理规范

2.1 错误码统一封装

SDK 内部调用 API 后，必须返回统一格式：

{
  "code": 201002,
  "message": "Token 无效或已过期",
  "detail": "jwt signature invalid",
  "trace_id": "xyz-123-456",
  "timestamp": "2025-09-27T10:20:30Z",
  "i18n": {
    "en": "Token is invalid or expired",
    "jp": "トークンが無効または期限切れです"
  }
}

• 前端：展示 message（或根据 i18n 选择语言）
• SDK：上报 trace_id 到监控系统，便于后端追踪

2.2 错误分级提示

• 用户可感知错误（如密码错误、余额不足） → 明确提示
• 用户无感知错误（如埋点上报失败） → 静默处理或延迟重试
• 安全敏感错误（如风控封禁、支付校验失败） → 模糊提示（避免暴露系统逻辑）

3. 日志与监控联动

3.1 Trace ID 贯通

• 每个请求分配一个 trace_id（UUID/雪花算法）
• 前端/SDK → API 网关 → 微服务 → 数据存储，全链路携带
• 出错时，错误码与 trace_id 必须写入日志，方便 ELK/监控系统查询

3.2 指标监控

• 每个错误码必须在监控系统（Prometheus + Grafana）建立监控指标
• 示例：

rate(error_count{code="203003"}[5m])

👉 可实时监控「支付回调签名验证失败」的频率，快速发现第三方攻击或接入问题。

3.3 告警规则

• 系统级错误（5xx）出现 ≥ 100 次/分钟 → 触发告警
• 业务错误（2xx）出现异常峰值（超过日常均值 3 倍） → 触发告警
• 支付/广告相关错误必须进入 SLA 监控（直接影响收入）

4. 错误码维护流程

4.1 错误码申请

• 新功能开发 → 开发人员在「错误码文档」中申请错误码
• 由 架构组/后端组长 审核，确保不冲突

4.2 错误码文档

• 错误码需统一维护在 Markdown 文档 / Swagger API 文档 / 内部 Wiki

• 每个错误码必须包含：

  • 编码
  • Message（中文/英文/日文多语言）
  • 场景说明
  • HTTP 状态码
  • 解决方案（运维手册中体现）

4.3 错误码版本管理

• 使用 Git 仓库维护 errors.yaml 或 errors.json 文件
• CI/CD 流程校验错误码是否重复
• SDK 自动拉取最新错误码（生成本地映射文件）

5. 错误码分类示例（细化）

5.1 用户模块

5.2 游戏模块

5.3 支付模块

5.4 广告模块

6. 最佳实践建议

• 错误码分配范围（例如用户模块 201000–201999）
• SDK 内置错误映射表（开发者不需要背数字）
• 自动化测试覆盖率（确保每个错误码有测试用例）
• SLA 指标：对支付/广告错误码单独统计成功率，保证收入稳定

总结

小游戏平台的错误码规范需要做到：

• 模块化（不同业务域独立编号）
• 分层次（系统/业务/第三方）
• 可国际化（支持多语言提示）
• 可追踪（trace_id 全链路追踪）
• 可运维（日志+监控+告警联动）
• 可管理（文档化+版本化+自动校验）

这样既能满足 用户体验，也能保证 研发和运维效率。