RESTful API 接口设计规范详解
REST(Representational State Transfer)直译为表现层状态转移。这是一种软件架构风格,让客户端和服务器通过统一的接口以无状态的方式互相传递资源的表现层数据来查询或变更资源状态。
注意:它不是协议,不是标准,也不是强制规范,只是一种建议的设计风格。
一、核心概念解析
1. RE (Representational) 表现层
指资源(Resource)的表现形式。资源指要操作的数据对象,比如用户、订单、商品等。同一个用户资源,可以用 JSON 格式返回给客户端,也可以用 XML 格式返回,这就是不同的表现形式。
2. S (State) 状态
指资源在某一时刻的状态。有状态意味着服务器会在内存中记住客户端信息(如登录态),而无状态则是服务器不记录客户端的任何信息,每次请求都是独立的。
3. T (Transfer) 转移
转移是双向的。GET 请求时,服务器把资源的状态转移给客户端;POST 请求时,客户端把资源的新状态转移给服务器,从而改变服务器上资源的状态。
二、构造 RESTful API
1. 确定资源
资源用 URI 统一资源标识符来表示,核心规则是用名词表示资源,不用动词。
- 名称复数表示资源集合,如
/users表示用户列表,/products表示商品列表。 - 具体某个资源,就加上 ID,如
/users/123表示 ID 为 123 的用户。 - 支持嵌套,如
/users/123/orders获取用户 123 的所有订单。但建议不要嵌套层级太深。
2. 选择动作
主要通过不同的 HTTP 方法来表示增删改查操作。
- GET /users/123:获取 ID 为 123 的用户
- POST /users:创建新用户
- PUT /users/123:修改用户 123(完整更新,幂等性)
- PATCH /users/123:部分更新用户 123 的某些字段
- DELETE /users/123:删除用户 123
GET 查询资源
GET /users— 查询所有用户GET /users/123— 查询 ID 为 123 的用户
POST 创建资源
POST /users— 创建新用户
PUT 完整更新资源
调用时需要提供资源的所有字段,多次执行结果相同。
PUT /users/123— 完整更新用户 123
DELETE 删除资源
DELETE /users/123— 删除用户 123
3. 添加查询条件(可选)
有时我们需要更精确的筛选数据。RESTful 风格强调把筛选、排序、分页这些操作都通过 URL 参数来表达,而不是在请求体里面传复杂的 JSON 对象。
GET https://api.example.com/users?age=25&page=2&sort=created_at
- : — 查询第 2 页,每页 10 条


