RESTful API 规范详解 - 直观图示教程
RESTful API 规范详解
用最直观的方式理解现代 API 设计规范
核心概念对比
传统 API 设计的问题
常见问题
-
URL 设计问题 : 包含动词 ( 如
getUsers或deleteOrder)，不符合资源导向原则 - HTTP 方法滥用 : 操作类型 (GET/POST 等 ) 与 URL 混合使用，导致语义不清
- 状态管理问题 : 服务端需要维护会话状态，违背 REST 无状态原则
- 数据格式混乱 : 返回数据格式缺乏统一标准，不同接口结构不一致
- 状态码滥用 : 错误处理不规范，所有错误都返回 200 状态码
典型的反 REST 风格
GET
/getUsers?userId=123
200 OK
{
"users": [
{"id": 123, "name": "John Doe"}
]
}
RESTful API 最佳实践
核心原则
-
资源导向设计 : URL 只使用名词表示资源 ( 如
/users或/orders) -
HTTP 方法语义化 : 严格使用标准方法表示操作
GET: 获取资源POST: 创建资源PUT: 全量更新资源PATCH: 部分更新资源DELETE: 删除资源
- 无状态设计 : 每个请求包含完整信息，服务端不保存会话状态
- 数据格式标准化 : 统一使用 JSON 格式，包含标准字段
-
HTTP 状态码规范 : 正确使用标准状态码
200: 成功请求201: 资源创建成功400: 客户端错误401: 未授权404: 资源不存在500: 服务器错误
示例代码
GET
/api/users/{id}
?page=1
200 OK
{
"data": {
"id": 123,
"name": "John Doe"
},
"links": {
"self": "/api/users/123"
}
}
四大设计原则
资源导向
核心要点
- 将系统功能抽象为资源
- 每个资源有唯一 URI
- 支持多种资源类型（物理 / 逻辑）
正确示例
GET
/api/orders/{orderId}
200 OK
{
"order_id": "ORD-123",
"total": 199.99,
"items": [...]
}
标准方法
HTTP 方法
GET
POST
PUT
DELETE
PATCH
使用场景
POST
/api/products
201 Created
{
"product_id": "PROD-456",
"location": "/api/products/PROD-456"
}
无状态
核心要点
- 每个请求都包含所有必要信息
- 服务器不保存客户端状态
- 状态由客户端维护
示例代码
GET
/api/users/123
200 OK
Authorization: Bearer <token>
统一接口
核心要点
- 自描述消息
- 资源表现形式协商
- HATEOAS
示例代码
GET
/api/users/123
200 OK
{
"Content-Type": "application/json",
"Accept": "application/json"
}
进阶特性
认证与授权
常用方式
- Bearer Token（推荐）
- OAuth 2.0
- API Key
- JWT
示例
Authorization: Bearer <token>
错误处理
GET
/api/protected
401 Unauthorized
{
"error": "Missing token",
"code": 401,
"documentation_url": "https://api.example.com/docs/auth"
}
HATEOAS
核心概念
- Hypermedia As The Engine Of Application State
- 响应中包含相关链接
- 实现客户端与服务端解耦
示例代码
GET
/api/users/123
200 OK
{
"user": {
"id": 123,
"name": "John Doe",
"email": "john@example.com"
},
"links": {
"self": "/api/users/123",
"orders": "/api/users/123/orders",
"update_profile": "/api/users/123/profile"
}
}
分页与过滤
常用参数
- page：页码
- limit：每页数量
- sort：排序字段
- filter：过滤条件
分页示例
GET /api/products?page=2&limit=20&sort=-price
过滤示例
GET /api/orders?filter[status]=completed&filter[amount][gt]=100
响应示例
GET
/api/products
200 OK
{
"data": [...],
"meta": {
"current_page": 2,
"per_page": 20,
"total": 100,
"last_page": 5
}
}
常用状态码
200 OK
201 Created
204 No Content
400 Bad Request
401 Unauthorized
403 Forbidden
404 Not Found
405 Method Not Allowed
422 Unprocessable Entity
500 Internal Server Error
