stripe-inspired-api-design-rules

Stripe 启发的 API 设计最佳实践

本文提炼了 Stripe API 背后的设计惯例——这是业内最受推崇、也最常被仿效的 JSON HTTP API。包含 8 个类别中的 52 条可执行规则，并按错误决策对每个端点、每个 SDK 和每项客户端集成造成的连锁影响是否不可逆进行优先级排序。每条规则都解释了原因、展示了错误与正确的代码示例，并链接到权威来源。

适用场景

遇到以下情况时，可参考这些规则：

• 设计新的 JSON HTTP API，或为现有 API 添加新端点
• 审查 API 设计提案、OpenAPI 规范，或新增／更改端点的 PR
• 排查集成问题，其中 API 的“错误”结构导致了客户端问题
• 审核 API 的命名一致性、错误结构统一性或兼容性风险
• 编写 API 设计报告（即检查工具生成的那类报告——Critical / Warning / Suggestion / Positive）
• 在两种设计方案之间做选择，并寻找权威来源作为依据
• 开始学习 API 设计——这些是应优先掌握的经典模式

这些规则具有通用性，适用于任何 JSON HTTP API，而不仅是仿照 Stripe 的 API。相关关键词包括“API design”“OpenAPI”“endpoint”“schema”“webhook”“idempotency”“pagination”“API versioning”，以及对 YAML／JSON 规范文件的审查。

按优先级划分的规则类别

优先级	类别	影响	前缀
1	资源建模与标识符	CRITICAL	resource-
2	URL 结构与 HTTP 语义	CRITICAL	url-
3	请求与响应格式	HIGH	format-
4	错误与状态码	HIGH	error-
5	幂等性与安全重试	HIGH	idem-
6	版本控制与向后兼容性	HIGH	ver-
7	命名、多态与元数据	MEDIUM-HIGH	naming-
8	身份验证、Webhook 与搜索	MEDIUM-HIGH	ops-

靠前的类别会产生更严重的连锁影响：资源建模中的错误选择（数值 ID、没有 object 判别字段）会永久影响每个端点；Webhook 事件命名中的错误选择，则只需修正一个类别。

快速参考

1. 资源建模与标识符（CRITICAL）

• resource-prefixed-string-ids — 为每个资源使用带前缀的字符串 ID
• resource-object-discriminator — 为每个资源添加只读的 object 判别字段
• resource-opaque-ids — 将 ID 视为不透明字符串，长度最多为 255 个字符
• resource-unix-seconds-timestamps — 所有日期时间均使用 Unix 秒数（整数）
• resource-iso-date-only — 仅表示日期的值使用 ISO 8601 日期字符串
• resource-birthdate-hash — 将出生日期表示为 {day, month, year} 哈希
• resource-integer-minor-units — 金额使用整数最小货币单位，绝不使用浮点数
• resource-currency-field-not-name — 将 currency 字段与金额字段放在一起；不要将货币写入字段名
• resource-decimal-suffix-strings — 对无法用整数表示的精确小数，使用带 _decimal 后缀的字符串

2. URL 结构与 HTTP 语义（关键）

• url-plural-collections — 集合 URL 使用复数形式；对象类型使用单数形式
• url-post-for-updates — 使用 POST 进行更新（而非 PUT 或 PATCH）
• url-action-verbs-as-subpaths — 将非 CRUD 操作表示为祈使式子路径
• url-no-bulk-endpoints — 每个请求处理一个对象——不提供批量端点
• url-version-in-path-and-header — 在 URL 路径和 Stripe-Version 标头中指定版本
• url-dedicated-search-endpoint — 复杂查询使用专用的 /search 端点

3. 请求与响应格式（高）

• format-form-encoded-requests — 接受表单编码的请求，始终返回 JSON
• format-bracket-notation-nesting — 在表单请求体中使用方括号表示法指定嵌套字段
• format-list-envelope — 使用 {object, url, has_more, data} 封装列表
• format-cursor-pagination — 使用游标分页（starting_after/ending_before），而非偏移量
• format-no-total-counts — 使用 has_more 布尔值；绝不返回总数
• format-expand-parameter — 使用 expand[] 在一次往返中展开相关对象
• format-dot-notation-expansion — 支持使用点号表示法进行嵌套展开（最大深度为 4）

