RESTFUL_API的基本概念

前面已经学习了API与HTTP的基本概念，现在我来整理一下RESTFUL的基本概念

REST API 全称 Representational State Transfer Application Programming Interface， 它基于REST架构风格，所以先来了解一下什么是REST架构风格

什么是 REST？

REST（Representational State Transfer，表述性状态转移）是一套用于设计网络应用接口的架构原则。你可以把它理解为一个 设计 API 的最佳实践指南。

REST 由 Roy Fielding 在 2000 年提出，它的目标是让 Web 服务更简单、可扩展、易于维护。

REST 的核心在于 六大设计原则：

1. 客户端-服务器分离（Client-Server）

• 前端（客户端）只负责用户交互；
• 后端（服务器）只负责数据处理和业务逻辑；
• 两者通过 API 通信，互不影响，便于独立开发和部署。

就像顾客只管点菜，厨房只管做菜，中间靠服务员（API）沟通。

2. 无状态性（Stateless）

• 每次请求必须包含所有必要信息；
• 服务器不会保存客户端的上下文状态；
• 这样设计让服务更可靠、可扩展（比如可以轻松加机器处理请求）。

每次去银行都要重新出示身份证——服务器不记得你是谁，除非你主动证明。

3. 可缓存性（Cacheable）

• 服务器可以在响应中标明“这个数据可以缓存”；
• 客户端或中间代理（如 CDN）就能缓存结果，减少重复请求，提升性能。

比如新闻列表一小时内不变，浏览器可以直接用缓存，不用再问服务器。

4. 统一接口（Uniform Interface）

这是 REST 最关键的原则！它要求所有 API 遵循一致的访问方式，包括：

• 使用标准的 HTTP 方法（GET、POST、PUT、DELETE）；
• URL 应该代表资源（用名词，不用动词）；
• 通过 HTTP 状态码表示结果（如 200 成功、404 未找到）；
• 使用标准格式（如 JSON）传递数据。

✅ 好例子：/users、/articles/123
❌ 坏例子：/getUsers、/deleteArticle?id=123

5. 分层系统（Layered System）

• 客户端不需要知道它是在和谁通信；
• 中间可以有负载均衡、API 网关、安全验证层等；
• 系统更安全、更灵活，也更容易维护。

架构可能是：前端 → 网关 → 认证服务 → 业务服务器 → 数据库

6. 按需代码（Code on Demand，可选）

• 服务器可以临时向客户端发送可执行代码（如 JavaScript）；
• 这个特性在实际 RESTful API 中很少使用，通常可忽略。

RESTful API 的主要设计理念

RESTful API 强调 “以资源为中心” 的设计理念：

• 一切皆资源：用户、文章、订单……都是“资源”；
• URL 表示资源：路径中只出现名词，不要出现动词；
• 操作由 HTTP 方法表示：用 GET、POST 等动词来表达“做什么”。

✅ 正确示例：

1
2
3
4
5
6

GET    /users          → 获取用户列表
POST   /users          → 创建新用户
GET    /users/123      → 获取 ID 为 123 的用户
PUT    /users/123      → 完整更新用户 123
PATCH  /users/123      → 部分更新用户 123
DELETE /users/123      → 删除用户 123

❌ 错误示例：

1
2

GET /getUser?id=123     → 混合了动词和参数
POST /deleteUser/123   → 用 POST 做删除，且 URL 含动词

这种设计让 API 更清晰、可预测，也更容易被其他开发者理解和使用。

RESTful API 的命名规范

RESTful有着一套自己的命名规范:

• 使用名词而非动词

1
2

✅ GET /api/books
❌ GET /api/getBooks

• 使用复数而非单数

1
2

✅ GET /api/users
❌ GET /api/user

• 使用小写字母

1
2

✅ GET /api/users
❌ GET /api/Users

• 使用连字符-分隔单词

1
2
3

✅ GET /api/user-books
❌ GET /api/user_books
❌ GET /api/userBooks

• 嵌套资源表示：当资源之间有从属关系时，可以使用嵌套 URL

1
2
3
4
5
6
7
8

// 获取用户 1 的所有订单
GET /api/users/1/orders

// 获取用户 1 的订单 666
GET /api/users/1/orders/666

// 为用户1 创建新订单
POST /api/users/1/orders

注意：嵌套资源不应该过深

• API版本控制 为了保持向后兼容，API 需要版本控制：

1
2
3

// URL 路径版本控制, 前面加上/api/v版本号
GET /api/v1/users
GET /api/v2/users

RESTful API 的请求与响应

请求与响应格式

RESTful API 的交互基于标准的 HTTP 请求与响应：

• 请求 通常包含：

  • 方法（如 GET、POST）
  • URL（如 /users/123）
  • 请求头（如 Content-Type: application/json）
  • 请求体（如创建用户时发送的 JSON 数据）

• 响应 通常包含：

  • 状态码（如 200 表示成功，404 表示资源未找到）
  • 响应头（如 Content-Type: application/json）
  • 响应体（如返回的用户信息）：

1
2
3
4
5

{
  "id": 123,
  "name": "张三",
  "email": "zhangsan@example.com"
}

这种统一的格式让前后端能高效、清晰地交换数据。

RESTful并没有明确规范请求体和响应体的具体格式，在实际场景中，还是要统一一下，规范有很多种，这里举个例子： ✅ 推荐的通用响应结构（成功）：

1
2
3
4
5
6
7
8

{
  "code": 200,
  "message": "success",
  "data": {
    "id": 123,
    "name": "张三"
  }
}

✅ 错误响应结构（失败）：

1
2
3
4
5

{
  "code": 404,
  "message": "用户不存在",
  "data": null
}

• code：业务状态码（可与 HTTP 状态码一致，也可自定义）
• message：人类可读的提示信息
• data：实际返回的数据（成功时有值，失败时可为 null）

总结

• REST 是一套设计 Web API 的架构原则；
• RESTful API 是遵循 REST 原则的 HTTP API；
• 核心思想：资源用 URL 表示，操作用 HTTP 方法表达；
• 优点：简单、统一、可扩展、跨平台。

掌握这些概念后，我们就能设计出清晰、专业、易用的 API 接口了

参考资料

• 菜鸟教程：RESTful API 入门