weichenandCursor
bd53e9ba79
Services can resolve legacy aliases and expose the catalog over CLI and HTTP instead of ad-hoc error strings. Co-authored-by: Cursor <cursoragent@cursor.com>
37 lines
1.4 KiB
Markdown
37 lines
1.4 KiB
Markdown
# 错误码注册治理
|
|
|
|
Go 定义是唯一权威来源，位于 `domains/`。JSON 文件是导出物，供服务查询、CLI 导出和跨语言消费。
|
|
|
|
## 新增一条码
|
|
|
|
1. 在 `errcode/codes.go` 增加 `Code` 常量。
|
|
2. 在对应域的 `register*` 中登记 HTTP、严重级别、重试、副作用、中文摘要与处置建议。
|
|
3. 若承接旧字符串，把它写成 `Aliases`，不要新造一套平行码。
|
|
4. 运行 `go test ./...`。目录一致性测试会失败，按测试输出重新导出 JSON：
|
|
|
|
```bash
|
|
WRITE_CATALOG=1 go test ./domains -run TestWriteCatalog -count=1
|
|
```
|
|
|
|
5. 更新 `docs/` 中对应系统的映射表。
|
|
|
|
## 不变量
|
|
|
|
- 规范码全局唯一；别名不得指向两个码，也不得与规范码同形冲突。
|
|
- 已发布的规范码只追加别名或澄清文案，不改变码字符串的含义。含义变化时新增码，旧码保留为别名或标记在映射表中。
|
|
- 副作用为 `possible` 或 `unknown` 的码，默认重试不得是 `always`。
|
|
- 种子数据在进程启动时登记。登记失败直接 panic，避免带着残缺目录对外服务。
|
|
|
|
## 自定义域
|
|
|
|
产品可以不改本仓库，在运行期加载 JSON：
|
|
|
|
```go
|
|
reg := errcode.NewRegistry()
|
|
domains.RegisterAll(reg)
|
|
data, _ := os.ReadFile("product.json")
|
|
if err := reg.LoadJSON(data); err != nil { /* 本批回滚 */ }
|
|
```
|
|
|
|
JSON 可以是数组，或 `{"codes":[...]}`。本批任一记录不合法时，整批回滚。
|