RESTful 请求是指符合 REST 架构风格规范的 HTTP 请求。REST 的核心思想是将网络上的所有事物（数据、服务）抽象为资源，并通过标准的 HTTP 方法对资源进行操作。

1. REST = “资源 + 标准动作”
   o 万物皆资源 → URL 用名词复数，层级 ≤3：/articles/123
   o 动作用 HTTP 动词：GET 读、POST 建、PUT 整改、PATCH 局改、DELETE 删
2. 请求 4 大件
   o 方法：GET /articles
   o URL：指向资源，不含动词
   o Header：Content-Type、Authorization、Idempotency-Key …
   o Body：POST/PUT/PATCH 时放 JSON
3. 幂等性
   GET/PUT/DELETE 幂等（可重试）；POST/PATCH 默认不幂等
4. 状态码速查
   2xx 成功 201 已创建 204 无内容
   4xx 客户端错 400 参数错 401/403 认证/授权 404 找不到
   5xx 服务器错 500 内部错
5. 博客文章接口示例
   GET /articles 列表
   GET /articles/123 单篇
   POST /articles 创建 {title, content}
   PUT /articles/123 整篇替换
   PATCH /articles/123 局部更新 {title}
   DELETE /articles/123 删除
6. 代码片段（以 POST 创建为例）
   curl -X POST https://api.example.com/articles
   -H "Content-Type: application/json"
   -H "Authorization: Bearer TOKEN"
   -d '{"title":"Hi","content":"..."}'
7. 最佳实践一句话
   名词复数、HTTPS、Token 无状态、分页过滤用 Query、版本加 /v1/、Swagger 文档、统一错误体。

一个 RESTful 请求通常包含以下几个关键部分：

1. HTTP 方法：定义操作类型（GET, POST, PUT, DELETE 等）。
2. URL：唯一标识要操作的资源。
3. HTTP 头部：包含元数据，如内容类型（Content-Type）、认证信息（Authorization）等。
4. 请求体：通常用于 POST 和 PUT 请求，携带要发送给服务器的数据。

1. RESTful API 设计原则

| 原则 | 描述 | 示例 |
| ：--- | :--- | :--- |
| 资源导向 | 使用名词（复数形式）来标识资源，而不是动词。API 端点应该指向资源。 | /users, /articles/123 |
| HTTP 方法 | 使用标准的 HTTP 方法来表达对资源的操作（CRUD）。 | GET（读）， POST（创建）， PUT（更新）， DELETE（删除） |
| 无状态 | 每个请求都必须包含处理该请求所需的所有信息。服务器不应存储用户会话状态。 | 使用 Token（如 JWT）而不是 Session 来认证每个请求。 |
| 统一接口 | 接口设计应标准、统一，使得系统各部分能独立演进。 | 使用 HTTP 状态码表示结果，使用 JSON 作为数据格式。 |
| 可缓存 | 服务器响应应明确标识是否可缓存，以提高性能。 | 使用 HTTP 头 Cache-Control, ETag。 |

2. 核心 HTTP 方法（动词）与 CRUD 对应关系

| HTTP 方法 | CRUD 操作 | 描述 | 是否幂等 | 是否有请求体 |
| ：--- | :--- | :--- | :--- | :--- |
| GET | Read | 获取资源（一个或多个）。 | 是 | 否 |
| POST | Create | 创建新资源。 | 否 | 是 |
| PUT | Update | 更新目标资源（全部字段）。 | 是 | 是 |
| PATCH | Update | 部分更新目标资源（一个或多个字段）。 | 否 | 是 |
| DELETE | Delete | 删除指定资源。 | 是 | 否 |

幂等性：一个方法的多次相同请求与一次请求具有相同的效果。这在网络不稳定时非常重要（例如，客户端可以安全地重试幂等请求）。

3. HTTP 状态码（Status Codes）

服务器通过状态码告知客户端请求的结果。

| 范围 | 类别 | 常用状态码 | 含义 |
| ：--- | :--- | :--- | :--- |
| 2xx | 成功 | 200 OK | 请求成功。 |
| | | 201 Created | 创建成功（常用于 POST）。 |
| | | 204 No Content | 操作成功，但无内容返回（常用于 DELETE）。 |
| 4xx | 客户端错误 | 400 Bad Request | 请求格式错误（如参数错误）。 |
| | | 401 Unauthorized | 未认证（身份验证失败）。 |
| | | 403 Forbidden | 无权限（认证成功但无权访问）。 |
| | | 404 Not Found | 资源不存在。 |
| 5xx | 服务器错误 | 500 Internal Server Error | 服务器内部错误。 |

4. 示例：一个博客文章的 API

假设我们有一个管理博客文章的 API，基础 URL 是 https://api.example.com。

| 操作 | HTTP 方法 | 端点 URL | 描述 | 请求体示例（JSON） |
| ：--- | :--- | :--- | :--- | :--- |
| 获取所有文章 | GET | /articles | 获取文章列表 | 无 |
| 获取单篇文章 | GET | /articles/123 | 获取 ID 为 123 的文章 | 无 |
| 创建新文章 | POST | /articles | 创建一篇文章 | {"title": "New Post", "content": "..."} |
| 全文更新文章 | PUT | /articles/123 | 更新 ID 为 123 的文章（所有字段） | {"title": "Updated", "content": "new..."} |
| 部分更新文章 | PATCH | /articles/123 | 只更新文章的标题 | {"title": "New Title"} |
| 删除文章 | DELETE | /articles/123 | 删除 ID 为 123 的文章 | 无 |

5. 如何使用代码发送 RESTful 请求

以下是使用不同工具发送 GET 和 POST 请求的示例。

示例 1：获取所有文章（GET）

cURL

curl -X GET https://api.example.com/articles \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

JavaScript (Fetch API)

fetch('https://api.example.com/articles', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
    'Content-Type': 'application/json'
  }
})
.then(response => response.json())
.then(data => console.log(data));

示例 2：创建一篇文章（POST）

cURL

curl -X POST https://api.example.com/articles \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{"title": "My New Post", "content": "This is the body."}'

JavaScript (Fetch API)

fetch('https://api.example.com/articles', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_ACCESS_TOKEN'
  },
  body: JSON.stringify({
    title: 'My New Post',
    content: 'This is the body.'
  })
})
.then(response => response.json())
.then(data => console.log(data));

6. 最佳实践与常见误区

1. 使用名词，而非动词：
2. 好：GET /users
3. 不好：GET /getUsers
4. 使用复数资源名：保持一致性，通常使用复数名词（/users, /products）。
5. 使用嵌套资源表示关系：
6. 获取用户的所有订单：GET /users/123/orders
7. 善用查询参数进行过滤、分页和排序：
8. 过滤：GET /articles?state=published
9. 分页：GET /articles?page=2&limit=20
10. 排序：GET /articles?sort=-created_at （- 表示降序）
11. 版本化你的 API：将版本号加入 URL 或 Header 中，避免破坏性更新影响现有用户。
12. URL 中：https://api.example.com/v1/articles
13. Header 中：Accept: application/vnd.example.v1+json
14. 始终使用 HTTPS：保证数据传输的安全性。
15. 提供清晰的文档：使用工具如 Swagger/OpenAPI 来生成交互式 API 文档。