「小游戏服务平台」错误码规范（落地实现版）

小游戏平台错误码规范（落地实现版）

1. errors.yaml 配置文件模板

统一在仓库中维护错误码：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47

# errors.yaml
system:
  - code: 10001
    http: 500
    message: "系统错误，请稍后再试"
    i18n:
      en: "System error, please try again later"
      jp: "システムエラー、後でもう一度試してください"
    detail: "Unknown error"
  - code: 10002
    http: 400
    message: "请求参数无效"
    i18n:
      en: "Invalid request parameter"
      jp: "無効なリクエストパラメータ"
    detail: "Validation error"

user:
  - code: 201001
    http: 401
    message: "用户名或密码错误"
    i18n:
      en: "Incorrect username or password"
    detail: "Auth failed"

  - code: 201002
    http: 401
    message: "Token 无效或已过期"
    i18n:
      en: "Token is invalid or expired"
    detail: "JWT validation failed"

game:
  - code: 202002
    http: 400
    message: "游戏包大小超过限制"
    i18n:
      en: "Game package size exceeds limit"
    detail: "File size > 500MB"

payment:
  - code: 203003
    http: 400
    message: "回调签名验证失败"
    i18n:
      en: "Payment callback signature verification failed"
    detail: "Signature mismatch"

👉 好处：

  • 可读性强
  • 版本化管理（Git 控制）
  • 多语言内置
  • CI/CD 可以校验是否有重复错误码

2. SDK / 后端错误码加载示例

Go 后端示例

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44

package errors

import (
    "encoding/json"
    "io/ioutil"
)

type ErrorCode struct {
    Code    int               `json:"code"`
    Http    int               `json:"http"`
    Message string            `json:"message"`
    I18n    map[string]string `json:"i18n"`
    Detail  string            `json:"detail"`
}

var errorMap = map[int]ErrorCode{}

func LoadErrorCodes(path string) error {
    data, err := ioutil.ReadFile(path)
    if err != nil {
        return err
    }
    var raw map[string][]ErrorCode
    if err := json.Unmarshal(data, &raw); err != nil {
        return err
    }
    for _, codes := range raw {
        for _, e := range codes {
            errorMap[e.Code] = e
        }
    }
    return nil
}

func GetError(code int, lang string) (int, string) {
    e, ok := errorMap[code]
    if !ok {
        return 500, "Unknown error"
    }
    if msg, ok := e.I18n[lang]; ok {
        return e.Http, msg
    }
    return e.Http, e.Message
}

使用示例

1
2
3

httpCode, msg := errors.GetError(201002, "en")
// httpCode = 401
// msg = "Token is invalid or expired"

JavaScript SDK 示例

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

import errorConfig from "./errors.json";

export function getError(code, lang = "zh") {
  const err = errorConfig[code];
  if (!err) return { http: 500, message: "未知错误" };
  return {
    http: err.http,
    message: err.i18n?.[lang] || err.message,
  };
}

// 使用示例
const err = getError(201002, "en");
console.log(err.message); // Token is invalid or expired

3. 错误码文档自动生成

可以通过 脚本将 errors.yaml 自动生成 Markdown/HTML 文档，避免人工维护：

生成 Markdown 示例

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

# errors2doc.py
import yaml

with open("errors.yaml", "r", encoding="utf-8") as f:
    data = yaml.safe_load(f)

with open("ERRORS.md", "w", encoding="utf-8") as f:
    for module, codes in data.items():
        f.write(f"## {module}\n\n")
        f.write("| Code | HTTP | Message | EN | JP |\n")
        f.write("|------|------|---------|----|----|\n")
        for c in codes:
            f.write(f"| {c['code']} | {c['http']} | {c['message']} | {c['i18n'].get('en','')} | {c['i18n'].get('jp','')} |\n")
        f.write("\n")

执行后会生成一份 ERRORS.md，供团队直接阅读。

4. 错误码最佳实践 checklist ✅

  • 全局唯一性：通过 CI 校验错误码不重复
  • 国际化：支持至少中/英多语言
  • 多层日志：前端 → SDK → API 网关 → 微服务，全链路带 trace_id
  • 自动化生成：从 errors.yaml 自动生成 SDK 映射 & 文档
  • 分级提示：用户可感知 / 无感知 / 安全敏感
  • 监控告警：关键错误码建立 Prometheus 告警（支付、广告）

📌 总结

小游戏平台的错误码规范最终落地方式是：

  • 集中管理（errors.yaml）
  • 全链路一致（前端/SDK/后端同一套标准）
  • 国际化支持（多语言 Message）
  • 自动化文档（避免手工更新冲突）
  • 监控联动（关键错误码告警）

这样既能保证 研发效率，又能满足 运维与产品合规需求。