SuperAPI AI 工具集

api-error-design

编程与开发

查看项目

更新于 10-16 08:44

技能介绍

用途:设计公共 API 在请求失败时返回什么——错误码分类法、错误信封、消息、重试信号与文档,目标让集成方仅凭响应即可自行定位并修复问题,减少支持工单。设计以 RFC 9457 为基准,避免各自定义错误格式或重定义 HTTP 状态码语义。

主要能力:先做澄清提问(REST/gRPC、新建还是改造、客户端已依赖哪些码与字段、消费者类型、是否存在分层失败原因、上线期限与迁移预算),再按工作流执行:审计现有错误面、选择分类法、采用错误信封、改写消息、设计可重试性信号、逐端点文档化并接入请求 ID 追踪。

分类法三选一:扁平码表、code/subcode 码表、domain/reason(Google AIP-193)。默认推荐 code/subcode;接口面小时降为扁平码表;跨 REST 与 gRPC 或多个服务共享时升为 domain/reason。纯 gRPC 面则删除前两种(其身份依赖绑定 HTTP 状态码),仅剩 domain/reason。无论何种形态,都需将客户端可能见到的每个错误码提前枚举并发布为单一参考文档。

信封:先选对 HTTP 状态码,再使用 application/problem+json 的 RFC 9457(取代 RFC 7807)字段 type、title、status、detail、instance,并通过扩展成员承载 code、errors 字段级明细、retryable、documentation_url、request_id;所有端点与状态码使用同一信封。需明确 400 与 422、401 与 403 的区别;拒绝部分错误响应,仅在批量或长时操作中允许逐项失败复用同一错误形态。

消息:人类可读、可操作、格式一致;命名字段、收到的值与违反的约束;使用平实、非指责、纠正性的措辞;4xx 表示调用方应停止并修改请求,5xx 表示应稍后重试或由提供方修复;可通过 documentation_url 指向目录条目而非塞入长段说明;本地化时 code 始终不翻译。

可重试信号:按状态划分,408、429、502、503、504 及部分 500 可重试,400、401、403、404、409、422 不可重试;最低信号为 429/503 上的 Retry-After 头,更丰富时在响应体给出 retry 对象,并始终包含 retryable 布尔值;500 语义模糊,应显式给出重试对象。

文档与稳定约定:在 OpenAPI responses 中枚举每个端点可能返回的状态与各错误码命名示例;每个 code 有稳定锚点供 documentation_url 指向;所有响应返回请求 ID 头(如 X-Request-ID)并在错误体 request_id 中回显。错误码属 API 契约,只增不改,新增码与可选字段可自由,不得改名、复用或删除已发布码,退役需走弃用机制,并设一个发布前的目录守门人。

适用场景:公共 REST API 的错误面设计、RFC 9457 迁移、针对支付类等分层失败领域的错误设计、错误消息改写与文档化审计。限制:纯 gRPC 面无法使用绑定 HTTP 状态码的分类法;GraphQL 的错误形态由同系列的另一技能负责;其他未在本资料中说明的实现细节暂未提供。