企业 API 设计：一致性、版本管理、文档与速率限制，打造持久的集成

企业一旦开始连接自己的系统，无论是网店、移动应用、分销伙伴还是 ERP，就是在构建 API。API 是一份契约：一方承诺，某种形式的请求会得到某种形式的响应。当契约被单方面更改、没有文档或不受限制时，问题就会出现。合作伙伴的应用突然失灵，内部团队不知道哪些接口仍在使用，一个配置错误的客户端就能拖慢整个系统。

本文介绍面向企业需求的 API 设计实践，而不是学术理论。重点放在最常决定 API 能否持续使用多年的四件事：设计一致性、版本管理与变更管理、文档，以及速率限制与安全。适合需要向技术团队或供应商提出恰当问题的企业主和产品经理。

摘要

• 好的 API 被当作产品对待：有清晰的契约、负责人、文档和生命周期，而不是应用的副产品
• 在命名、错误格式、分页和日期格式上保持一致的设计，可降低各方的集成成本
• 版本管理与弃用政策使您能够演进 API 而不破坏旧客户端
• 配有示例和测试环境的实时文档，是决定合作伙伴多快能够接入的最大因素
• 速率限制、身份验证和监控保护稳定性与安全，并使基础设施成本可预测

把 API 当作产品，而不是应用的副产品

许多 API 是意外诞生的。移动应用团队需要数据，接口被尽快创建，两年后业务伙伴想要使用它，却没人确定哪些内容可以改动。这种模式产生的 API 不一致、难以编写文档，每次修改都有风险。

把 API 当作产品对待，意味着几项实际做法。有一位负责契约和变更决策的负责人。有一份 API 使用方清单（内部与外部），以便预估变更的影响。有质量目标，如可用性和响应时间。还有生命周期计划：新接口如何引入，旧接口如何退役。这种思路与可组合 ERP：模块化与 API 优先的系统中讨论的模块化和 API 优先原则一致。外行入门可参阅面向企业主的 API 是什么。

让 API 易于使用的设计原则

一致性是最重要的。对方的开发者学会一种模式，就期望它在整个 API 中都适用。值得一开始就确定的决策：

• 命名：资源使用名词，复数形式一致，所有字段采用相同的书写风格
• 方法：按含义使用 HTTP 方法，例如 GET 读取、POST 创建、PUT 或 PATCH 修改、DELETE 删除
• 状态码：返回有意义的状态码，出错时不要回答"200 OK"
• 错误格式：整个 API 统一，包含稳定的错误代码、人类可读的消息和修复提示
• 分页：所有列表使用同一种模式，对频繁变化的大数据最好采用游标分页
• 筛选与排序：参数统一，客户端无需针对每个接口重新学习
• 日期与时间格式：采用带明确时区的单一标准，并明确货币与数字单位
• 资源标识：使用稳定、不变的 ID，而不是可被猜测的顺序号

对有重复风险的操作实现幂等性

在创建订单或支付等操作中，不稳定的网络会让客户端重发同一请求。没有保护的话，结果就是重复订单。请支持幂等键：客户端附带唯一代码，服务器识别重复请求并返回相同结果，而不会执行两次。这在支付集成中尤其重要，见网站与应用的支付网关集成。

响应够用即可，不要过多

返回使用方所需的数据，而不是数据库的全部内容。泄露内部字段的响应会增加安全风险，也使将来的变更更困难，因为客户端会开始依赖那些本不该被使用的字段。

版本管理与变更管理

一个活跃的 API 必然会变化。问题在于如何在不破坏现有客户端的情况下修改它。

哪些变更安全，哪些会破坏

通常安全的（增量式）变更包括：在响应中添加新字段、添加新接口或添加可选参数。破坏性变更包括：删除或重命名字段、更改数据类型、改变某个值的含义、把原本可选的参数变为必填，以及更改默认行为。编写良好的客户端会忽略不认识的新字段，因此请把这一预期写入文档。

版本策略

标记版本有几种方式。

• URL 路径中的版本，例如 /v1/，最容易理解和测试
• 请求头中的版本，保持 URL 整洁，但用简单工具测试更困难
• 基于日期的版本，客户端将行为固定在某个日期

选择一种并一致地应用。只有确实出现破坏性变更时才提升主版本，并尽量通过把变更设计为增量式来减少这种情况。

公平的弃用政策

以可预期的流程让旧接口退役。

• 通过使用方真正会阅读的渠道提前公告，例如发给技术联系人的邮件、发布说明和响应上的警告头
• 给予合理的过渡期，通常是几个月，对大型合作伙伴更长
• 提供带前后对照示例的迁移指南
• 监控旧接口的使用情况，在关闭之前就知道谁还在使用
• 逐步关闭，例如安排试验性停用时段，让被遗忘的客户端有机会作出反应

