用途:为 API 或模块设计错误分类体系(error taxonomy),统一决定错误该抛出什么、映射到哪个状态码、消息是否暴露给客户端、是否可重试;也用于审查抛出点与 catch 块。
主要能力:定义一组封闭的错误种类,每个种类在设计时一次性确定三个属性——传输映射(如 HTTP 状态码,也可映射到 gRPC 状态码、CLI 退出码、库的公开异常类型)、消息是否暴露、是否可重试。分类在抛出点完成,状态码、可见性、重试等后果由种类机械推导。示例种类包括 validation、precondition、not_found、conflict、authn/authz、throttled、configuration、infrastructure、internal。两条关键规则:可重试性由一个共享策略从种类推导,重试循环、死信决策、工作流引擎共用同一分类器;消息暴露是安全边界,服务端故障类隐藏消息,调用方故障类暴露且消息需可操作。
分类判定:问“正确的服务器是否仅因调用方请求而遇到此错误、调用方能否通过修改请求修复”——是则为调用方类,否则为服务端类;internal 只保留给真正的不变量守卫,一旦触发应修 bug 而非让客户端绕过。
用法:调用方不得对消息做字符串匹配,错误应携带稳定的机器可读 code。对已有代码库的落地是先调查后重构,可用 scripts/error_census.py 统计抛出点及其种类;详细分类走查见 references/classification-walkthrough.md,落地流程见 references/rollout.md。
限制:资料未提供该技能的具体安装命令、支持的平台、收费与价格信息。