这些错误背后的方法论
在我们深入具体错误之前，你需要理解我如何对API设计失败进行分类。我不仅是收集轶事——我追踪跨行业、团队规模和技术栈的模式。 截至今天早上，我的电子表格有847条记录。每条记录都包括错误类别、团队规模、发现时间（多长时间后有人注意到问题）、修复时间和预计业务影响。我已经对数据进行了匿名处理，但模式显而易见。 错误分为三个严重级别： 第1级：烦人 — 这些给API消费者造成摩擦，但不破坏功能。想想不一致的命名约定或缺失的文档。平均修复时间：2-4小时。平均业务影响：开发者满意度低分。 第2级：昂贵 — 这些需要重大重构或造成持续的维护负担。想想糟糕的版本管理策略或过于耦合的端点。平均修复时间：2-6周。平均业务影响：推迟功能发布、增加支持成本。 第3级：灾难性 — 这些可能导致数据丢失、安全漏洞或完全服务中断。想想删除数据的GET端点或绕过身份验证的漏洞。平均修复时间：1-3个月（包括恢复）。平均业务影响：六位到七位数。 我今天要讨论的七个错误涵盖所有三个级别。有些看似微不足道，直到你在规模上处理它们。其他的显然很危险，但却令人惊讶地常见。 使这些错误特别阴险的是，它们往往在开发过程中或初始生产部署时并不显现。它们在你达到规模时浮现，当你需要改进API时，或者当外部用户开始以你从未预料的方式使用你的端点时，它们才暴露出来。只有我能讲述的故事：分页灾难
让我给你讲讲我亲眼目睹的最糟糕的API设计错误——一个让一家B轮初创公司失去其最大的企业交易的错误。 该公司构建了一个项目管理API。干净、文档齐全、速度快。他们与一家希望将15年的项目数据迁移到新系统的财富500强企业达成了一项试点合作。合同年价值230万美元。 迁移团队开始通过`/api/projects`端点提取数据。在他们的500个项目的样本数据测试中，一切运行得非常完美。然后他们对生产环境运行：340,000个项目。 该端点使用基于偏移量的分页：`/api/projects?offset=0&limit=100`。标准配置。可是在规模上，偏移分页有一个致命缺陷：随着偏移量的增加，数据库性能会指数级下降。 提取记录0-100？快速。提取记录100,000-100,100？数据库必须扫描100,000条记录才能跳过它们。当他们达到偏移量300,000时，每个请求需要45秒并超时。 本应在6小时内完成的迁移在三天后仍在运行。财富500强的基础设施团队将其标记为潜在的DDoS攻击。初创公司的首席执行官不得不亲自打电话给他们的CTO，解释说不，他们并没有攻击他们——他们的API设计得很糟糕。 更糟糕的是：修复它需要一个破坏性的改变。他们必须切换到基于游标的分页，这意味着每个客户端都需要更新其集成代码。财富500强公司最终选择放弃。他们无法冒着在试点期间基于需要重大更改的API上构建的风险。 六个月后，我在他们的C轮融资尽职调查中审查了他们的API。分页问题依然存在。他们太害怕修复它，因为他们现在有40个付费客户，都需要更新他们的代码。 这就是API设计错误的特点——它们固化。存在的时间越长，修复它们的难度就越大。每一个新的集成都让你无法进行破坏性的更改。数据：实际在生产中出现的问题
我分析了自2019年以来进行的400个API设计审查。实际在生产中导致问题的原因如下：| 错误类别 | 频率 | 平均发现时间 | 平均修复时间 | 是否需要破坏性更改？ |
|---|---|---|---|---|
| 糟糕的分页策略 | 67% | 4-8个月 | 6-12周 | 是（89%） |
| 不一致的错误响应 | 82% | 2-3周 | 3-6周 | 否 |
| 缺失的速率限制 | 43% | 1-2个月 | 2-4周 | 否 |
| 非幂等操作 | 38% | 3-6个月 | 8-16周 | 是（72%） |
| 过度提取/提取不足 | 91% | 1-3个月 | 4-8周 | 有时（45%） |
| 糟糕的版本管理策略 | 56% | 6-12个月 | 12-24周 | 不适用（防止未来更改） |
| 不安全的HTTP方法 | 12% | 1-4周 | 1-2周 | 是（100%） |
为什么聪明的团队会犯这些错误
关于API设计，有一点没人告诉你：这些错误不是由无能造成的。它们是由于在当时看似合理的限制下做出的合理决策。“我们使用偏移分页，因为这是ORM默认给我们的。切换到基于游标的分页会使冲刺增加两天，而我们已经落后于进度。我们认为如果这个问题出现了，我们会在后面优化。” — 一家金融科技初创公司的工程负责人，在他们的分页成为问题前的三个月这是我反复看到的模式：团队做出权宜之计的选择，因为他们在优化快速交付，而不是长期的可维护性。在当下，这通常是正确的商业决策。问题是，“以后”永远不会来，或者来得时候修复问题需要的破坏性更改会影响数十个客户。 另一个常见模式是：团队根据内部数据模型而不是消费者的需求设计API。你的数据库有一个`users`表，包含47列，所以你的`/api/users`端点返回所有47个字段。看起来很合理，对吧？可你的移动应用只需要其中的5个字段，现在你正在通过蜂窝网络向数百万个设备发送42个不必要的字段。
“我们考虑过字段过滤，但这似乎是过早的优化。我们的端点在测试中速度足够快。我们没有意识到，拥有100个测试用户的‘足够快’变成了拥有100,000个生产用户时的‘不可接受的慢’。” — 一家SaaS公司的CTO，解释为什么他们的移动应用加载时间为4秒第三种模式是：团队没有考虑API的演变。他们在设计版本1时并没有考虑如何处理版本2。他们没有在URL或头部中包含版本号。他们没有记录哪些字段是稳定的，哪些可能会改变。然后六个月后，他们需要进行破坏性更改，才意识到他们没有干净的办法来做到这一点，而不会破坏现有集成。 这就是为什么我在设计审查中总是问团队：“当你需要改变这个的时候会发生什么？”如果答案是“我们到时候想办法”，那你就正在为自己设定痛苦的未来。
挑战“REST纯洁性”假设
这里有一个不受欢迎的观点：严格遵循REST原则往往会使API变得更糟，而不是更好。 REST的纯粹主义者会告诉你，每个资源应该有一个标准的URL，应该语义上使用HTTP方法，你的API应该是无状态的、可缓存的以及Roy Fielding在他的论文中所概述的所有其他约束。 在实践中？我审查的一些最佳API在使其用例合理的情况下违反了REST原则。 以GitHub的API为例。他们有一个名为`/repos/{owner}/{repo}/commits`的端点，返回提交。遵循REST，对吧？但他们还有一个`/search/commits`端点，返回……提交。同一资源，不同的URL结构。为什么？因为搜索提交与列出提交是根本不同的操作，试图将搜索强行放入标准URL的查询参数中会导致更糟糕的开发者体验。 或者考虑Stripe的API。他们对应该理论上使用PUT的幂等操作使用POST。为什么？因为POST在HTTP客户端中的支持更广泛，并且头部中的幂等性密钥提供了与PUT相同的保证，而没有兼容性问题。 重点不是REST不好——而是REST是一组指导方针，而不是宗教教义。目标是构建直观、性能良好且可维护的API。有时这意味着遵循REST原则。有时这意味着故意破坏它们。“我们花了三个星期争论我们的批量更新端点应该是PUT还是POST。事后看来，我们本该用这三个星期构建更好的错误消息。当你的API返回‘500 Internal Server Error’而没有详细信息时，没有人关心HTTP方法的纯洁性。” — 一家医疗公司的API架构师错误的