💡 Key Takeaways
- The Foundation: Understanding REST Beyond the Buzzword
- Resource Naming: The Art of Intuitive URLs
- HTTP Methods: Using the Right Tool for the Job
- Status Codes: Speaking HTTP's Language Fluently
作者：Marcus Chen，首席API架构师，拥有14年在金融科技和医疗公司构建可扩展系统的经验
💡 关键要点
- 基础知识：理解REST超越流行词
- 资源命名：直观URL的艺术
- HTTP方法：选择合适的工具
- 状态码：流利地讲HTTP的语言
三年前，我看到一家创业公司因为其API设计根本性的问题而消耗了230万美元的工程成本。他们构建了一个有47个不同端点的支付处理系统，命名规则不一致，且没有版本控制策略。当他们需要为最大客户添加新功能时，变更如多米诺骨牌般蔓延到整个系统。经过六个月的重构，他们失去了最大的客户，并裁员40%的工程团队。
这场灾难让我领悟到一个重要的真理：API设计不只是为了让事情今天能够工作。而是要在您的系统与世界之间建立一个可以优雅演变的契约，这个契约能够处理数以百万计的请求，并且足够直观，使得开发者真的想要使用它。在超过十年的时间里，我设计了处理数十亿交易的API，我意识到一个好的API和一个出色的API之间的区别往往归结为大多数团队所忽视的几个基本原则。
基础知识：理解REST超越流行词
2010年我开始我的职业生涯时，REST已经是Web API的主流架构风格，但我注意到许多开发者将其视为清单，而非一种哲学。REST代表表述性状态转移（Representational State Transfer），它基于Roy Fielding在他的博士论文中概述的六个核心约束。但在实践中，重要的是将您的API资源视为名词，使用HTTP方法作为动词，并保持无状态性。
单靠无状态性原则就为我节省了无数调试时间。每个从客户端到服务器的请求必须包含理解和处理该请求所需的所有信息。服务器上不应有会话状态。这意味着您的API可以水平扩展，而不需要复杂的会话管理，您的集群中的任何服务器都可以处理任何请求。当我为一家处理每日320万交易的医疗平台架构支付API时，这个原则使我们能够在高峰期从4台服务器扩展到47台，而不改变应用程序代码的任何一行。
但REST并不是教条。我见过团队浪费数周的时间争论某个东西是否“真正符合REST”，而他们应该关注的是一致性和可用性。目标是创建一个开发者能够直观理解的API。如果您正确使用HTTP方法，逻辑性地组织资源，并保持无状态性，那么您就已经完成了90%的工作。剩下的10%则是那些使您的API使用起来愉悦而不是令人沮丧的实用模式。
资源命名：直观URL的艺术
您的URL结构是开发者看到的第一件事，它为您的整个API设定了期望。我遵循一个简单的规则：为资源使用名词，保持复数形式，并在有明显的父子关系时将其层次化。例如，/api/v1/users/12345/orders/67890让您立刻知道您正在查看属于用户12345的订单67890。
"最好的API是开发者在阅读您的文档之前就能预测下一个端点的API——这时您就知道您达到了真正的一致性。”
大多数团队出错的地方在于：他们将动词混入URL中。我审查过的API中有端点如/api/getUser或/api/createOrder。这是多余的，因为HTTP方法已经提供了动词。GET /api/users/12345比GET /api/getUser/12345更加清晰和RESTful。HTTP方法告诉您正在执行什么操作；而URL告诉您正在操作的资源。
一致性比完美更重要。在一个项目中，我们曾就使用/users还是/accounts作为我们的用户资源进行辩论。我们在会议上花了三个小时。这时候重要的不是我们选择哪个术语，而是我们选择了一个并在整个API中保持一致。我们记录了我们的决定，将其添加到我们的API风格指南中，然后继续前进。这种一致性使得开发者能够在无需不断查看文档的情况下预测端点名称。
对于嵌套资源，我将深度限制在最多两到三级。超过这个深度，URL会变得笨重且关系变得不清晰。如果您发现自己在写/api/companies/123/departments/456/teams/789/members/012，那么您就走得太远了。相反，可以考虑将团队作为顶级资源并使用查询参数：/api/teams/789/members?company=123&department=456。这使得URL变得更易管理，同时仍允许您适当地过滤和限定资源。
HTTP方法：选择合适的工具
HTTP为我们提供了丰富的方法词汇，但我看到开发者常常错误使用它们或仅限于使用GET和POST。理解每种方法的语义意义帮助我构建既直观又可缓存的API。GET用于检索资源，必须是幂等且安全的——多次调用会产生相同的结果而不会有副作用。POST用于创建新资源。PUT替换整个资源。PATCH更新部分资源。DELETE删除资源。
| HTTP方法 | 目的 | 幂等 | 常见错误 |
|---|---|---|---|
| GET | 检索资源 | 是 | 用于修改数据的操作 |
| POST | 创建新资源 | 否 | 用于更新而不是PUT/PATCH |
| PUT | 替换整个资源 | 是 | 部分更新而不是完全替换 |
| PATCH | 部分资源更新 | 否 | 不必要地发送完整资源主体 |
| DELETE | 删除资源 | 是 | 在响应主体中返回资源数据 |
对于PUT和POST的幂等性至关重要。当我为一家拥有847家店铺的零售连锁构建库存管理API时，我们特意因为它具有幂等性保证而使用PUT进行更新。如果网络故障导致请求被发送两次，PUT确保我们不会意外创建重复的记录或多次应用相同的更新。这个决定在运营的第一年避免了大约12,000个库存差异。
PATCH被低估但价值巨大。它允许部分更新，而不要求客户端为小的更新发送整个资源表示。当更新一个有30个字段的用户资料时，为什么要强迫客户端发送全部30个字段，而他们只想更改电子邮件地址呢？PATCH /api/users/12345的主体为{"email": "[email protected]"}比要求完整资源更高效且不容易出错。
DELETE也应该是幂等的。对已删除的资源调用DELETE应返回204无内容或404未找到，而不是错误。这使得重试逻辑更简单且更可靠。我实现了软删除，其中DELETE将资源标记为非活动状态，而不是物理删除，这提供了审核跟踪并允许恢复。关键是后续对同一资源的DELETE调用产生相同的结果——从客户端的角度来看，资源已经消失。