💡 Key Takeaways
- The $2.3 Million API Mistake That Changed How I Design REST APIs Forever
- Resource-Oriented Design: Think in Nouns, Not Verbs
- HTTP Status Codes: Your API's Communication Language
- Versioning Strategies: Planning for Inevitable Change
改变我如何永远设计 REST API 的 230 万美元 API 错误
我仍然记得 2019 年一个星期二凌晨 3 点的电话。我们的支付处理 API 发生故障，导致 47 个企业客户无法处理交易。在我们六小时后恢复服务时，我们损失了 230 万美元的收入和三个重要客户。根本原因？我在十八个月前做出的糟糕 API 设计决策，当时似乎无伤大雅。
💡 关键要点
- 改变我如何永远设计 REST API 的 230 万美元 API 错误
- 面向资源的设计：思考名词，而非动词
- HTTP 状态码：你的 API 的通信语言
- 版本控制策略：为不可避免的变化做好规划
我叫 Marcus Chen，过去十二年一直在设计和维护大规模的 REST API——最初在一家每年处理 40 亿美元的金融科技初创公司，然后在一家服务 200,000+ 开发者的 SaaS 公司，现在是一名独立的 API 架构顾问。那次灾难性的失败教会了我比任何书籍或课程都要多的 REST API 设计知识。今天，我将分享那些经过实战检验的原则，这些原则使我的 API 在过去四年中保持了 99.97% 的正常运行时间。
REST API 是现代软件的支柱。根据 RapidAPI 2023 年的 API 状态报告，89% 的开发者定期使用 REST API，而设计不良的 API 每年使公司损失平均 120 万美元的开发者时间、支持成本和失去的机会。然而，大多数开发者通过反复试错的方式学习 API 设计，重蹈我曾经造成的数百万损失的覆辙。
这篇文章不是理论上的。每个我分享的原则都来自真实的生产经验——从处理每秒 50,000 次请求的 API 到管理数十亿美元交易的系统。无论你是在构建你的第一个 API 还是重构遗留系统，这些实践将使你免于我以艰辛的方式学到的痛苦教训。
面向资源的设计：思考名词，而非动词
我在 REST API 设计中看到的最大错误是将终端点视为 RPC 调用。开发者创建诸如 /getUser、/createOrder 或 /deleteProduct 的 URL——基本上是在用 JSON 构建 SOAP API。这正是我早期所做的，结果造成了维护的噩梦，耗费了两年的时间才理顺。
“好 API 和伟大 API 之间的区别不在于技术——而在于拒绝会在凌晨 3 点纠缠你的捷径的纪律。”
REST 本质上是关于资源，而非动作。你的 API 应该暴露 事物（名词），并使用 HTTP 方法来定义动作（动词）。当我在 2020 年重新设计我们的支付 API 时，我将 73 个基于动词的终端点转变为 28 个面向资源的终端点。结果？开发者上手时间从 4.2 天降至 1.3 天，与 API 相关的支持票减少了 61%。
这是改变我一切的思维模型：想象你的 API 就像一个文件柜。每个抽屉代表一个资源集合（/users、/orders、/products）。单独的文件是特定资源（/users/12345）。你不会用“获取文件”或“添加文件”这样的动作来标记抽屉——抽屉只包含文件，而你使用不同的动作（打开、添加、移除）与它们互动。
实际实现意味着对集合使用复数名词：/customers 而不是 /customer，/invoices 而不是 /invoice。正确使用 HTTP 方法：GET 用于检索，POST 用于创建，PUT 用于完全更新，PATCH 用于部分更新，DELETE 用于删除。当我在 2022 年审计 50 个流行 API 时，我发现78% 的低评分 API 违反了这一原则，而94% 的高评分 API 始终遵循它。
对于嵌套资源，逻辑上保持层次结构。/customers/789/orders 是合理的，因为订单属于客户。但不要嵌套超过两层——/customers/789/orders/456/items/123/reviews 会变得难以管理。相反，使用查询参数或单独的终端点。在创建五级嵌套结构后，我学到了这一点，这使我们的移动团队威胁要切换到 GraphQL。
我发现的一个例外是：对不符合 CRUD 模型的操作使用动词。/orders/456/cancel 或 /users/789/verify-email 是可以接受的，因为这些表示动作，而不是资源状态。只需将这些保持在最低限度——在我当前负责的每天有 50,000 活跃用户的 API 中，只有 94 个终端点中有 8 个使用基于动词的路径，并且每个都有明确的理由。
HTTP 状态码：你的 API 的通信语言
三年来，我对所有请求返回 HTTP 200，并将错误详细信息放在响应体中。“它可以工作，”我对我的团队说。“客户端可以直接查看 JSON。”当我们尝试实施适当的缓存、监控和错误跟踪时，这个决定让我感到困扰。我们的监控系统无法区分成功请求和失败，这使得设置有意义的警报变得不可能。
| 方法 | 示例 | 优点 | 缺点 |
|---|---|---|---|
| URL 路径版本控制 | /api/v1/users | 清晰、可缓存、易于路由 | 需要重复代码、URL 污染 |
| Header 版本控制 | Accept: application/vnd.api+json;version=1 | 干净的 URL、灵活的协商 | 测试更难、缓存复杂性 |
| 查询参数 | /api/users?version=1 | 简单、向后兼容 | 容易被遗忘、不一致使用 |
| 内容协商 | Accept: application/vnd.company.v1+json | RESTful，符合标准 | 学习曲线陡峭、工具缺口 |
HTTP 状态码存在是有原因的——它们是一种每个 HTTP 客户端、代理、缓存和监控工具都能理解的标准化语言。当我在 2021 年最终重构我们的 API 以使用正确的状态码时，我们的错误检测提高了 340%，问题被发现的平均时间比之前快了 23 分钟。
这是我基于处理去年 24 亿个 API 请求的经验所提出的实用指南：使用 200 OK 表示成功的 GET、PUT、PATCH 或 DELETE 操作返回数据。使用 201 Created 表示成功的 POST 操作创建资源，并包括一个指向新资源的 Location 头部。使用 204 No