308 lines
11 KiB
Markdown
308 lines
11 KiB
Markdown
# 第5-6课：HTTP接口调试与综合实践
|
||
|
||
## 一、本课定位
|
||
|
||
本课把客户端、服务器、URL、HTTP、状态码、JSON和RESTful API组合成一个可运行的本地闭环。示例使用Python标准库搭建临时图书接口，只服务于协议观察，不替代下一阶段的FastAPI。
|
||
|
||
## 二、本课目标
|
||
|
||
完成本课后，你能够：
|
||
|
||
1. 启动一个只监听本机的临时HTTP服务；
|
||
2. 使用客户端代码发送GET和POST请求；
|
||
3. 同时检查状态码、响应头和JSON响应体；
|
||
4. 识别JSON格式错误、字段错误和资源不存在；
|
||
5. 设计图书管理系统的RESTful API；
|
||
6. 说明HTTP知识如何迁移到FastAPI。
|
||
|
||
## 三、前置知识
|
||
|
||
- 客户端、服务器和请求响应流程；
|
||
- URL、HTTP方法、请求头和请求体；
|
||
- 常见状态码；
|
||
- JSON转换与RESTful API设计；
|
||
- Python类、异常、线程和上下文管理器的基本阅读能力。
|
||
|
||
线程（Thread）表示同一程序中的一条执行路线。本课只用后台线程让服务器等待请求，主线程同时充当客户端；不展开并发编程细节。
|
||
|
||
本课示例使用了前面阶段学过的类、异常和上下文管理器，但只要求按调用流程阅读，不重新讲解这些Python语法。
|
||
|
||
## 四、为什么现在才启动真实HTTP服务
|
||
|
||
前五课分别拆开观察了通信角色、URL、请求、响应、JSON和接口设计。如果一开始就使用框架，路由、自动校验和自动序列化会让新手看到结果，却不容易分清是谁完成了哪一步。
|
||
|
||
本课使用标准库建立一个最小闭环：
|
||
|
||
1. 程序在本机启动HTTP服务器；
|
||
2. 客户端向它发送真实HTTP请求；
|
||
3. 服务器读取路径、请求头和请求体；
|
||
4. 服务器修改内存数据；
|
||
5. 服务器返回状态码、响应头和JSON；
|
||
6. 客户端读取并输出响应；
|
||
7. 全部测试结束后关闭服务器。
|
||
|
||
它是教学服务器，不是下一阶段要长期使用的项目框架。
|
||
|
||
## 五、先认识本课的新名词
|
||
|
||
| 名词 | 本课中的含义 |
|
||
|---|---|
|
||
| `localhost` | 表示自己的计算机，常对应`127.0.0.1` |
|
||
| 监听（Listen） | 服务器等待某个地址和端口上的请求 |
|
||
| 随机端口 | 传入端口0，由操作系统选择当前可用端口 |
|
||
| 处理器（Handler） | 收到请求后负责读取并生成响应的代码 |
|
||
| 后台线程 | 在同一程序中持续运行服务器，让主流程可以发送请求 |
|
||
| 内存数据 | 只存在于当前程序运行期间，结束后不会保存 |
|
||
| 超时（Timeout） | 等待超过限定时间后停止继续等待 |
|
||
|
||
`127.0.0.1`只指向本机。绑定该地址可以避免本课没有认证的服务被局域网其他设备访问。
|
||
|
||
## 六、完整调用链
|
||
|
||
```text
|
||
send_request()
|
||
↓ HTTP请求
|
||
BookApiHandler
|
||
↓ 路径匹配、JSON解析、字段校验
|
||
内存图书列表
|
||
↓ JSON响应
|
||
send_request()读取状态码、响应头和响应体
|
||
```
|
||
|
||
示例绑定`127.0.0.1`，只接受本机连接；端口传入`0`，由操作系统选择当前可用端口，避免与现有服务冲突。数据只保存在内存中，程序结束即消失。
|
||
|
||
同一个Python程序同时扮演两种角色：
|
||
|
||
- `ThreadingHTTPServer`和`BookApiHandler`是服务器；
|
||
- `send_request()`是客户端；
|
||
- 它们通过本机网络连接交换HTTP消息，不是普通函数直接传参。
|
||
|
||
## 七、服务器如何启动
|
||
|
||
```python
|
||
server = ThreadingHTTPServer(("127.0.0.1", 0), BookApiHandler)
|
||
```
|
||
|
||
这行代码只创建服务器对象，还没有开始持续等待请求。地址元组中：
|
||
|
||
- `127.0.0.1`限制为本机；
|
||
- `0`请求操作系统分配端口；
|
||
- `BookApiHandler`指定收到请求后由哪个类处理。
|
||
|
||
随后创建后台线程并执行`serve_forever()`。名称表示服务器会持续等待，直到程序调用`shutdown()`。
|
||
|
||
## 八、服务端重点
|
||
|
||
`BaseHTTPRequestHandler`按请求方法调用`do_GET()`或`do_POST()`。`send_json()`负责：
|
||
|
||
1. 将Python对象序列化为JSON；
|
||
2. 编码成UTF-8字节；
|
||
3. 写入状态码和响应头；
|
||
4. 按字节数计算`Content-Length`；
|
||
5. 写出响应体。
|
||
|
||
中文字符的字符数量与UTF-8字节数量不同，因此必须对编码后的`response_body`调用`len()`。
|
||
|
||
### 8.1 GET请求
|
||
|
||
客户端请求`GET /books`时，标准库调用`do_GET()`：
|
||
|
||
1. 检查`self.path`是否等于`/books`；
|
||
2. 路径匹配时返回200和图书列表；
|
||
3. 路径不匹配时返回404和错误JSON。
|
||
|
||
### 8.2 POST请求
|
||
|
||
客户端请求`POST /books`时，标准库调用`do_POST()`：
|
||
|
||
1. 检查路径；
|
||
2. 从`Content-Length`得知需要读取多少字节；
|
||
3. 读取请求体并按UTF-8解码；
|
||
4. 使用`json.loads()`解析JSON；
|
||
5. 校验`title`是否为非空字符串；
|
||
6. 创建新图书并加入内存列表；
|
||
7. 返回201、新图书JSON和`Location`响应头。
|
||
|
||
JSON语法错误返回400，字段不符合要求返回422，未知路径返回404。三个结果代表不同问题。
|
||
|
||
## 九、客户端重点
|
||
|
||
`urllib.request.Request`创建请求，`urlopen()`发送请求。遇到4xx或5xx时，标准库会抛出`HTTPError`，但错误对象仍包含状态码和响应体，需要读取后再判断原因。
|
||
|
||
接口调试不能只看响应体。至少检查：
|
||
|
||
- 请求方法与完整URL；
|
||
- 请求头和请求体；
|
||
- HTTP状态码；
|
||
- 响应`Content-Type`；
|
||
- JSON响应结构；
|
||
- 服务端数据是否按预期变化。
|
||
|
||
客户端发送JSON前，需要完成与服务器相反的转换：
|
||
|
||
```text
|
||
Python字典 → JSON字符串 → UTF-8字节 → HTTP请求体
|
||
```
|
||
|
||
客户端收到响应后再反向处理：
|
||
|
||
```text
|
||
HTTP响应体字节 → UTF-8字符串 → 显示或解析JSON
|
||
```
|
||
|
||
示例为保持输出直观，只显示JSON字符串。实际业务客户端通常还会使用`json.loads()`转换成对象。
|
||
|
||
## 十、程序完整执行顺序
|
||
|
||
1. 创建服务器对象；
|
||
2. 创建并启动后台线程；
|
||
3. 从服务器对象取得操作系统分配的端口；
|
||
4. 第一次GET查询初始列表；
|
||
5. POST创建“HTTP接口实践”；
|
||
6. 第二次GET验证列表已经变化；
|
||
7. GET未知路径验证404；
|
||
8. 无论中间是否出错，`finally`都会关闭服务器；
|
||
9. 主线程等待后台线程结束；
|
||
10. 程序输出“本地服务已关闭”。
|
||
|
||
这里先新增再查询，是为了验证POST不只是返回201，还真实改变了当前程序的内存状态。
|
||
|
||
## 十一、运行方法
|
||
|
||
```powershell
|
||
cd D:\Code\Python\05_web基础\5_6_HTTP接口调试与综合实践
|
||
python local_book_api_example.py
|
||
```
|
||
|
||
## 十二、预期结果
|
||
|
||
```text
|
||
本地服务已启动：http://127.0.0.1:随机端口号
|
||
GET http://127.0.0.1:相同端口/books -> 200
|
||
响应体：{"items": [{"id": 1, "title": "Python入门"}]}
|
||
POST http://127.0.0.1:相同端口/books -> 201
|
||
响应体：{"id": 2, "title": "HTTP接口实践"}
|
||
GET http://127.0.0.1:相同端口/books -> 200
|
||
响应体中包含两本图书
|
||
GET http://127.0.0.1:相同端口/missing -> 404
|
||
响应体：{"message": "资源不存在"}
|
||
本地服务已关闭。
|
||
```
|
||
|
||
端口号每次不同是正常现象。第二次查询应包含新创建的“HTTP接口实践”。
|
||
|
||
## 十三、怎样判断测试真正通过
|
||
|
||
不要只检查程序是否结束，应逐项确认：
|
||
|
||
1. 四次请求使用同一个随机端口；
|
||
2. 第一次GET只有初始图书；
|
||
3. POST状态码是201而不是200；
|
||
4. POST响应中生成了编号2；
|
||
5. 第二次GET包含编号1和编号2；
|
||
6. 未知路径返回404；
|
||
7. 最后一行确认服务器已关闭；
|
||
8. 再运行一次时仍从一条初始数据开始。
|
||
|
||
最后一项说明数据只在内存中，没有持久保存，也说明示例可重复运行。
|
||
|
||
## 十四、使用接口调试工具
|
||
|
||
示例服务会自动结束，不适合手工操作。完成`practice.py`时，可以让服务等待键盘输入后再关闭，然后使用Postman、Apifox或IDE内置HTTP客户端发送请求：
|
||
|
||
```http
|
||
GET http://127.0.0.1:端口/books
|
||
```
|
||
|
||
```http
|
||
POST http://127.0.0.1:端口/books
|
||
Content-Type: application/json
|
||
|
||
{"title": "Web实践", "author": "张三"}
|
||
```
|
||
|
||
不要把服务绑定到`0.0.0.0`，本课没有实现认证和生产安全配置。
|
||
|
||
调试工具中的请求配置通常分为：
|
||
|
||
1. 选择HTTP方法；
|
||
2. 输入完整URL；
|
||
3. 配置请求头；
|
||
4. 选择JSON请求体并输入数据；
|
||
5. 发送请求；
|
||
6. 查看状态码、耗时、响应头和响应体。
|
||
|
||
不要只复制响应内容，还要记录发送了什么请求，否则别人无法复现问题。
|
||
|
||
## 十五、图书管理API设计草案
|
||
|
||
| 方法 | 路径 | 成功状态 | 作用 |
|
||
|---|---|---:|---|
|
||
| GET | `/books` | 200 | 分页查询图书 |
|
||
| GET | `/books/{book_id}` | 200 | 查询图书详情 |
|
||
| POST | `/books` | 201 | 新增图书 |
|
||
| PATCH | `/books/{book_id}` | 200 | 修改部分字段 |
|
||
| DELETE | `/books/{book_id}` | 204 | 删除图书 |
|
||
|
||
常见失败包括400格式错误、404图书不存在、409编号冲突和422字段校验失败。实际项目还要处理认证、权限、日志、数据库事务和并发。
|
||
|
||
## 十六、与FastAPI的衔接
|
||
|
||
下一阶段会由FastAPI代替底层标准库代码：
|
||
|
||
- 路由装饰器代替手工判断路径和方法；
|
||
- Pydantic模型代替手工字段校验；
|
||
- 框架自动序列化JSON并生成接口文档；
|
||
- 异常处理器统一生成错误响应。
|
||
|
||
不会改变的是HTTP层的设计：方法、路径、参数、状态码、请求结构和响应结构仍需开发者决定。
|
||
|
||
## 十七、常见错误
|
||
|
||
### 17.1 服务启动后程序不结束
|
||
|
||
服务器会持续等待请求。必须调用`shutdown()`和`server_close()`，并等待后台线程结束。
|
||
|
||
### 17.2 只测试成功情况
|
||
|
||
至少覆盖未知路径、无效JSON和缺少必填字段，否则无法确认错误边界。
|
||
|
||
### 17.3 把标准库示例当作生产服务器
|
||
|
||
本例只用于教学，没有完整认证、限流、日志、安全加固和部署能力。
|
||
|
||
### 17.4 把服务绑定到`0.0.0.0`
|
||
|
||
这会让服务监听所有可用网络接口。本课没有认证，不应扩大访问范围。
|
||
|
||
### 17.5 按字符数计算`Content-Length`
|
||
|
||
HTTP传输的是字节。包含中文时必须先编码，再计算字节长度。
|
||
|
||
### 17.6 忘记处理`HTTPError`
|
||
|
||
标准库遇到4xx和5xx会抛出`HTTPError`。错误对象中仍有响应体，应读取并用于定位问题。
|
||
|
||
### 17.7 端口不同就认为结果错误
|
||
|
||
本课故意使用随机可用端口。只要同一次运行中的请求端口一致即可。
|
||
|
||
## 十八、课堂练习
|
||
|
||
打开`practice.py`，完成图书管理接口设计、服务端实现和客户端调试。练习不提供答案或代码骨架。
|
||
|
||
## 十九、本课小结
|
||
|
||
一个接口是否正确，要从客户端请求、服务器处理和HTTP响应三个方向共同验证。框架会减少底层代码，但不会代替接口语义和业务规则设计。
|
||
|
||
## 二十、验收标准
|
||
|
||
- 本地服务能自动启动和关闭；
|
||
- GET、POST和404请求输出符合预期；
|
||
- JSON中文编码与`Content-Length`正确；
|
||
- 能设计完整的图书管理接口；
|
||
- 能说明本阶段知识与FastAPI的对应关系；
|
||
- 能完整描述GET和POST在服务器中的处理顺序；
|
||
- 能从请求方法、URL、状态码、响应头、响应体和数据变化六方面调试接口；
|
||
- 完成`practice.py`综合练习。
|