250 lines
7.5 KiB
Markdown
250 lines
7.5 KiB
Markdown
# 第5-5课：RESTful API设计
|
||
|
||
## 一、本课目标
|
||
|
||
完成本课后，你能够：
|
||
|
||
1. 理解资源、资源标识和资源表现形式；
|
||
2. 解释表述性状态转移（Representational State Transfer，REST）的基本思想；
|
||
3. 使用路径、HTTP方法和状态码共同描述一个接口；
|
||
4. 区分列表接口、详情接口和业务动作接口；
|
||
5. 为图书管理系统设计一组结构一致的RESTful API。
|
||
|
||
## 二、前置知识
|
||
|
||
- 已学过URL和HTTP请求方法；
|
||
- 已学过HTTP响应和常用状态码；
|
||
- 已学过JSON请求体和响应体；
|
||
- 不要求接触过FastAPI、Django或任何接口框架。
|
||
|
||
## 三、先理解“资源”
|
||
|
||
资源（Resource）是系统希望通过接口管理的业务对象，例如图书、作者、用户和订单。它不是只指数据库中的一行，也不是只指一个Python对象，而是从接口使用者角度看到的业务事物。
|
||
|
||
一本编号为10的图书可以用路径表示：
|
||
|
||
```text
|
||
/books/10
|
||
```
|
||
|
||
这里：
|
||
|
||
- `books`表示图书资源集合；
|
||
- `10`用于标识集合中的一本图书；
|
||
- 返回的JSON是这本图书在当前时刻的一种表现形式。
|
||
|
||
同一个资源可以有JSON、HTML等不同表现形式，但后端API通常返回JSON。
|
||
|
||
## 四、REST与RESTful是什么
|
||
|
||
REST是一种Web接口架构风格，不是协议、框架或Python库。RESTful表示一个接口的设计遵循REST的资源化思想。
|
||
|
||
入门阶段先掌握三条核心规则：
|
||
|
||
1. 路径主要描述资源，优先使用名词；
|
||
2. HTTP方法描述想对资源做什么；
|
||
3. HTTP状态码描述处理结果。
|
||
|
||
因此创建图书通常写成：
|
||
|
||
```text
|
||
POST /books → 201 Created
|
||
```
|
||
|
||
而不是：
|
||
|
||
```text
|
||
POST /createBook → 200 OK
|
||
```
|
||
|
||
后一种不一定不能运行，但它没有充分利用HTTP已有的语义。
|
||
|
||
## 五、从一个接口开始设计
|
||
|
||
设计接口时按以下顺序思考：
|
||
|
||
1. 管理的业务资源是什么？这里是图书；
|
||
2. 是操作集合还是单个资源？`/books`是集合，`/books/10`是单个资源；
|
||
3. 操作意图是什么？查询、创建、修改还是删除；
|
||
4. 输入放在哪里？路径参数、查询参数或JSON请求体；
|
||
5. 成功返回什么状态码和数据？
|
||
6. 可能失败的情况有哪些？
|
||
|
||
## 六、图书资源接口
|
||
|
||
| 方法 | 路径 | 输入位置 | 成功状态 | 作用 |
|
||
|---|---|---|---:|---|
|
||
| GET | `/books` | 查询参数 | 200 | 查询图书列表 |
|
||
| GET | `/books/{book_id}` | 路径参数 | 200 | 查询一本图书 |
|
||
| POST | `/books` | JSON请求体 | 201 | 创建图书 |
|
||
| PUT | `/books/{book_id}` | JSON请求体 | 200或204 | 整体替换图书 |
|
||
| PATCH | `/books/{book_id}` | JSON请求体 | 200或204 | 修改部分字段 |
|
||
| DELETE | `/books/{book_id}` | 路径参数 | 204 | 删除图书 |
|
||
|
||
表中的`{book_id}`是路径参数占位符。真实请求会写成`/books/10`，花括号不会原样发送。
|
||
|
||
## 七、列表、详情与分页
|
||
|
||
列表接口操作资源集合：
|
||
|
||
```text
|
||
GET /books?keyword=Python&page=1&page_size=20
|
||
```
|
||
|
||
- `keyword`负责筛选；
|
||
- `page`表示第几页；
|
||
- `page_size`表示每页多少条。
|
||
|
||
一种清晰的列表响应是：
|
||
|
||
```json
|
||
{
|
||
"items": [
|
||
{"id": 10, "title": "Python入门"}
|
||
],
|
||
"page": 1,
|
||
"page_size": 20,
|
||
"total": 1
|
||
}
|
||
```
|
||
|
||
详情接口操作单个资源：
|
||
|
||
```text
|
||
GET /books/10
|
||
```
|
||
|
||
存在时返回200和图书JSON；不存在时返回404，而不是返回200和空字符串。
|
||
|
||
## 八、新增接口的完整设计
|
||
|
||
请求：
|
||
|
||
```http
|
||
POST /books HTTP/1.1
|
||
Content-Type: application/json
|
||
|
||
{"title": "Web基础", "price": 59.00}
|
||
```
|
||
|
||
成功响应：
|
||
|
||
```http
|
||
HTTP/1.1 201 Created
|
||
Location: /books/10
|
||
Content-Type: application/json
|
||
|
||
{"id": 10, "title": "Web基础", "price": 59.00}
|
||
```
|
||
|
||
`Location`响应头告诉客户端新资源的地址。常见失败包括JSON格式错误、字段不合规则和图书编号冲突。
|
||
|
||
## 九、PUT与PATCH的区别
|
||
|
||
- PUT通常表示用请求内容整体替换资源的可修改状态；
|
||
- PATCH通常表示只修改请求中出现的字段。
|
||
|
||
例如只修改价格时，PATCH请求体可以是：
|
||
|
||
```json
|
||
{"price": 69.00}
|
||
```
|
||
|
||
项目必须明确PUT缺少字段时如何处理。不要仅凭方法名称猜测，接口文档需要写清楚。
|
||
|
||
## 十、业务动作如何设计
|
||
|
||
不是所有业务都能自然表示为基础增删改查。例如“取消订单”是一个带业务规则的动作。
|
||
|
||
可以把取消记录理解成订单下的子资源：
|
||
|
||
```text
|
||
POST /orders/10/cancellations
|
||
```
|
||
|
||
也有项目使用：
|
||
|
||
```text
|
||
POST /orders/10/cancel
|
||
```
|
||
|
||
RESTful不是机械规则。选择能够清楚表达业务、便于权限与审计、并且全项目一致的方案更重要。
|
||
|
||
## 十一、错误响应也需要设计
|
||
|
||
同一个详情接口可能产生不同结果：
|
||
|
||
| 情况 | 状态码 | 响应含义 |
|
||
|---|---:|---|
|
||
| 查询成功 | 200 | 返回资源 |
|
||
| 编号格式错误 | 400或422 | 客户端输入不符合要求 |
|
||
| 图书不存在 | 404 | 找不到指定资源 |
|
||
| 未登录 | 401 | 需要完成身份认证 |
|
||
| 没有权限 | 403 | 身份已知但禁止访问 |
|
||
| 后端未知异常 | 500 | 服务器未能完成处理 |
|
||
|
||
错误响应应保持固定结构，例如包含错误代码和面向调用者的消息，但不能泄露数据库密码或程序堆栈。
|
||
|
||
## 十二、完整示例
|
||
|
||
`rest_api_design_example.py`不建立网络连接，而是把一组接口设计保存为Python列表并输出。这样可以把注意力放在方法、路径和状态码的组合上。
|
||
|
||
## 十三、运行方法
|
||
|
||
```powershell
|
||
cd D:\Code\Python\05_web基础\5_5_RESTful_API设计
|
||
python rest_api_design_example.py
|
||
```
|
||
|
||
预期输出包含五条图书接口和一个带筛选、分页参数的列表请求示例。
|
||
|
||
## 十四、代码执行顺序
|
||
|
||
1. `main()`调用`build_book_api_design()`；
|
||
2. 函数返回由多个字典组成的列表；
|
||
3. `print_api_design()`逐条读取接口；
|
||
4. 每条接口按统一列顺序输出；
|
||
5. 最后输出列表筛选示例。
|
||
|
||
示例中的数据结构只是“接口设计表”，不是服务器，也不会真的新增或删除图书。
|
||
|
||
## 十五、常见错误
|
||
|
||
### 15.1 路径全部使用动词
|
||
|
||
`/getBooks`、`/createBook`和`/deleteBook`会把HTTP方法已有的意图重复写入路径，并使接口越来越不一致。
|
||
|
||
### 15.2 用GET修改数据
|
||
|
||
浏览器、缓存或爬虫可能自动访问GET链接。GET应当用于读取，不能因为输入方便就用它删除数据。
|
||
|
||
### 15.3 列表接口一次返回全部数据
|
||
|
||
数据增长后会拖慢数据库、服务器和客户端。列表接口应尽早明确分页规则和最大每页数量。
|
||
|
||
### 15.4 只设计成功响应
|
||
|
||
客户端真正需要处理的往往是校验失败、资源不存在、状态冲突和权限不足。接口设计必须包含失败边界。
|
||
|
||
### 15.5 认为RESTful只有唯一答案
|
||
|
||
REST提供设计思想，复杂业务动作可能有多种合理表达。项目内一致、语义清楚和文档完整比形式上的绝对统一更重要。
|
||
|
||
## 十六、课堂练习
|
||
|
||
打开`practice.py`，完成作者资源、订单业务动作和反例改造练习。练习文件不含参考答案。
|
||
|
||
## 十七、本课小结
|
||
|
||
RESTful API围绕资源组织路径，用HTTP方法表达操作，用状态码表达结果。设计一个接口时，不仅要考虑成功路径，还要明确输入位置、错误状态和响应结构。
|
||
|
||
## 十八、验收标准
|
||
|
||
- 能解释资源、集合路径和详情路径；
|
||
- 能组合路径、方法和状态码；
|
||
- 能区分查询参数、路径参数和JSON请求体；
|
||
- 能解释PUT与PATCH的基本差异；
|
||
- 能设计包含失败结果的图书接口；
|
||
- 示例可独立运行；
|
||
- 完成`practice.py`中的练习。
|