目录 (12)
RESTful API 架构
REST(Representational State Transfer)是一种软件架构风格,它的提出是为了给 Web 开发提供指导方针,并描述 Web 的结构。
1. REST 架构的特点
RESTful API 的核心在于,不把 URL 看作 Endpoint,而是把它看作一种资源,并且通过保持一致性来变得可预测。据说下面这些就是 REST 架构所具有的特性。
1.1 Stateless 无状态性
在客户端-服务器的请求中,不保存客户端的信息,每个请求都应该是相互独立的。
1.2 Client-Server 结构
由客户端、服务器和资源构成,通过 HTTP 发起请求。
1.3 数据缓存
让数据可以被缓存,从而尽量减少客户端与服务器之间的交互。
1.4 统一接口
资源必须是可识别的,并且要与发送给客户端的表述区分开来。
另外,资源应该通过接收到的表述来进行操作。
对于客户端来说,自描述消息中应当充分包含说明该如何处理这些信息的内容。(Content-type、method、encoding 等)
1.5 支持分层架构
服务器可以拥有按层次结构(安全、负载均衡等)组织起来的分层系统。
1.6 按需代码(Code on Demand)
收到请求后,服务器可以向客户端发送可执行的代码,从而扩展客户端的功能。
2. 方法与状态整理
在 RESTful API 中,通过 HTTP 方法来表示对资源的操作,服务器根据这个方法进行处理,并在 Response 中传递状态码来表示响应的状态。
2.1 方法
方法 | 说明 | 主要用途 | 幂等性(Idempotent) | 安全性(Safe) | 示例 URI |
|---|---|---|---|---|---|
GET | 查询资源 | 查询数据 | ✅ 是(同一请求执行多次,结果也相同) | ✅ 是(不会改变服务器状态) | /users/1 |
POST | 创建资源 | 添加数据 | ❌ 否 | ❌ 否 | /users |
PUT | 整体修改资源 | 整体更新数据 | ✅ 是 | ❌ 否 | /users/1 |
PATCH | 部分修改资源 | 部分更新数据 | ❌ 通常为否(取决于服务器实现) | ❌ 否 | /users/1 |
DELETE | 删除资源 | 删除数据 | ✅ 是(即使已经删除,也可以返回相同的响应) | ❌ 否 | /users/1 |
OPTIONS | 查询支持的方法 | CORS 预检请求等 | ✅ 是 | ✅ 是 | /users |
HEAD | 只查询资源的头部(没有正文) | 确认元数据 | ✅ 是 | ✅ 是 | /users/1 |
2.2 状态
状态 | 状态码 | 含义 | 说明 | 使用示例 |
|---|---|---|---|---|
(2xx) | 200 OK | 请求成功 | 用于 GET、PUT、PATCH、DELETE 等 | 数据查询成功 |
201 Created | 已创建 | 通过 POST 请求创建资源时使用 | 注册会员、发布文章等 | |
204 No Content | 无内容 | 请求成功但没有响应正文时 | DELETE、PUT 成功后无响应内容 | |
(3xx) | 301 Moved Permanently | 永久移动 | 资源已被永久移动 | 提示 URL 已变更 |
302 Found | 临时移动 | 资源暂时位于其他位置 | 登录后重定向 | |
304 Not Modified | 未修改 | 可以直接使用缓存的资源 | 条件 GET(If-Modified-Since 等) | |
(4xx) | 400 Bad Request | 错误请求 | 参数无效等 | 缺少字段、JSON 解析失败 |
401 Unauthorized | 需要认证 | 需要登录或令牌错误 | 没有 JWT / JWT 已过期 | |
403 Forbidden | 禁止访问 | 没有权限时 | 仅限管理员访问 | |
404 Not Found | 资源不存在 | 请求了不存在的 URI | 用错误的 ID 查询时 | |
409 Conflict | 冲突 | 创建重复资源时等 | 重复创建相同 ID 等 | |
422 Unprocessable Entity | 无法处理 | 格式正确但语义有误 | 表单验证失败等 | |
(5xx) | 500 Internal Server Error | 服务器内部错误 | 服务器内部发生异常 | 意料之外的错误 |
502 Bad Gateway | 网关错误 | 服务器收到了错误的响应 | 代理、网关问题 | |
503 Service Unavailable | 服务不可用 | 服务器维护中或过载 | 服务器宕机、维护 | |
504 Gateway Timeout | 网关超时 | 响应延迟 | 后端响应延迟时 |
3. 理查森成熟度模型(Richardson Maturity Model)
理查森(Richardson)为了更好地应用 REST API,定义了一个 4 级的成熟度模型。

