RESTful API 设计：基本最佳实践
设计结构良好的 API 已不再是小众技能，而是现代软件开发的基本要求。设计不佳的 API 会降低开发效率、损害系统性能，并造成维护噩梦。掌握 REST 的核心原则，你可以创建可扩展、灵活且让其他开发者乐于使用的 Web 服务，从而学会如何为 Web 应用程序设计既强大又直观的 RESTful API。
你将学到什么
通过本指南，你将理解 RESTful 架构的基本约束，并超越理论，做出实际的设计决策。你将学习如何设计面向资源的 URI、正确应用 HTTP 方法，以及实施版本控制、安全性和文档策略，确保你的 API 在演进过程中保持健壮且易于使用。
REST 的基本原则
要设计真正的 RESTful API，必须遵循 Roy Fielding 定义的架构约束。这些原则创建了一个无状态、可缓存且统一的接口，将客户端与服务器解耦。
客户端-服务器与无状态性
将用户界面与数据存储分离，提高了用户界面在多个平台上的可移植性，并简化了服务器组件，从而提升了可扩展性。这种分离使得前端和后端能够独立演进。此外，REST 要求无状态的请求模型。这意味着从客户端到服务器的每个 HTTP 请求都必须包含理解和处理该请求所需的所有信息。服务器不能依赖之前交互中存储的任何上下文。这一约束对于实现水平可扩展性至关重要，因为任何服务器实例都可以处理任何请求。这种无状态性是 RESTful API 简洁性和可扩展性的主要驱动力。
统一接口
统一接口是 REST 区别于其他架构的显著特征。它简化并解耦了架构，使各部分能够独立演进。该接口依赖于四个关键约束：
- 资源标识： 资源（例如用户、订单、产品）在请求中通过 URI 标识。它们被视为名词，而非动词。
- 通过表示操作资源： 客户端与资源的表示（通常是 JSON 或 XML）交互，而非资源本身。表示包含足够的信息来修改或删除资源。
- 自描述消息： 每条消息包含足够的信息来描述如何处理它，例如媒体类型和 HTTP 方法。
- 超媒体作为应用状态引擎 (HATEOAS)： 客户端应完全通过服务器动态提供的超媒体链接与应用交互。这使得 API 可以更改其 URI 结构而不会破坏客户端，因为客户端通过链接导航。
设计面向资源的 URI
资源标识是实际 API 设计的第一步。你必须确定 API 将暴露的业务对象或实体。
命名约定
遵循一致的命名约定对可用性至关重要。使用名词表示资源，而不是动词。例如，使用 /orders，而不是 /create-order。HTTP 方法已经隐含了动作。对于集合，最佳实践是使用复数名词。/customers 是集合的清晰路径，而 /customers/5 指向特定客户。这种方法直观且与许多 Web API 框架的路由方式一致。
路径结构与关系
设计 URI 来表示资源之间的关系，但不要过于复杂。像 /customers/1/orders 这样的 URL 有效地表示了特定客户的所有订单。避免要求 URI 比 collection/item/collection 更复杂。如果资源具有深层关系，请在响应体中提供链接，而不是在 URI 中编码整个遍历路径。这可以防止紧耦合，使 API 更灵活地应对变化。
定义 HTTP 方法和状态码
REST 充分利用 HTTP 协议的能力来对资源执行操作。
标准方法
你的 API 应使用标准 HTTP 方法来执行 CRUD（创建、读取、更新、删除）操作。
- GET： 检索资源的表示。必须是安全的（无副作用）且幂等的（多次相同请求的效果与一次相同）。
- POST： 创建新资源。服务器分配新资源的 URI 并将其返回给客户端。
- PUT： 替换资源的整个状态。是幂等的。
- PATCH： 对资源进行部分更新。
- DELETE： 删除资源。是幂等的。
有意义的状态码
返回正确的 HTTP 状态码对于清晰可用的 API 至关重要。这允许客户端无需解析响应体即可理解操作结果。
| 状态码 | 含义 | 使用场景 |
|---|---|---|
| 200 OK | 成功 | 请求成功；负载包含请求的数据。 |
| 201 Created | 资源已创建 | POST 请求成功创建了新资源。 |
| 204 No Content | 成功，无内容 | 请求成功（例如 DELETE 请求），但没有要返回的表示。 |
| 400 Bad Request | 客户端错误 | 请求格式错误或包含无效数据（例如语法错误）。 |
| 401 Unauthorized | 认证错误 | 客户端认证失败。 |
| 403 Forbidden | 授权错误 | 客户端已认证但缺乏权限。 |
| 404 Not Found | 资源未找到 | 请求的 URI 不存在。 |
| 500 Internal Server Error | 服务器错误 | 发生通用服务器端错误。 |
高级考虑：版本控制与文档
通过版本控制面向未来
变化是不可避免的，你的 API 必须演进。为了避免破坏现有客户端，需要健壮的版本控制策略。最常见且透明的方法是 URL 版本控制，即在 URI 路径中包含版本号，例如 /v1/users。这使得 API 版本显式。其他选项包括自定义头部或媒体类型版本控制，但 URL 版本控制因其简单易用而常被青睐。
“API 优先”思维
将 API 视为产品而非琐事是成熟工程团队的标志。"API 优先"方法意味着在编写底层实现代码之前设计 API 规范。你应该使用标准规范语言（如 OpenAPI）来定义 API 契约。该契约作为唯一真相来源，并支持强大的工具，如交互式文档和客户端 SDK 生成。它还迫使你从 API 消费者的角度思考，确保在编写任何代码之前接口易于使用。
常见问题
RESTful API 中 PUT 和 PATCH 有什么区别？ PUT 用于替换整个资源为新表示。如果你只发送部分更新，它将用 null 或默认值覆盖其余部分。PATCH 用于对资源进行部分更新，仅修改你指定的字段。因此，对于不想发送整个资源状态的更新，PATCH 通常是首选。
API 版本控制应该在 URL 中还是头部中？
URL 版本控制（例如 /v1/users）是最常见且推荐的方法。它使版本显而易见，对开发者和调试都有帮助，因为它直接出现在请求路径中。虽然存在基于头部的版本控制，但对于大多数用例，URL 路径版本控制更简单且更易发现。
什么是 HATEOAS，我需要实现它吗？ HATEOAS（超媒体作为应用状态引擎）是一种约束，服务器在响应中提供链接，供客户端动态导航 API。这使客户端与 URI 结构解耦，允许服务器更改 URI 而不会破坏客户端。虽然严格的"完整"HATEOAS 很少实现，但在 API 响应中包含相关链接是一种最佳实践，可促进可发现性并减少客户端中 URI 的硬编码。
命名 API 资源的最佳实践是什么？
最佳实践是使用名词表示资源，使用复数名词表示集合。避免在 URI 中使用动词（例如使用 /orders，而不是 /get-orders）。这是因为 HTTP 方法（GET、POST 等）已经定义了正在执行的操作。清晰、基于名词的结构使你的 API 直观且易于使用。
为什么 RESTful API 必须是无状态的？ 无状态意味着来自客户端的每个请求都包含服务器完成该请求所需的所有信息，并且服务器不在请求之间存储任何会话状态。这一约束对于可扩展性至关重要，因为它允许负载均衡集群中的任何服务器实例处理任何请求，并简化了服务器端架构。这是使 RESTful API 能够支持 Web 规模应用的核心原则。
来源
- Lauret, Arnaud. The Design of Web APIs. Manning Publications, 2025.
- Microsoft. "Best practices for RESTful web API design." Azure Architecture Center, 2025.
- Fielding, Roy. "Guiding Principles of REST."
- Oracle. "What Are RESTful Web Services?" Oracle Help Center.
- OGC. "Overview and main concepts." OGC API Workshop.
- [x]cube LABS. "Best Practices for Designing RESTful APIs." 2024.
- Hackney Council. "API Design Principles." Hackney Development System.
— Editorial Team
暂无评论。