RESTful API 接口设计规范与实战
一、RESTful API 接口规范
REST 全称 Representational State Transfer,中文直译为表现层状态转移。
RE (Representational) 表现层
资源 (Resource) 指要操作的数据对象,比如用户、订单、商品等。表现层是指资源呈现出来的具体格式。同一个用户资源,可以用 JSON 格式返回给客户端,也可以用 XML 格式,这就是不同的表现形式。
S (State) 状态 状态是指资源在某一时刻的状态。有状态意味着服务器会在内存中记住客户端信息(如登录态),无状态则是服务器不记录任何客户端信息,每次请求都是独立的。
T (Transfer) 转移
转移是双向的:用 GET 请求时,服务器把资源的状态转移给客户端;用 POST 请求时,客户端把资源的新状态转移给服务器,从而改变服务器上资源的状态。
组合起来,REST 是一种软件架构风格,让客户端和服务器通过统一的接口以无状态的方式互相传递资源的表现层数据来查询或变更资源状态。因此 RESTful API 是指符合 REST 架构风格的 API。
注意:它不是协议,不是标准,也不是强制规范,只是一种建议的设计风格。你可以遵循,也可以根据业务场景调整。
例如,做一个用户管理系统,对用户信息进行增删改查,用 RESTful 风格的 API 如下所示:
GET /users/123获取 ID 为 123 的用户POST /users创建新用户PUT /users/123修改用户 123DELETE /users/123删除用户 123
对比一下非 RESTful 风格:
| 操作 | 非 RESTful | RESTful |
|---|---|---|
| 获取用户 | POST /getUser?id=1 | GET /users/1 |
| 创建用户 | POST /createUser | POST /users |
| 更新用户 | POST /update_user | PUT /users/1 |
| 删除用户 | POST /delete/user | DELETE /users/1 |
二、构造 RESTful API
2.1 客户端发送请求
2.1.1 确定资源
资源用 URI 统一资源标识符来表示,核心规则是用 名词 来表示资源,不用动词。
- 名称复数表示资源集合,如:
/users表示用户列表/products表示商品列表
- 具体某个资源,就加上 ID,如:


