RESTful API

RESTful API 是一种基于 HTTP 协议设计 Web 接口的架构风格，全称是 Representational State Transfer（表述性状态转移）。它不是一种技术或框架，而是一套设计原则和约束条件，用来规范客户端与服务器之间如何通信。

---

核心设计原则

• 资源导向：一切皆资源，每个资源都有唯一的 URI（统一资源标识符）。例如：/users/1 表示 ID 为 1 的用户。
• 统一接口：使用标准 HTTP 方法操作资源：无状态：每次请求都包含完整信息，服务器不保存客户端状态（如会话信息需通过 Token 传递）。
  • GET：获取资源（如获取用户列表）
  • POST：创建资源（如新建用户）
  • PUT：全量更新资源（如修改用户全部信息）
  • PATCH：部分更新资源（如只改用户邮箱）
  • DELETE：删除资源
• 可缓存：响应应明确标注是否可缓存，提升性能。
• 分层系统：客户端无需知道是否直接连接服务器，中间可有代理、网关等。

---

一个简单示例

假设管理用户资源：

操作	HTTP 方法	URI	说明
获取所有用户	GET	/users	返回用户列表
获取单个用户	GET	/users/1	返回 ID 为 1 的用户
创建用户	POST	/users	请求体携带用户数据
更新用户	PUT	/users/1	替换 ID 为 1 的用户数据
删除用户	DELETE	/users/1	删除 ID 为 1 的用户
获取用户订单	GET	/users/1/orders	嵌套资源

---

响应格式

通常使用 JSON 格式返回数据：

{
  "code": 200,
  "data": {
    "id": 1,
    "name": "张三",
    "email": "zhangsan@example.com"
  },
  "message": "success"
}

---

常见状态码

• 200 OK：请求成功
• 201 Created：资源创建成功
• 400 Bad Request：客户端请求有误
• 401 Unauthorized：未认证
• 403 Forbidden：无权限
• 404 Not Found：资源不存在
• 500 Internal Server Error：服务器内部错误

---

优点

• 简洁易懂：基于 HTTP 标准，学习成本低。
• 跨平台：任何语言都能调用（Java、Python、JavaScript、Go 等）。
• 可扩展：前后端分离架构的理想选择。
• 广泛支持：几乎所有 Web 框架都原生支持（Spring Boot、Express、Django、Flask 等）。

---

缺点

• 无状态导致重复传输：每次请求需携带认证信息。
• 过度请求：复杂数据可能需要多次请求（可通过 GraphQL 优化）。
• 版本管理麻烦：接口变更需考虑兼容性，通常通过 URL 版本（/v1/users）或 Header 控制。

---