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