【软件工程】RESTful API-基于HTTP协议的架构风格

REST 的核心概念REST（）是一种基于 HTTP 协议的架构风格，由 Roy Fielding 在 2000 年提出。其核心思想是将网络资源抽象为可通过URI（统一资源标识符）访问的实体，并通过标准的 HTTP 方法（GET、POST 等）操作这些资源。核心目标解耦客户端与服务器：前后端独立开发，通过接口交互。无状态性：每个请求包含完整上下文，服务器不保存客户端状态。可扩展性：支持缓存、分层代

浩水飞鸽(晴雨)

1124人浏览 · 2025-05-09 06:22:30

浩水飞鸽(晴雨) · 2025-05-09 06:22:30 发布

文章目录

- - RESTful API 详细介绍

RESTful API 详细介绍

1. REST 的核心概念

REST（Representational State Transfer）是一种基于 HTTP 协议的架构风格，由 Roy Fielding 在 2000 年提出。其核心思想是将网络资源抽象为可通过 URI（统一资源标识符） 访问的实体，并通过标准的 HTTP 方法（GET、POST 等）操作这些资源。
核心目标：

解耦客户端与服务器：前后端独立开发，通过接口交互。
无状态性：每个请求包含完整上下文，服务器不保存客户端状态。
可扩展性：支持缓存、分层代理等机制，适应高并发场景。

2. RESTful API 的六大原则

客户端-服务器分离
- 客户端负责用户界面和交互，服务器负责数据处理和存储。
- 通过标准化接口（如 HTTP）通信，降低耦合度。
无状态（Stateless）
- 每个请求必须包含所有必要信息（如认证 Token、参数）。
- 服务器不会存储客户端会话状态（如 Session），适合水平扩展。
可缓存（Cacheable）
- 服务器需明确响应是否可缓存（通过 Cache-Control 头部）。
- 减少重复请求，提升性能（如 GET /articles 可缓存）。
统一接口（Uniform Interface）
- 资源标识：通过 URI 唯一标识资源（如 /users/123）。
- 表述操作：资源与表现形式分离（如 JSON、XML）。
- 自描述消息：请求和响应包含元数据（如 Content-Type: application/json）。
- HATEOAS（Hypermedia as the Engine of Application State）：响应中包含相关资源的链接，客户端通过链接导航。
```
{
  "id": 123,
  "name": "Alice",
  "links": [
    { "rel": "self", "href": "/users/123" },
    { "rel": "orders", "href": "/users/123/orders" }
  ]
}
```
分层系统（Layered System）
- 客户端无需了解中间层（如负载均衡器、代理服务器、防火墙）。
- 中间层可增强安全性、性能（如 CDN 缓存静态资源）。
按需代码（Code-On-Demand，可选）
- 服务器可返回可执行代码（如 JavaScript），扩展客户端功能。

3. 核心设计要素

3.1 资源（Resource）

每个资源对应一个 URI，URI 应为名词而非动词，如：
- GET /users（获取用户列表）
- GET /users/{id}（获取单个用户）
URI 设计规范：
- 使用小写字母和连字符（/user-roles）。
- 避免暴露服务器架构（如 /api/v1 而非 /php/api）。
- 嵌套资源表示层级关系：
```
GET /users/{userId}/orders       # 获取用户的订单  
DELETE /users/{userId}/orders/{orderId}  # 删除用户某个订单  
```

3.2 HTTP 方法

方法	语义	幂等性	示例
GET	获取资源	是	`GET /users`
POST	创建资源或触发操作	否	`POST /users`
PUT	替换整个资源	是	`PUT /users/{id}`
PATCH	部分更新资源	否	`PATCH /users/{id}`
DELETE	删除资源	是	`DELETE /users/{id}`

幂等性：多次执行同一请求的效果与单次执行相同（如 PUT、DELETE）。

3.3 HTTP 状态码

状态码	类别	常见场景
200	成功	`GET` 成功
201	已创建	`POST` 创建资源成功，响应头包含 `Location: /users/123`
204	无内容	`DELETE` 成功或 `PUT` 更新后无需返回数据
400	客户端错误	请求参数错误（如缺少必填字段）
401	未授权	未提供认证信息（如 Token）
403	禁止访问	认证成功但无权操作资源
404	未找到	URI 对应的资源不存在
429	请求过多	客户端触发速率限制
500	服务器错误	服务器内部错误（如数据库连接失败）

3.4 请求与响应格式

请求头：指定数据格式和认证信息。

GET /users/123 HTTP/1.1
Accept: application/json
Authorization: Bearer <token>

响应体：通常使用 JSON 或 XML。

{
  "id": 123,
  "name": "Alice",
  "email": "alice@example.com"
}

错误响应：包含错误详情。

{
  "error": {
    "code": "invalid_request",
    "message": "Missing required field: email"
  }
}

4. 进阶设计技巧

4.1 分页与过滤

分页：使用 limit 和 offset 参数或 page 和 size。

GET /articles?page=2&size=20

响应中返回分页元数据：

{
  "data": [...],
  "pagination": {
    "total": 100,
    "page": 2,
    "size": 20
  }
}

过滤与排序：

GET /products?category=electronics&price_gte=100&sort=-price

4.2 版本控制

URI 路径：/api/v1/users
请求头：Accept: application/vnd.myapi.v1+json

4.3 批量操作

批量创建：

POST /users/bulk
Content-Type: application/json

[{"name": "Alice"}, {"name": "Bob"}]

4.4 HATEOAS 实现

在响应中嵌入资源链接，引导客户端发现后续操作：

{
  "id": 123,
  "name": "Alice",
  "_links": {
    "self": { "href": "/users/123" },
    "orders": { "href": "/users/123/orders" }
  }
}

5. 安全与认证

HTTPS：强制使用 TLS 加密通信。
认证方式：
- OAuth 2.0：通过授权服务器颁发 Token（如 Authorization: Bearer <token>）。
- JWT（JSON Web Token）：自包含的 Token，包含用户信息和签名。
权限控制：基于角色的访问控制（RBAC），如：
- 普通用户只能读写自己的资源（GET /users/me）。
- 管理员可访问所有资源（GET /users）。

6. 常见问题与解决方案

跨域请求（CORS）：配置服务器返回 Access-Control-Allow-Origin 头部。

文件上传：使用 multipart/form-data 格式：

POST /upload
Content-Type: multipart/form-data

--boundary
Content-Disposition: form-data; name="file"; filename="photo.jpg"

<binary data>

性能优化：
- 启用 Gzip 压缩。
- 使用缓存策略（如 Cache-Control: max-age=3600）。

7. 工具与生态

API 文档：
- Swagger/OpenAPI：通过 YAML 或 JSON 描述 API，生成交互式文档。
- Postman：测试 API 请求并生成文档。
框架支持：
- Node.js：Express、NestJS。
- Python：Django REST Framework、FastAPI。
- Java：Spring Boot。

8. REST 与其他 API 风格对比

特性	REST	GraphQL	gRPC
协议	HTTP/1.1	HTTP/2	HTTP/2
数据格式	JSON/XML	JSON	Protobuf（二进制）
灵活性	固定端点	客户端自定义查询	强类型接口
适用场景	简单 CRUD 操作	复杂查询与聚合	高性能微服务通信