RESTful API 教程

好的！下面是一份面向初学者到中级的 RESTful API 教程，内容尽量清晰、结构化，并带有实际例子。我们会从概念讲起，一步步到设计原则、常见实践和实现建议。

---

1. 什么是 RESTful API？

REST（Representational State Transfer）是一种架构风格，不是标准也不是协议。它由 Roy Fielding 在 2000 年的博士论文中提出，主要用于设计网络应用程序（尤其是 Web API）。

RESTful API 的核心思想：
把服务器上的资源（Resource）看作是 Web 的核心，通过统一的接口（通常是 HTTP）来对这些资源进行增删改查。

---

2. REST 的六大约束（必须理解）

约束	说明	实际意义
客户端-服务器	客户端和服务器分离，互不干扰	前后端分离
无状态（Stateless）	每个请求都必须包含所有必要信息，服务器不保存客户端状态	易于水平扩展
可缓存	响应可以被缓存（通过 Cache-Control、ETag 等头）	提升性能
分层系统	客户端不需要知道它连接的是真实服务器还是代理、负载均衡器等	便于架构扩展
统一接口（最重要！）	所有资源都通过相同的接口操作（见下文 4 个子约束）	降低学习成本
按需代码（可选）	服务器可以发送可执行代码给客户端（例如 JavaScript），实际很少用	移动端 H5 偶尔用到

统一接口的四个子约束（最常被问到）：

1. 资源识别（Resource Identification）
   每个资源都有唯一的标识符，通常是 URL。
2. 通过资源的表示来操作资源（Manipulation of Resources Through Representations）
   客户端通过资源的某种表示（JSON、XML 等）来操作资源，而不是直接操作资源本身。
3. 自描述消息（Self-descriptive Messages）
   每个请求/响应都包含足够的信息（HTTP 方法、Content-Type、状态码等），让接收方能理解。
4. HATEOAS（超媒体作为应用状态引擎，Hypermedia as the Engine of Application State）
   响应中应该包含相关资源的链接，客户端通过链接“发现”下一步操作。
   （实际项目中很少严格实现，但了解概念很有用）

---

3. RESTful API 的核心设计原则（常用“最佳实践”）

原则	推荐做法	例子
使用名词（资源）而非动词	URL 用名词表示资源，动词用 HTTP 方法表示	/users 而不是 /getUsers
使用 HTTP 方法表达动作	GET / POST / PUT / PATCH / DELETE	POST /users 创建用户
复数形式资源名	通常用复数（约定俗成）	/articles 而不是 /article
层级结构清晰	用路径表达从属关系	/users/123/orders
使用 HTTP 状态码	2xx 成功、4xx 客户端错误、5xx 服务器错误	201 Created、404 Not Found、400 Bad Request
版本控制	在 URL 中或 Header 中指定版本	/v1/users 或 Accept: application/vnd.myapi.v2+json
字段命名规范	推荐 snake_case 或 camelCase，一致即可	user_id 或 userId
返回一致的结构	成功和失败都返回类似结构（data + meta 或 errors）	{ "data": {...}, "meta": {...} }

---

4. HTTP 方法与 CRUD 对应表（最常用）

操作	HTTP 方法	URL 示例	说明	幂等性	安全
创建（Create）	POST	POST /users	创建新资源	否	否
读取（Read）	GET	GET /users	获取资源列表	是	是
读取（Read）	GET	GET /users/123	获取单个资源	是	是
更新（全量）	PUT	PUT /users/123	替换整个资源（缺失字段清空）	是	否
更新（部分）	PATCH	PATCH /users/123	部分更新（只改动提供的字段）	否*	否
删除	DELETE	DELETE /users/123	删除资源	是	否

*注：PATCH 是否幂等取决于具体实现方式（如果每次只应用一次差量则幂等）。

---

5. 常见状态码速查表

状态码	含义	典型场景
200	OK	GET 成功返回数据
201	Created	POST 创建成功
204	No Content	DELETE 成功，无返回体
400	Bad Request	参数错误、格式不对
401	Unauthorized	未登录或 Token 无效
403	Forbidden	已登录但无权限
404	Not Found	资源不存在
409	Conflict	资源冲突（例如重复创建）
422	Unprocessable Entity	语义错误（校验失败）
429	Too Many Requests	超过限流配额
500	Internal Server Error	服务器内部错误

---

6. 实际例子：博客系统 RESTful API 设计

资源：文章（articles）、用户（users）、评论（comments）

操作	HTTP 请求	说明
获取所有文章	GET /articles	可加查询参数 ?page=1&limit=20
获取单篇文章	GET /articles/123
创建文章	POST /articles	Body: { title, content, authorId }
修改文章（全量）	PUT /articles/123	必须提供所有字段
修改文章标题	PATCH /articles/123	Body: { title: “新标题” }
删除文章	DELETE /articles/123
获取某篇文章的评论	GET /articles/123/comments
给文章添加评论	POST /articles/123/comments	Body: { content, authorId }
获取某个用户的所有文章	GET /users/456/articles

---

7. 推荐的响应结构（JSON）

成功响应示例：

{
  "data": {
    "id": 123,
    "title": "RESTful API 设计指南",
    "content": "...",
    "created_at": "2025-12-25T10:00:00Z"
  },
  "meta": {
    "request_id": "abc123",
    "timestamp": "2025-12-25T10:00:01Z"
  }
}

失败响应示例：

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "标题长度不能超过 100 个字符",
    "details": [
      {
        "field": "title",
        "issue": "too_long"
      }
    ]
  }
}

---

8. 常见问题与进阶话题

问题	推荐做法 / 讨论点
如何处理分页？	使用 ?page=2&limit=20 或 ?offset=40&limit=20，返回 total、next 等 meta
如何做认证授权？	常用：JWT（Bearer Token）、OAuth 2.0、API Key
如何做版本控制？	URL 版本 /v1/、Header 版本、Git 风格（Accept header）
PUT vs PATCH 区别？	PUT 是全量替换，PATCH 是部分更新
如何处理批量操作？	POST /articles/bulk-create 或 PATCH /articles + 数组
什么是 HATEOAS？	响应中返回 _links 字段，指向相关资源
限流（Rate Limiting）怎么做？	Header: X-RateLimit-Limit, X-RateLimit-Remaining, Retry-After
错误码要用英文还是数字？	推荐英文常量 + HTTP 状态码（400 + “VALIDATION_ERROR”）

---

9. 快速上手实践建议

1. 用 Node.js + Express 或 Spring Boot（Java）或 FastAPI（Python）写一个小型项目
2. 实现一套简单的 TODO 列表 API
3. 加上分页、认证（JWT）、基本的输入校验
4. 用 Postman 或 curl 测试
5. 再用 Swagger/OpenAPI 生成接口文档（强烈推荐）

---

10. 总结：RESTful API 设计核心口诀

“名词做资源，动词用方法，状态码说话，结构要一致”

• URL 用名词（复数）
• 动作用 HTTP 方法
• 结果用 HTTP 状态码
• 数据结构前后一致
• 出错要清晰友好

如果你想深入某个部分（例如：如何设计分页、认证、错误处理、OpenAPI 文档生成、HATEOAS 实践等），可以告诉我，我可以继续展开讲解或给出代码示例！