4. 错误与状态码（高）

• error-top-level-object — 始终使用顶层 error 对象封装失败
• error-four-type-enum — 使用固定的少量 type 枚举值，不要不断增加类型
• error-message-mandatory-code-optional — 必须提供 message；code 可选，且仅用于程序化处理
• error-lowercase-snake-case-codes — 错误代码使用小写 snake_case，而非 SCREAMING_SNAKE_CASE
• error-http-status-mapping — 一致地将错误类型映射到 HTTP 状态码
• error-doc-url-on-every-error — 每个错误都包含 doc_url 链接和请求 ID

5. 幂等性与安全重试（高）

• idem-key-header — 所有变更请求都接受 Idempotency-Key 标头
• idem-scoped-per-account — 幂等键按账户划分作用域，而非全局共享
• idem-24h-ttl — 幂等键保留 24 小时，并在 72 小时后清理
• idem-fail-on-key-reuse — 使用相同键提交不同参数时返回 409
• idem-recovery-points — 多步骤幂等操作使用恢复点

6. 版本控制与向后兼容性（高）

• ver-dated-versions — 使用日期格式版本（YYYY-MM-DD），而非 v1/v2/v3
• ver-account-pinning — 将每个账户固定到其首次请求使用的版本
• ver-additive-changes — 明确定义哪些变更属于向后兼容变更
• ver-version-change-modules — 将每项破坏性变更封装在版本变更模块中
• ver-tolerate-unknown — 说明客户端必须容忍未知字段、事件和枚举值

7. 命名、多态与元数据（中高优先级）

• naming-snake-case-wire-format — 所有线上标识符均使用 snake_case
• naming-american-english — 使用美式英语拼写（canceled，而非 cancelled）
• naming-simple-unambiguous — 名称应简单明确、不以数字开头、不使用行话
• naming-type-discriminator-polymorphism — 使用 type 字段和同级对象区分多态类型
• naming-metadata-pattern — 提供限制严格的 metadata 透传字段
• naming-boolean-past-tense — 布尔值使用过去时动词和简单形容词，而非 is_/has_ 前缀
• naming-enums-over-booleans — 新增状态/标志字段时，优先使用枚举而非布尔值

8. 身份验证、Webhook 与搜索（中高优先级）

• ops-prefixed-api-keys — 为 API 密钥添加范围和模式前缀（sk_live_、pk_test_、rk_）
• ops-https-only-basic-auth — 强制仅使用 HTTPS，并以密钥作为用户名进行 HTTP Basic 身份验证
• ops-on-behalf-of-header — 多租户调用使用专用的 On-Behalf-Of 标头
• ops-webhook-event-envelope — Webhook 事件使用固定的 {id, object, type, data, created} 信封
• ops-webhook-event-naming — 事件类型命名格式：<resource>.<past_tense_action>
• ops-webhook-signature — 使用 HMAC 和时间戳容差窗口为 Webhook 投递签名
• ops-webhook-at-least-once-handlers-idempotent — 说明至少一次投递；处理程序必须根据 event.id 去重

使用方法

对于聚焦的问题（“这个字段应该是布尔值还是枚举？”），请直接查看相关规则（naming-enums-over-booleans）——每条规则均独立成篇，包含原因、代码示例和权威来源。

对于完整的 API 评审或审计，请按类别从上到下逐项检查。顺序与 Stripe 自身的设计优先级一致：首先正确设计资源模型和 URL 结构；接下来处理格式、错误、幂等性和版本控制；最后处理命名和运维接口，因为这些最容易演进。

要生成结构化的发现报告（例如检查工具生成的报告），请使用规则的 slug 引用规则——resource-unix-seconds-timestamps、format-no-total-counts——这样每项发现都能追溯到具体且可靠的来源。

阅读章节定义，了解类别排序背后的级联影响理由；添加新规则时，请参阅规则模板。

参考文件

文件	描述
references/_sections.md	类别定义，以及按设计传播影响排序的类别
assets/templates/_template.md	编写新规则的模板
metadata.json	版本和参考 URL
gotchas.md	应用这些规则时发现的易错点