REST API #

什么是 REST API？ #

REST（Representational State Transfer，表述性状态转移）是一种软件架构风格，由 Roy Fielding 在 2000 年提出。RESTful API 是遵循 REST 架构原则设计的 Web API，它使用标准的 HTTP 方法操作资源，实现简洁、统一、可扩展的接口设计。

核心特点 #

特性 说明
资源导向 以资源为核心，URL 表示资源
统一接口 使用标准 HTTP 方法
无状态 每个请求包含所有必要信息
可缓存 响应可被缓存提高性能
分层系统 支持中间层和负载均衡

文档结构 #

本指南按以下结构组织，循序渐进地帮助你掌握 REST API 设计：

1. 入门基础 #

主题 描述 文档链接
REST API 简介 REST 的定义、历史、六大约束 intro.md
RESTful 设计原则 资源导向设计、统一接口原则 principles.md
资源设计 资源命名、层级关系、URI 设计 resources.md

2. 核心概念 #

主题 描述 文档链接
端点设计 URL 设计规范、最佳实践 endpoints.md
HTTP 方法 GET、POST、PUT、PATCH、DELETE 使用 methods.md
状态码 HTTP 状态码的正确使用 status-codes.md

3. 进阶功能 #

主题 描述 文档链接
版本管理 API 版本控制策略 versioning.md
分页与过滤 数据分页、排序、过滤 pagination.md
错误处理 错误响应设计、错误码规范 error-handling.md

4. 安全与最佳实践 #

主题 描述 文档链接
API 安全 认证授权、HTTPS、安全最佳实践 security.md
最佳实践 API 设计最佳实践总结 best-practices.md

5. 高级主题 #

主题 描述 文档链接
高级主题 HATEOAS、速率限制、缓存策略 advanced.md

学习路径 #

入门阶段（REST 新手） #

  1. 了解 REST 的基本概念和六大约束
  2. 理解资源导向设计思想
  3. 掌握 URI 设计规范
  4. 学习 HTTP 方法的正确使用

进阶阶段（REST 熟练） #

  1. 掌握状态码的正确使用
  2. 学会 API 版本管理
  3. 实现分页和过滤功能
  4. 设计友好的错误响应

高级阶段（REST 专家） #

  1. 实现 API 安全机制
  2. 应用 HATEOAS 原则
  3. 优化 API 性能
  4. 设计大规模 API 架构

RESTful vs 传统 API #

特性 RESTful API 传统 RPC API
URL 设计 名词（资源） 动词（操作）
操作表达 HTTP 方法 URL 中体现
状态管理 无状态 有状态
可缓存性 良好 较差
可扩展性 优秀 一般
学习成本 统一标准 各不相同

快速开始 #

RESTful API 示例 #

text 
GET    /users           # 获取用户列表
GET    /users/123       # 获取指定用户
POST   /users           # 创建用户
PUT    /users/123       # 更新用户（完整）
PATCH  /users/123       # 更新用户（部分）
DELETE /users/123       # 删除用户

请求响应示例 #

http 
GET /users/123 HTTP/1.1
Host: api.example.com
Accept: application/json

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": 123,
  "name": "张三",
  "email": "zhangsan@example.com",
  "createdAt": "2025-01-15T10:30:00Z"
}

应用场景 #

场景 描述
Web 应用 前后端分离架构
移动应用 iOS/Android 后端服务
微服务 服务间通信
第三方集成 开放 API 平台

资源推荐 #

更新日志 #

  • 2026-03-29：创建初始版本，包含完整的 REST API 学习大纲

继续探索本指南，逐步掌握 REST API 设计技术，从新手成长为 API 设计专家！

最后更新：2026-03-29