REST API 简介 #
什么是 API？ #
在了解 REST API 之前，我们需要先理解 API（Application Programming Interface，应用程序编程接口）的概念。API 是软件系统之间进行通信的桥梁。
text
┌─────────────────────────────────────────────────────────────┐
│ API 的本质 │
├─────────────────────────────────────────────────────────────┤
│ │
│ 类比： │
│ │
│ ┌─────────┐ API 调用 ┌─────────┐ │
│ │ 应用A │ ───────────────> │ 应用B │ │
│ └─────────┘ └─────────┘ │
│ │
│ 就像： │
│ - 餐厅菜单：告诉你可以点什么菜 │
│ - 遥控器：告诉你如何控制电视 │
│ - 服务窗口：告诉你如何办理业务 │
│ │
└─────────────────────────────────────────────────────────────┘
API 的类型 #
text
┌─────────────────────────────────────────────────────────────┐
│ API 类型分类 │
├─────────────────────────────────────────────────────────────┤
│ │
│ 1. 库/框架 API │
│ - 编程语言内部调用 │
│ - 如：jQuery API、React API │
│ │
│ 2. 操作系统 API │
│ - 系统级功能调用 │
│ - 如：Windows API、POSIX API │
│ │
│ 3. Web API（本系列重点） │
│ - 网络服务接口 │
│ - 如：REST API、GraphQL API │
│ │
└─────────────────────────────────────────────────────────────┘
什么是 REST？ #
REST（Representational State Transfer，表述性状态转移）是一种软件架构风格，由 Roy Fielding 在 2000 年的博士论文中提出。它定义了一组设计 Web 服务的约束条件和原则。
核心定位 #
text
┌─────────────────────────────────────────────────────────────┐
│ REST │
├─────────────────────────────────────────────────────────────┤
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ 资源导向 │ │ 无状态 │ │ 统一接口 │ │
│ └─────────────┘ └─────────────┘ └─────────────┘ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ 分层系统 │ │ 可缓存 │ │ 按需代码 │ │
│ └─────────────┘ └─────────────┘ └─────────────┘ │
└─────────────────────────────────────────────────────────────┘
REST 解决的问题 #
text
┌─────────────────────────────────────────────────────────────┐
│ REST 解决的问题 │
├─────────────────────────────────────────────────────────────┤
│ │
│ 传统 Web 服务问题： │
│ │
│ 1. SOAP 协议复杂 │
│ - XML 格式冗余 │
│ - 学习成本高 │
│ - 开发效率低 │
│ │
│ 2. 接口设计混乱 │
│ - 命名不规范 │
│ - 动词混用 │
│ - 难以理解和使用 │
│ │
│ 3. 耦合度高 │
│ - 客户端与服务端紧密耦合 │
│ - 难以扩展和维护 │
│ │
│ REST 解决方案： │
│ │
│ ✅ 简单：基于 HTTP 协议，易于理解和使用 │
│ ✅ 统一：标准化接口设计，降低学习成本 │
│ ✅ 解耦：客户端与服务端独立发展 │
│ ✅ 可扩展：支持分层架构，易于扩展 │
│ │
└─────────────────────────────────────────────────────────────┘
REST 的历史 #
发展历程 #
text
1994年 ─── HTTP/1.0 发布
│
│ Web 基础协议
│ 简单的请求响应
│
│
│ Roy Fielding 提出
│ HTTP 协议的设计原则
│ 架构风格定义
│
2002年 ─── REST 流行
│
│ Web 2.0 兴起
│ Ajax 技术普及
│ API 需求增长
│
2006年 ─── REST 框架涌现
│
│ Ruby on Rails
│ Django REST Framework
│ Spring MVC
│
2010年 ─── REST 成为主流
│
│ 移动互联网爆发
│ 微服务架构兴起
│ 云原生应用
│
至今 ─── 行业标准
│
│ 几乎所有 Web API
│ 微服务通信标准
│ 云服务接口规范
里程碑事件 #
| 时间 | 事件 | 意义 |
|---|---|---|
| 1994 | HTTP/1.0 | Web 协议基础 |
| 1999 | HTTP/1.1 | 完善 HTTP 方法 |
| 2000 | REST 论文 | 架构风格定义 |
| 2006 | AWS S3 API | REST 商业化成功 |
| 2010 | GitHub API | REST 最佳实践 |
| 2015 | HTTP/2 | 性能优化 |
REST 的六大约束 #
1. 统一接口（Uniform Interface） #
text
┌─────────────────────────────────────────────────────────────┐
│ 统一接口约束 │
├─────────────────────────────────────────────────────────────┤
│ │
│ 核心原则： │
│ │
│ 1. 资源标识（Identification of Resources） │
│ - 使用 URI 标识资源 │
│ - /users/123 │
│ - /products/456 │
│ │
│ 2. 通过表述操作资源（Manipulation through Representations） │
│ - 使用 JSON/XML 表示资源 │
│ - 通过表述执行操作 │
│ │
│ 3. 自描述消息（Self-descriptive Messages） │
│ - 请求包含所有必要信息 │
│ - 响应包含状态说明 │
│ │
│ 4. 超媒体作为应用状态引擎（HATEOAS） │
│ - 响应包含相关链接 │
│ - 引导客户端进行下一步操作 │
│ │
└─────────────────────────────────────────────────────────────┘
2. 无状态（Stateless） #
text
┌─────────────────────────────────────────────────────────────┐
│ 无状态约束 │
├─────────────────────────────────────────────────────────────┤
│ │
│ 定义： │
│ 每个请求必须包含服务端处理所需的所有信息 │
│ 服务端不保存客户端会话状态 │
│ │
│ 有状态 vs 无状态： │
│ │
│ 有状态： │
│ 请求1: 登录 ───> 服务端保存用户状态 │
│ 请求2: 获取数据 ───> 服务端查找用户状态 │
│ │
│ 无状态： │
│ 请求1: 登录 ───> 返回 Token │
│ 请求2: 获取数据 + Token ───> 服务端验证 Token │
│ │
│ 优势： │
│ ✅ 可扩展性：任何服务器都能处理请求 │
│ ✅ 可靠性：服务器崩溃不影响其他服务器 │
│ ✅ 可见性：请求包含所有信息，便于监控 │
│ │
└─────────────────────────────────────────────────────────────┘
3. 客户端-服务端分离（Client-Server） #
text
┌─────────────────────────────────────────────────────────────┐
│ 客户端-服务端分离 │
├─────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────┐ ┌─────────────────┐ │
│ │ 客户端 │ │ 服务端 │ │
│ ├─────────────────┤ ├─────────────────┤ │
│ │ - 用户界面 │ │ - 数据存储 │ │
│ │ - 用户交互 │◄────────────►│ - 业务逻辑 │ │
│ │ - 请求发送 │ HTTP │ - 请求处理 │ │
│ │ - 响应展示 │ │ - 响应生成 │ │
│ └─────────────────┘ └─────────────────┘ │
│ │
│ 关注点分离： │
│ - 客户端关注用户体验 │
│ - 服务端关注数据处理 │
│ - 两者独立发展、独立部署 │
│ │
└─────────────────────────────────────────────────────────────┘
4. 可缓存（Cacheable） #
text
┌─────────────────────────────────────────────────────────────┐
│ 可缓存约束 │
├─────────────────────────────────────────────────────────────┤
│ │
│ 定义： │
│ 响应数据应该标明是否可缓存，以及缓存策略 │
│ │
│ 缓存控制示例： │
│ │
│ HTTP/1.1 200 OK │
│ Cache-Control: max-age=3600, public │
│ ETag: "33a64df551425fcc55e4d42a148795d9f25f89d4" │
│ Last-Modified: Wed, 21 Oct 2025 07:28:00 GMT │
│ │
│ 优势： │
│ ✅ 减少网络延迟 │
│ ✅ 降低服务器负载 │
│ ✅ 提高响应速度 │
│ │
└─────────────────────────────────────────────────────────────┘
5. 分层系统（Layered System） #
text
┌─────────────────────────────────────────────────────────────┐
│ 分层系统约束 │
├─────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────┐ │
│ │ 客户端 │ │
│ └────┬────┘ │
│ │ │
│ ┌────▼────┐ ┌─────────┐ │
│ │ 负载均衡 │────►│ API网关 │ │
│ └─────────┘ └────┬────┘ │
│ │ │
│ ┌────────────────────┼────────────────────┐ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ ┌─────┐ ┌─────┐ ┌─────┐ │
│ │服务A│ │服务B│ │服务C│ │
│ └──┬──┘ └──┬──┘ └──┬──┘ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ ┌─────┐ ┌─────┐ ┌─────┐ │
│ │ DB1 │ │ DB2 │ │ DB3 │ │
│ └─────┘ └─────┘ └─────┘ │
│ │
│ 客户端不知道它连接的是终端服务器还是中间层 │
│ 每一层都可以独立扩展和管理 │
│ │
└─────────────────────────────────────────────────────────────┘
6. 按需代码（Code on Demand）- 可选 #
text
┌─────────────────────────────────────────────────────────────┐
│ 按需代码约束 │
├─────────────────────────────────────────────────────────────┤
│ │
│ 定义： │
│ 服务端可以临时扩展客户端功能，通过传输可执行代码 │
│ │
│ 示例： │
│ - JavaScript 脚本 │
│ - Java Applet（已废弃） │
│ - Flash（已废弃） │
│ │
│ 现代应用： │
│ - 动态加载 JavaScript 模块 │
│ - Web Components │
│ - 服务端推送配置 │
│ │
│ 注意：这是唯一可选的约束 │
│ │
└─────────────────────────────────────────────────────────────┘
RESTful API 的核心概念 #
资源（Resource） #
text
┌─────────────────────────────────────────────────────────────┐
│ 资源概念 │
├─────────────────────────────────────────────────────────────┤
│ │
│ 定义： │
│ 资源是 REST 架构的核心概念，表示任何可以被命名的事物 │
│ │
│ 资源示例： │
│ - 用户（User） │
│ - 订单（Order） │
│ - 商品（Product） │
│ - 评论（Comment） │
│ │
│ 资源标识： │
│ - 使用 URI（统一资源标识符）标识 │
│ - /users/123 │
│ - /orders/456 │
│ │
│ 资源表述： │
│ - JSON 格式（最常用） │
│ - XML 格式 │
│ - HTML 格式 │
│ │
└─────────────────────────────────────────────────────────────┘
表述（Representation） #
text
┌─────────────────────────────────────────────────────────────┐
│ 表述概念 │
├─────────────────────────────────────────────────────────────┤
│ │
│ 定义： │
│ 资源在特定时刻的状态快照，以某种格式呈现 │
│ │
│ JSON 表述示例： │
│ { │
│ "id": 123, │
│ "name": "张三", │
│ "email": "zhangsan@example.com", │
│ "createdAt": "2025-01-15T10:30:00Z" │
│ } │
│ │
│ 同一资源可以有多种表述： │
│ - JSON（application/json） │
│ - XML（application/xml） │
│ - HTML（text/html） │
│ - 图片（image/png） │
│ │
└─────────────────────────────────────────────────────────────┘
状态转移（State Transfer） #
text
┌─────────────────────────────────────────────────────────────┐
│ 状态转移概念 │
├─────────────────────────────────────────────────────────────┤
│ │
│ 定义： │
│ 客户端通过操作资源表述，实现应用状态的转移 │
│ │
│ 状态转移示例： │
│ │
│ 初始状态：用户未登录 │
│ ┌─────────┐ │
│ │ Guest │ │
│ └─────────┘ │
│ │ │
│ │ POST /auth/login │
│ │ { "username": "admin", "password": "xxx" } │
│ ▼ │
│ 转移后状态：用户已登录 │
│ ┌─────────┐ │
│ │ Admin │ │
│ └─────────┘ │
│ │
│ 这就是 REST（表述性状态转移）名称的由来 │
│ │
└─────────────────────────────────────────────────────────────┘
RESTful API vs 传统 API #
对比示例 #
text
┌─────────────────────────────────────────────────────────────┐
│ 传统 RPC 风格 API │
├─────────────────────────────────────────────────────────────┤
│ │
│ GET /getAllUsers │
│ GET /getUserById?id=123 │
│ POST /createUser │
│ POST /updateUser │
│ POST /deleteUser?id=123 │
│ │
│ 问题： │
│ ❌ URL 中包含动词，语义混乱 │
│ ❌ 使用 GET 执行删除操作 │
│ ❌ 接口命名不统一 │
│ ❌ 难以理解和维护 │
│ │
└─────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────┐
│ RESTful API │
├─────────────────────────────────────────────────────────────┤
│ │
│ GET /users 获取用户列表 │
│ GET /users/123 获取指定用户 │
│ POST /users 创建用户 │
│ PUT /users/123 更新用户（完整） │
│ PATCH /users/123 更新用户（部分） │
│ DELETE /users/123 删除用户 │
│ │
│ 优势： │
│ ✅ URL 只包含名词，表示资源 │
│ ✅ HTTP 方法表示操作类型 │
│ ✅ 接口规范统一 │
│ ✅ 易于理解和维护 │
│ │
└─────────────────────────────────────────────────────────────┘
详细对比 #
| 特性 | 传统 API | RESTful API |
|---|---|---|
| URL 设计 | 动词+名词 | 纯名词 |
| 操作表达 | URL 中体现 | HTTP 方法 |
| 状态管理 | 有状态 | 无状态 |
| 可缓存性 | 较差 | 良好 |
| 可扩展性 | 一般 | 优秀 |
| 学习成本 | 各不相同 | 统一标准 |
RESTful API 的优势 #
1. 简单统一 #
text
✅ 基于 HTTP 协议
- 无需额外学习新协议
- 工具支持完善
- 调试方便
✅ 标准化接口
- 统一的 URL 设计
- 统一的 HTTP 方法使用
- 统一的状态码
2. 可扩展性 #
text
✅ 无状态设计
- 任何服务器都能处理请求
- 水平扩展简单
✅ 分层架构
- 可以添加负载均衡
- 可以添加缓存层
- 可以添加安全层
3. 松耦合 #
text
✅ 客户端与服务端独立
- 前后端分离开发
- 技术栈独立选择
- 独立部署和扩展
4. 可见性 #
text
✅ 请求自描述
- 包含所有必要信息
- 便于监控和调试
- 便于缓存和代理
RESTful API 的局限性 #
1. 多次请求问题 #
text
┌─────────────────────────────────────────────────────────────┐
│ 多次请求问题 │
├─────────────────────────────────────────────────────────────┤
│ │
│ 场景：获取用户及其所有订单 │
│ │
│ RESTful 方式： │
│ 1. GET /users/123 获取用户信息 │
│ 2. GET /users/123/orders 获取用户订单 │
│ │
│ 问题： │
│ ⚠️ 需要多次请求 │
│ ⚠️ 网络开销大 │
│ │
│ 解决方案： │
│ - GraphQL（按需查询） │
│ - 嵌入资源（Embedding Resources） │
│ - 批量接口 │
│ │
└─────────────────────────────────────────────────────────────┘
2. 版本管理 #
text
┌─────────────────────────────────────────────────────────────┐
│ 版本管理问题 │
├─────────────────────────────────────────────────────────────┤
│ │
│ 问题： │
│ API 变更如何保持向后兼容？ │
│ │
│ 解决方案： │
│ - URL 版本：/v1/users, /v2/users │
│ - Header 版本：Accept: application/vnd.api.v1+json │
│ - 查询参数：/users?version=1 │
│ │
└─────────────────────────────────────────────────────────────┘
3. 实时数据 #
text
┌─────────────────────────────────────────────────────────────┐
│ 实时数据问题 │
├─────────────────────────────────────────────────────────────┤
│ │
│ 问题： │
│ REST 基于请求-响应模式，不支持服务端主动推送 │
│ │
│ 解决方案： │
│ - WebSocket：双向实时通信 │
│ - Server-Sent Events：服务端推送 │
│ - 轮询：定时请求（效率低） │
│ │
└─────────────────────────────────────────────────────────────┘
RESTful API 的应用场景 #
1. Web 应用 #
text
┌─────────────────────────────────────────────────────────────┐
│ Web 应用 │
├─────────────────────────────────────────────────────────────┤
│ │
│ 前后端分离架构： │
│ │
│ ┌─────────┐ REST API ┌─────────┐ │
│ │ 前端 │◄───────────────►│ 后端 │ │
│ │ React │ │ Node.js │ │
│ │ Vue │ │ Python │ │
│ │ Angular │ │ Java │ │
│ └─────────┘ └─────────┘ │
│ │
│ 优势： │
│ - 前后端独立开发 │
│ - 多端复用同一 API │
│ - 便于团队协作 │
│ │
└─────────────────────────────────────────────────────────────┘
2. 移动应用 #
text
┌─────────────────────────────────────────────────────────────┐
│ 移动应用 │
├─────────────────────────────────────────────────────────────┤
│ │
│ iOS / Android 应用后端： │
│ │
│ ┌─────────┐ │
│ │ iOS App │──┐ │
│ └─────────┘ │ │
│ │ REST API ┌─────────┐ │
│ ┌─────────┐ ├──────────────────►│ 后端 │ │
│ │Android │──┤ │ 服务 │ │
│ │ App │ │ └─────────┘ │
│ └─────────┘ │ │
│ │ │
│ ┌─────────┐ │ │
│ │ 小程序 │──┘ │
│ └─────────┘ │
│ │
│ 优势： │
│ - 一套 API 支持多端 │
│ - 无状态设计适合移动端 │
│ - 易于缓存优化 │
│ │
└─────────────────────────────────────────────────────────────┘
3. 微服务架构 #
text
┌─────────────────────────────────────────────────────────────┐
│ 微服务架构 │
├─────────────────────────────────────────────────────────────┤
│ │
│ 服务间通信： │
│ │
│ ┌─────────┐ REST API ┌─────────┐ │
│ │ 用户服务 │◄───────────────►│ 订单服务 │ │
│ └─────────┘ └─────────┘ │
│ ▲ ▲ │
│ │ REST API │ │
│ │ │ │
│ ┌────┴────┐ ┌────┴────┐ │
│ │ 商品服务 │◄─────────────────│ 支付服务 │ │
│ └─────────┘ └─────────┘ │
│ │
│ 优势： │
│ - 服务解耦 │
│ - 技术栈独立 │
│ - 独立部署和扩展 │
│ │
└─────────────────────────────────────────────────────────────┘
4. 第三方集成 #
text
┌─────────────────────────────────────────────────────────────┐
│ 第三方集成 │
├─────────────────────────────────────────────────────────────┤
│ │
│ 开放 API 平台： │
│ │
│ - 微信开放平台 API │
│ - 支付宝开放平台 API │
│ - GitHub API │
│ - Twitter API │
│ - Stripe API │
│ │
│ 优势： │
│ - 标准化接口易于集成 │
│ - 无状态设计易于授权 │
│ - 文档化便于开发者使用 │
│ │
└─────────────────────────────────────────────────────────────┘
学习路径 #
text
入门阶段
├── REST API 简介（本文）
├── RESTful 设计原则
└── 资源设计
进阶阶段
├── 端点设计
├── HTTP 方法使用
├── 状态码使用
└── API 版本管理
高级阶段
├── API 安全
├── 分页与过滤
├── 错误处理
└── 最佳实践
扩展阶段
├── 高级主题
├── GraphQL vs REST
└── 实战案例
下一步 #
现在你已经了解了 REST API 的基本概念，接下来学习 RESTful 设计原则，深入了解如何设计优秀的 RESTful API！
最后更新：2026-03-29