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 偶尔用到

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

资源识别（Resource Identification）
每个资源都有唯一的标识符，通常是 URL。
通过资源的表示来操作资源（Manipulation of Resources Through Representations）
客户端通过资源的某种表示（JSON、XML 等）来操作资源，而不是直接操作资源本身。
自描述消息（Self-descriptive Messages）
每个请求/响应都包含足够的信息（HTTP 方法、Content-Type、状态码等），让接收方能理解。
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”）