RESTful API 设计原则
字数 3366 2025-11-02 17:10:18

RESTful API 设计原则

我们来探讨一个后端开发中至关重要的概念：RESTful API 的设计原则。无论你使用 Spring Boot、Express.js、Django REST Framework 还是其他任何后端框架，设计和实现一套符合 REST 风格的 API 都是核心技能。

1. 什么是 REST？

首先，我们需要理解 REST 本身。REST（Representational State Transfer，表述性状态转移）是一种软件架构风格，而不是一个标准或协议。它由 Roy Fielding 博士在 2000 年的博士论文中提出，为一组架构约束条件定义了如何设计分布式、可扩展的网络应用。

简单理解，REST 描述了一种客户端与服务器交互的理想方式。而遵循 REST 风格设计的 API，我们就称之为 RESTful API。

2. REST 的核心约束（设计原则）

要被称为 RESTful，一个 API 需要满足以下六项核心约束中的大部分（尤其是前五项）：

  • 客户端-服务器（Client-Server）：这是最基本的原则。客户端和服务器是分离的，它们可以独立演化。客户端负责用户界面和用户体验，服务器负责数据处理和存储。这种分离提高了前后端的可移植性和可扩展性。

  • 无状态（Stateless）：这是非常重要且常被误解的一点。服务器不会在多个请求之间保存任何客户端的状态信息。这意味着每一个从客户端发往服务器的请求，都必须包含理解该请求所需的全部信息。会话状态（Session）完全由客户端负责保存（例如，通过 Token 或 Cookie）。这带来了巨大的好处：服务器更容易扩展，因为任何一个请求都可以被任何一台服务器实例处理。

  • 可缓存（Cacheable）：服务器返回的响应必须明确表明其本身是否可以被缓存。如果可以，客户端可以重用之前的响应数据，从而减少网络交互，提高效率。这通常通过 HTTP 头如 Cache-Control 来实现。

  • 统一接口（Uniform Interface）：这是 REST 架构的核心特征，它进一步细分为四个子原则：

    1. 资源的标识：每个资源（如一个用户、一篇文章）在系统中都有一个唯一的标识符，通常通过 URI（统一资源标识符）来实现。例如，/users/123 唯一标识了 ID 为 123 的用户。
    2. 通过表述来操作资源：客户端并不直接操作资源本身，而是操作资源的“表述”（Representation）。例如，客户端通过获取 JSON 格式的表述来了解一个用户的信息，也可以通过发送一个 JSON 表述来更新用户信息。同一个资源可以有多种表述（如 JSON、XML）。
    3. 自描述的消息：每个消息（请求或响应）都包含足够的信息来描述如何处理自己。这主要通过使用标准的 HTTP 方法（GET, POST, PUT, DELETE 等）和 Media Type（如 application/json）来实现。
    4. 超媒体作为应用状态的引擎（HATEOAS）：这是最高级的约束，在实践中并非总是被严格遵守。它要求服务器的响应中不仅包含数据，还应包含指向相关资源的链接（超媒体）。客户端通过跟随这些链接来驱动应用的状态变迁，就像在网页上点击链接一样。例如，获取用户列表的响应可能包含指向每个用户详情的链接。

  • 分层系统（Layered System）：客户端不需要知道它是直接连接至最终服务器，还是连接到一个中间层（如负载均衡器、代理服务器、网关等）。这提高了系统的安全性、可扩展性和可管理性。

  • 按需代码（Code-On-Demand，可选）：服务器可以临时向客户端传输一些可执行代码（如 JavaScript 脚本），以扩展客户端的功能。这是唯一一个可选的约束，在 Web API 中较少使用。

3. 如何设计一个符合上述原则的 RESTful API？—— 实践指南

现在，我们将这些原则应用到具体的 API 设计中。

步骤一：将你的数据模型视为“资源”

一切皆资源。比如，你的应用有用户、文章、评论。那么 /users、/articles、/comments 就是你的核心资源集合。

步骤二：使用 HTTP 方法对应 CRUD 操作

这是 RESTful API 最直观的体现。我们通过标准的 HTTP 方法来表达我们对资源的操作意图，而不是在 URL 中使用动词。

HTTP 方法 操作 描述 通常对应的 SQL
GET 检索/查询 安全且幂等的。用于获取资源的一个或多个表述。 SELECT
POST 创建 非幂等。用于创建新资源。服务器为新资源分配 URI。 INSERT
PUT 替换/更新 幂等的。用于更新已知 URI 的资源（客户端提供完整的更新后资源）。如果资源不存在，可以决定是否创建。 UPDATE
PATCH 部分更新 幂等的。用于对资源进行部分修改。 UPDATE
DELETE 删除 幂等的。用于删除指定 URI 的资源。 DELETE

