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,表述性状态转移)这一架构风格。
.jpg)
架构特征
按照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 设计
- 使用复数名词(URI中不能出现动词)
GET /users- 层级表示关系
GET /users/eric/posts- 使用连字符
-而非下划线_
GET /published-posts- 使用查询参数进行过滤、排序、搜索:
GET /articles/{year}/{month} # 路径参数 GET /articles?year={year}&month={month} # query-string参数
合适的响应状态码
统一的响应格式
通常使用JSON作为数据交换格式。
{ "code": 200, "message": "操作成功", "data": { "id": 1, "name": "张三" }, "success": true }简洁美观的API文档

