小游戏平台错误码规范（落地实现版）
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 ✅
📌 总结
小游戏平台的错误码规范最终落地方式是：
- 集中管理（
errors.yaml）
- 全链路一致（前端/SDK/后端同一套标准）
- 国际化支持（多语言 Message）
- 自动化文档（避免手工更新冲突）
- 监控联动（关键错误码告警）
这样既能保证 研发效率，又能满足 运维与产品合规需求。