这种分阶段方式类似于企业应用的功能开关与渐进式发布中讨论的发布理念，并避免对合作伙伴有风险的"一次性全部切换"。

让集成变快的文档

文档往往比 API 设计本身更能决定集成成败。无法在几小时内理解如何使用 API 的合作伙伴，会放弃或提交大量支持工单。

好的文档具备以下要素：

• 快速入门指南：几分钟内从测试凭据到第一次成功请求
• 完整的参考：每个接口、参数、请求和响应示例，以及错误代码列表
• 机器可读的规范，例如 OpenAPI，可自动生成文档、客户端和测试
• 带示例数据、与生产环境分离的测试环境或沙盒
• 按业务场景的指南，例如如何创建订单再跟踪其状态，而不只是接口列表
• 带日期和影响程度的变更日志
• 关于速率限制、身份验证和支持政策的信息

文档应与代码一起生成或更新，以免过时。如果文档可能与实际行为不同，使用方就会不再信任它。关于面向用户文字清晰度的类似考虑，见企业应用和网站的 UX 文案与微文案，同样适用于 API 的错误消息。

速率限制、身份验证与安全

不设限的开放 API 会招致问题，无论来自配置错误的客户端还是攻击者。

速率限制与配额

限制每个客户端在特定时间段内的请求数量。目的是保护稳定性、确保客户端之间的公平，并控制基础设施成本。超出限制时返回合适的状态码，说明客户端何时可以重试，并在文档中写明限制。对于较重的操作，提供批处理或 Webhook 途径，让客户端不必反复询问状态。这在企业的 Webhook 与实时集成中有讨论。

身份验证与授权

确保每个请求都经过身份验证，每个操作都按访问权限获得授权。使用可撤销的 API 密钥或令牌，授予所需的最小权限，并将测试环境与生产环境的凭据分开。对于代表用户的访问，使用成熟的标准，而不是自创方案。访问权限的原则见设计用户访问权限，通用防护见企业应用的基础安全。

校验与其他防护

• 在服务器端校验所有输入，不要只依赖客户端
• 限制请求大小和执行时间
• 不要在错误消息中显示内部技术堆栈信息
• 为审计留痕记录重要请求，同时避免过多存储敏感数据
• 在所有环境中使用加密连接
• 以明确的流程轮换并撤销泄露的凭据

由于 API 往往是通向核心数据的入口，请定期测试其安全性，并纳入依赖扫描，如依赖安全与软件供应链所述。

监控与可观测性

您无法管理看不见的 API。请监控以下指标：

• 每个接口的可用性和错误率
• 延迟，尤其是代表最差体验的高百分位
• 按客户端和按接口的请求量
• 旧版本的使用情况，用于规划弃用
• 异常的身份验证失败，这是滥用的迹象
• Webhook 的响应时间和重试成功率

通用监控和有用日志的做法在企业应用的可观测性、日志与错误处理和网站与企业应用的监控与正常运行时间中有讨论。

管理 API 的常见错误

• 在不通知的情况下更改响应，导致合作伙伴的集成失灵
• 没有谁在使用 API 的清单，因此不知道变更的影响
• 文档落后于代码
• 每个接口的错误格式都不同
• 没有速率限制，一个客户端就能让所有人的服务瘫痪
• 把一个拥有全部权限的访问密钥用于各种用途
• 因为认为没人使用而突然关闭旧版本
• 把数据库结构原样暴露为 API

起步步骤

1. 列出所有接口及其使用方，包括内部和外部

2. 制定设计准则：命名、错误、分页和数据格式

3. 确定版本策略和书面的弃用政策

4. 根据规范生成文档并提供沙盒

5. 设置速率限制、按客户端的凭据和监控

6. 每季度审查 API：谁在用什么、什么很慢、什么可以退役

常见问题

小企业需要考虑 API 版本管理吗？需要，只要有外部方或移动应用依赖您的 API。尤其是移动应用很难强制更新，旧版本可能存活数月。

何时应提升版本？只在出现破坏性变更时。增量式变更不需要新版本。

文档必须手工编写吗？大部分可以从规范生成，但业务场景指南和示例仍需人来撰写。

合理的速率限制是多少？取决于容量和使用模式。从基于真实数据的保守数字开始，监控后调整，并为有需要的客户提供更高档位。

GraphQL 比 REST 更好吗？两者都可行。根据使用方需求和团队能力选择。一致性、版本、文档和速率限制的原则对两者都适用。

结论

持久的 API 不是偶然。它来自把它当作产品：设计一致、以公平的版本和弃用方式管理变更、实时更新的文档，以及清晰的速率限制和安全措施。这项投资将通过更快的合作伙伴集成、更少的支持工单，以及在使用量增长时依然稳定的系统得到回报。如果您的业务开始依赖集成，就该用对待其他产品的同样思路来审视您的 API 了。