示例：一个博客系统的 API 设计

假设我们要管理文章（Article）资源。

  • 获取所有文章：GET /api/v1/articles （返回文章列表）
  • 获取单篇文章：GET /api/v1/articles/123 （返回 ID 为 123 的文章详情）
  • 创建新文章：POST /api/v1/articles （请求体 Body 中包含新文章的 JSON 数据）
  • 完整更新文章：PUT /api/v1/articles/123 （请求体 Body 中包含 ID 为 123 的文章的完整新数据）
  • 部分更新文章：PATCH /api/v1/articles/123 （请求体 Body 中只包含要更新的字段，如 {"title": "新标题"}）
  • 删除文章：DELETE /api/v1/articles/123

步骤三：使用正确的 HTTP 状态码

服务器应该返回恰当的状态码来告知客户端请求的结果。

  • 200 OK：请求成功。
  • 201 Created：创建资源成功。通常在 POST 请求后返回，响应头 Location 中应包含新资源的 URI。
  • 204 No Content：请求成功，但响应体中没有内容（如 DELETE 成功）。
  • 400 Bad Request：客户端请求有错误（如参数验证失败）。
  • 401 Unauthorized：身份未认证。
  • 403 Forbidden：身份已认证，但无权限访问该资源。
  • 404 Not Found：请求的资源不存在。
  • 500 Internal Server Error：服务器内部错误。

步骤四：设计清晰的 URI

  • 使用名词的复数形式：/articles 而不是 /getArticle。
  • 使用连字符-提高可读性：/api/order-histories 比 /api/orderHistories 更清晰。
  • 使用查询参数进行过滤、分页、排序：
    • 过滤：GET /api/v1/articles?author=john&category=tech
    • 分页：GET /api/v1/articles?page=2&size=10
    • 排序：GET /api/v1/articles?sort=-createdAt,title （- 表示倒序）

总结

RESTful API 设计的核心思想是利用 Web 标准（主要是 HTTP）本身的特点来构建清晰、可预测、可扩展的接口。它不是死板的教条，而是一套指导原则。在实际项目中，你可能不会 100% 满足所有约束（尤其是 HATEOAS），但理解并遵循其核心思想（如无状态、资源化、正确使用 HTTP 方法和状态码）将极大地提升你设计的 API 的质量。

