RestfulAPI

约 1722 字大约 6 分钟

2025-10-16

诞生

在 Web 的早期（1990年代中后期），虽然 HTTP 协议（0.9, 1.0）和 HTML 已经存在，但 Web 更多地被看作是一个由相互链接的文档组成的网络。随着动态网页技术的兴起（如 CGI, ASP, PHP），网站开始提供更复杂的功能。然而，当时并没有一个统一、严谨的标准来指导如何设计这些交互。开发者们以各种方式创建“API”，导致 API 难以理解、难以维护，且无法充分利用 Web 基础设施（如缓存、代理等）。

2000年，罗伊·菲尔丁（Roy Thomas Fielding）在他的博士论文《Architectural Styles and the Design of Network-based Software Architectures》（架构风格与基于网络的软件架构设计）中，首次系统地阐述了 REST（Representational State Transfer，表述性状态转移）这一架构风格。

架构特征

按照REST提出的设计规范，一个基于RESTful架构的应用程序应该具备以下特征：

应用程序采用客户端-服务器(C/S)架构，其客户端和服务端在业务逻辑上是各自独立的，他们的具体分工如下：
- 客户端的主要任务是根据用户的操作向服务端请求指定的数据资源，并利用服务端返回的数据为用户提供良好的使用体验。
- 服务端的主要任务是监听并响应客户端的请求，并利用服务器资源为用户提供海量数据存储与大规模运算的服务。
客户端与服务端之间只能通过 HTTP 协议来进行数据交互，并在交互数据时使用 XML 或 JSON 这一类通用数据格式。在具体交互过程中：
- 客户端在响应用户操作时应始终以 URI 的形式向服务端请求服务，并在请求时至使用 HTTP 协议提供的 GET、POST、PUT、DELETE 方法来传递自己的请求信息。
- 服务端只能根据客户端所使用的 HTTP 请求方法和 URI 对数据库执行增、删、改、查等操作，并将处理结果作为响应数据返回给客户端。

六大约束

一个真正的 RESTful API 架构必须满足所有这些约束。

Uniform Interface（统一接口）
这是 RESTful API 的核心，它致力于让服务端业务逻辑以统一API 的方式向客户端提供服务，在一个完全遵循 RESTful 的团队里，后端只需要告诉前端 /users 这个 API，前端就应该知道: - 获取所有用户：GET /users
```
-  获取特定用户：`GET /users/{id}`  

-  创建用户：`POST /users`

-  更新用户：`PUT /users/{id}`

-  删除用户：`DELETE /users/{id}`
```
Client-Server（客户端和服务端分离）
- 它意味着客户端和服务器是独立的、可以分离的。
- 客户端是负责请求和处理数据的组件，服务器是负责存储数据和处理请求的组件。
- 这两个组件之间通过一组约定来协作，以便客户端能够获取所需的数据。
Statelessness（无状态）
- 它指的是每个请求都是独立的，没有前后关系。服务器不保存客户端的状态信息，并且每个请求都必须包含所有所需的信息。
- 这样做的好处是可以使每个请求变得简单，容易理解和处理，并且可以更容易地扩展和维护。
- 例如，假设你在登录一个网站，你需要在登录界面输入用户名和密码通过接口获取到了 token 。接下来的所有请求都需要携带上这个 token 而不是系统在第一次登录成功之后记录了你的状态。
Cacheability（可缓存）
- 客户端和服务端可以协商缓存内容，通过设置 HTTP 状态码，服务器可以告诉客户端这个数据是否可以被缓存。
- 例如，一个 HTTP 响应头中包含一个 Cache-Control 字段，用于告诉客户端该数据可以缓存多长时间。这样可以提高数据传输的效率，从而降低网络带宽的开销，加速数据的访问速度。
Layered System（分层）
- 客户端不应该关心请求经过了多少中间层，只需要关心请求的结果。
- 架构的系统可以分为多个层次，每一层独立完成自己的任务。这样的架构结构使得系统更容易维护，并且允许独立替换不同层次。
- 例如，数据库存储层可以独立于其他层，在不影响其他层的情况下进行替换或扩展。
Code on Demand（可选的代码请求）
- 它提倡服务器可以将客户端代码下载到客户端并执行。这样，客户端可以根据服务器发送的代码来扩展它的功能。
- 这个限制可以使客户端代码变得更加灵活，并且可以通过服务器提供的代码来解决问题，而不必再等待下一个版本。
- Code on Demand 是可选的，但它可以使 RESTful API 变得更加灵活和可扩展。

设计规范

如何设计一套合理、好用的 API ，REST 给出了以下约定：

HTTP 方法

使用标准的 HTTP 方法

- GET（SELECT）：从服务器取出资源（一项或多项）。

- POST（CREATE）：在服务器新建一个资源。

- PUT（UPDATE）：在服务器更新资源（客户端提供改变后的完整资源）。

- PATCH（UPDATE）：在服务器更新资源（客户端提供改变的属性）。

- DELETE（DELETE）：从服务器删除资源。

版本控制
版本控制是指在不影响现有的客户端应用的情况下，更新 RESTful API 的方法，常见的版本控制方式包括：
- URL 方法：通过改变 URL 来表示不同的版本，例如 https://api.example.com/api/v1/resources 和 https://api.example.com/api/v2/resources。
- Accept 标头：通过请求标头中的 Accept 字段来表示版本。
- 请求参数：通过请求中的参数来表示版本，例如 https://api.example.com/resources?version=1 和 https://api.example.com/resources?version=2。
清晰的 URI 设计
1. 使用复数名词(URI中不能出现动词)
```
GET /users
```
1. 层级表示关系
```
GET /users/eric/posts
```
1. 使用连字符 - 而非下划线 _
```
GET /published-posts
```
1. 使用查询参数进行过滤、排序、搜索:
```
GET /articles/{year}/{month}    # 路径参数
GET /articles?year={year}&month={month}    # query-string参数
```
合适的响应状态码

统一的响应格式

通常使用JSON作为数据交换格式。

{
  "code": 200,
  "message": "操作成功",
  "data": {
    "id": 1,
    "name": "张三"
  },
  "success": true
}

简洁美观的API文档