代码规范：RESTful API 全面介绍

RESTful API 全面介绍

一、定义

RESTful API 是一种基于 REST （Representational State Transfer，表述性状态转移）架构风格设计的应用程序接口。

由 Roy Fielding 于 2000 年在其博士论文中提出，利用 HTTP 协议的特性，以资源为中心，通过标准方法对资源进行操作。

二、核心约束（六大原则）

约束	说明
客户端-服务器分离	前后端独立开发、部署，仅通过接口通信，职责解耦
无状态	每次请求须包含所有必要信息，服务器不保存客户端上下文（不依赖 Session）
可缓存	响应中标明是否可缓存，减少重复请求，提升传输效率
统一接口	标准 HTTP 方法 + 资源标识符 + 自描述消息，降低系统耦合度
分层系统	允许代理、网关、负载均衡等中间层存在，客户端无需感知最终服务器
按需代码（可选）	服务器可临时返回可执行代码（如 JavaScript）扩展客户端功能

三、关键实践

1. 资源与 URL 设计

资源使用名词复数命名，禁止动词出现在路径中
层级关系用斜线表达，保持语义清晰

✅ 推荐
GET /users // 获取用户列表
GET /users/5 // 获取单个用户
GET /users/5/orders // 获取该用户的订单

❌ 避免
GET /getUsers
POST /deleteUser/5

2. HTTP 方法语义

方法	语义	幂等	安全
`GET`	获取资源	✅	✅
`POST`	创建资源	❌	❌
`PUT`	全量替换资源	✅	❌
`PATCH`	部分更新资源	❌	❌
`DELETE`	删除资源	✅	❌

幂等：多次执行相同操作，结果一致。
安全：操作不会修改服务器资源状态。

3. HTTP 状态码规范

复制代码

2xx 成功
  200 OK                  // 请求成功
  201 Created             // 资源创建成功
  204 No Content          // 成功但无返回内容（如 DELETE）

3xx 重定向
  301 Moved Permanently   // 永久重定向
  304 Not Modified        // 缓存命中，资源未变更

4xx 客户端错误
  400 Bad Request         // 请求参数有误
  401 Unauthorized        // 未认证（需登录）
  403 Forbidden           // 已认证但无权限
  404 Not Found           // 资源不存在
  422 Unprocessable Entity // 语义错误（如字段校验失败）

5xx 服务端错误
  500 Internal Server Error // 服务器内部错误
  502 Bad Gateway           // 网关/代理错误
  503 Service Unavailable   // 服务暂时不可用

4. 响应格式（JSON 为主）

json 复制代码

{
  "code": 200,
  "message": "success",
  "data": {
    "id": 123,
    "name": "Alice",
    "email": "alice@example.com"
  },
  "_links": {
    "self":   { "href": "/users/123" },
    "orders": { "href": "/users/123/orders" }
  }
}

_links 字段体现 HATEOAS（超媒体即应用状态引擎），属于 REST 成熟度的最高级别。

5. 版本管理

http 复制代码

// 方式一：URL 路径（最直观，推荐）
GET /v1/users
GET /v2/users

// 方式二：请求头（更语义化）
Accept: application/vnd.myapi.v2+json

// 方式三：查询参数（不推荐，污染 URL）
GET /users?version=2

6. 过滤 / 分页 / 排序

http 复制代码

// 过滤
GET /users?role=admin&status=active

// 分页
GET /users?page=2&size=20

// 排序
GET /users?sort=createdAt,desc

// 字段裁剪（缓解过度获取问题）
GET /users?fields=id,name,email

7. 安全规范

机制	说明
HTTPS	全程加密传输，防止中间人攻击
JWT	无状态身份认证，适合分布式系统
OAuth 2.0	第三方授权标准，适合开放平台
限流（Rate Limiting）	防止接口被滥用，通常配合 `429 Too Many Requests`
CORS	跨域资源共享策略，控制哪些源可访问接口

四、完整示例：用户 API

http 复制代码

# 获取用户列表
GET /v1/users?page=1&size=10

# 获取单个用户
GET /v1/users/42

# 创建用户
POST /v1/users
Content-Type: application/json

{
  "name": "Bob",
  "email": "bob@example.com"
}

# 全量更新
PUT /v1/users/42
Content-Type: application/json

{
  "name": "Robert",
  "email": "robert@example.com"
}

# 部分更新
PATCH /v1/users/42
Content-Type: application/json

{
  "email": "new@example.com"
}

# 删除用户
DELETE /v1/users/42

五、优缺点总结

✅ 优点

基于 HTTP，简单轻量，易于理解、调试与接入
无状态设计，天然支持水平扩展
浏览器、移动端、服务端等全平台通用
利用 HTTP 缓存机制，减少冗余请求
生态成熟，工具链完善（Postman、Swagger、OpenAPI）

❌ 缺点

问题	说明	解决方案
过度获取（Over-fetching）	返回大量无用字段	Fields 参数 / GraphQL
不足获取（Under-fetching）	需多次请求才能拼装数据	BFF 层 / GraphQL
实时推送能力弱	基于请求-响应模型	WebSocket / SSE
强类型约束缺失	接口契约靠文档维护	OpenAPI / gRPC

六、REST 成熟度模型（Richardson Model）

复制代码

Level 0 --- 单一 URI，所有操作靠 POST 区分（RPC 风格）
Level 1 --- 引入资源概念，不同资源对应不同 URI
Level 2 --- 使用 HTTP 方法语义（GET/POST/PUT/DELETE）+ 状态码  ← 业界主流
Level 3 --- HATEOAS，响应中携带超媒体链接，实现自描述导航

七、RESTful vs 其他方案

维度	RESTful	GraphQL	gRPC
协议	HTTP	HTTP	HTTP/2
数据格式	JSON/XML	JSON	Protobuf（二进制）
查询灵活性	一般	极高	一般
实时推送	弱（需 WebSocket）	支持 Subscription	支持流式
性能	中	中	高
适用场景	通用 Web API	复杂数据查询	微服务内部通信

总结

RESTful API 是目前 Web 服务的主流设计风格 ，凭借其简洁性、可扩展性和与 HTTP 协议的天然契合，广泛应用于前后端分离、移动端接口、开放平台等场景。

在复杂查询或强实时性要求的场景下，可结合 GraphQL 、gRPC 或 WebSocket 灵活补充，按需选型。