RESTful API 设计原则 我们来探讨一个后端开发中至关重要的概念：RESTful API 的设计原则。无论你使用 Spring Boot、Express.js、Django REST Framework 还是其他任何后端框架，设计和实现一套符合 REST 风格的 API 都是核心技能。 1. 什么是 REST？ 首先，我们需要理解 REST 本身。REST（Representational State Transfer，表述性状态转移）是一种软件架构风格，而不是一个标准或协议。它由 Roy Fielding 博士在 2000 年的博士论文中提出，为一组架构约束条件定义了如何设计分布式、可扩展的网络应用。 简单理解，REST 描述了一种客户端与服务器交互的理想方式。而遵循 REST 风格设计的 API，我们就称之为 RESTful API。 2. REST 的核心约束（设计原则） 要被称为 RESTful，一个 API 需要满足以下六项核心约束中的大部分（尤其是前五项）： 客户端-服务器（Client-Server） ：这是最基本的原则。客户端和服务器是分离的，它们可以独立演化。客户端负责用户界面和用户体验，服务器负责数据处理和存储。这种分离提高了前后端的可移植性和可扩展性。 无状态（Stateless） ：这是非常重要且常被误解的一点。服务器不会在多个请求之间保存任何客户端的状态信息。这意味着每一个从客户端发往服务器的请求，都必须包含理解该请求所需的全部信息。会话状态（Session）完全由客户端负责保存（例如，通过 Token 或 Cookie）。这带来了巨大的好处：服务器更容易扩展，因为任何一个请求都可以被任何一台服务器实例处理。 可缓存（Cacheable） ：服务器返回的响应必须明确表明其本身是否可以被缓存。如果可以，客户端可以重用之前的响应数据，从而减少网络交互，提高效率。这通常通过 HTTP 头如 Cache-Control 来实现。 统一接口（Uniform Interface） ：这是 REST 架构的核心特征，它进一步细分为四个子原则： 资源的标识 ：每个资源（如一个用户、一篇文章）在系统中都有一个唯一的标识符，通常通过 URI（统一资源标识符）来实现。例如， /users/123 唯一标识了 ID 为 123 的用户。 通过表述来操作资源 ：客户端并不直接操作资源本身，而是操作资源的“表述”（Representation）。例如，客户端通过获取 JSON 格式的表述来了解一个用户的信息，也可以通过发送一个 JSON 表述来更新用户信息。同一个资源可以有多种表述（如 JSON、XML）。 自描述的消息 ：每个消息（请求或响应）都包含足够的信息来描述如何处理自己。这主要通过使用标准的 HTTP 方法（GET, POST, PUT, DELETE 等）和 Media Type（如 application/json ）来实现。 超媒体作为应用状态的引擎（HATEOAS） ：这是最高级的约束，在实践中并非总是被严格遵守。它要求服务器的响应中不仅包含数据，还应包含指向相关资源的链接（超媒体）。客户端通过跟随这些链接来驱动应用的状态变迁，就像在网页上点击链接一样。例如，获取用户列表的响应可能包含指向每个用户详情的链接。 分层系统（Layered System） ：客户端不需要知道它是直接连接至最终服务器，还是连接到一个中间层（如负载均衡器、代理服务器、网关等）。这提高了系统的安全性、可扩展性和可管理性。 按需代码（Code-On-Demand，可选） ：服务器可以临时向客户端传输一些可执行代码（如 JavaScript 脚本），以扩展客户端的功能。这是唯一一个可选的约束，在 Web API 中较少使用。 3. 如何设计一个符合上述原则的 RESTful API？—— 实践指南 现在，我们将这些原则应用到具体的 API 设计中。 步骤一：将你的数据模型视为“资源” 一切皆资源。比如，你的应用有用户、文章、评论。那么 /users 、 /articles 、 /comments 就是你的核心资源集合。 步骤二：使用 HTTP 方法对应 CRUD 操作 这是 RESTful API 最直观的体现。我们通过标准的 HTTP 方法来表达我们对资源的操作意图，而不是在 URL 中使用动词。 | HTTP 方法 | 操作 | 描述 | 通常对应的 SQL | | :--- | :--- | :--- | :--- | | GET | 检索/查询 | 安全且幂等的。用于获取资源的一个或多个表述。 | SELECT | | POST | 创建 | 非幂等。用于创建新资源。服务器为新资源分配 URI。 | INSERT | | PUT | 替换/更新 | 幂等的。用于更新 已知 URI 的资源（客户端提供完整的更新后资源）。如果资源不存在，可以决定是否创建。 | UPDATE | | PATCH | 部分更新 | 幂等的。用于对资源进行部分修改。 | UPDATE | | DELETE | 删除 | 幂等的。用于删除指定 URI 的资源。 | DELETE | 示例：一个博客系统的 API 设计 假设我们要管理文章（Article）资源。 获取所有文章 ： GET /api/v1/articles （返回文章列表） 获取单篇文章 ： GET /api/v1/articles/123 （返回 ID 为 123 的文章详情） 创建新文章 ： POST /api/v1/articles （请求体 Body 中包含新文章的 JSON 数据） 完整更新文章 ： PUT /api/v1/articles/123 （请求体 Body 中包含 ID 为 123 的文章的完整新数据） 部分更新文章 ： PATCH /api/v1/articles/123 （请求体 Body 中只包含要更新的字段，如 {"title": "新标题"} ） 删除文章 ： DELETE /api/v1/articles/123 步骤三：使用正确的 HTTP 状态码 服务器应该返回恰当的状态码来告知客户端请求的结果。 200 OK ：请求成功。 201 Created ：创建资源成功。通常在 POST 请求后返回，响应头 Location 中应包含新资源的 URI。 204 No Content ：请求成功，但响应体中没有内容（如 DELETE 成功）。 400 Bad Request ：客户端请求有错误（如参数验证失败）。 401 Unauthorized ：身份未认证。 403 Forbidden ：身份已认证，但无权限访问该资源。 404 Not Found ：请求的资源不存在。 500 Internal Server Error ：服务器内部错误。 步骤四：设计清晰的 URI 使用名词的复数形式 ： /articles 而不是 /getArticle 。 使用连字符 - 提高可读性 ： /api/order-histories 比 /api/orderHistories 更清晰。 使用查询参数进行过滤、分页、排序 ： 过滤： GET /api/v1/articles?author=john&category=tech 分页： GET /api/v1/articles?page=2&size=10 排序： GET /api/v1/articles?sort=-createdAt,title （ - 表示倒序） 总结 RESTful API 设计的核心思想是 利用 Web 标准（主要是 HTTP）本身的特点来构建清晰、可预测、可扩展的接口 。它不是死板的教条，而是一套指导原则。在实际项目中，你可能不会 100% 满足所有约束（尤其是 HATEOAS），但理解并遵循其核心思想（如无状态、资源化、正确使用 HTTP 方法和状态码）将极大地提升你设计的 API 的质量。