第4章 响应、错误与中间件

第 4 章 · 响应、错误与中间件

章节摘要：输入侧的契约建立之后，本章处理输出侧与横切层——响应的多形态输出与 response_model 输出契约、错误的统一表达与全局处理器、中间件的执行模型与 Flask 钩子的对照。三个主题合起来回答一个问题：数据离开业务函数之后、到达客户端之前，框架提供了哪些可控的环节。

学习目标

阅读完本章，你应当能够：

1. 用 response_model 收紧输出结构，解释它拦住敏感字段的时机；
2. 按场景选择 JSONResponse、HTMLResponse、FileResponse 与 StreamingResponse；
3. 用 HTTPException 与全局异常处理器搭出分层错误体系；
4. 写函数式与类式中间件，说明执行顺序与 Next 协议；
5. 对照 Flask 的 before/after 钩子与 CORS 处理方式，说出迁移对应关系。

核心概念速览

一句金句：输入模型守住门，输出模型守住窗，异常处理器守住逃生通道——三道防线齐了，接口的行为才是可预期的。

子章节导航

4.1 响应处理：多形态输出与响应模型契约

JSON 之外的世界：HTML、文件、流式输出各自的响应类与适用边界。重心放在 response_model——它与请求体模型共用同一套 Pydantic 机制，但方向相反：过滤、脱敏、输出校验。部分更新场景下"输入模型与输出模型分开建模"的完整推演也在这节。

4.2 错误处理：HTTPException 与全局异常处理器

从 404 与 422 的语义差异讲起，到 HTTPException 的 detail 结构、自定义异常类加全局处理器的设计，以及"业务错误码与 HTTP 状态码分层"的工程方案。对照 Flask 的 abort 与 errorhandler 装饰器。

4.3 中间件：CORS、GZip 与 Flask 钩子机制对比

中间件是包裹整个应用的洋葱圈：请求进入时逐层穿过、响应返回时逆序穿回。本节讲清函数式与类式两种写法、@app.middleware 与 add_middleware 的差异、CORS 与 GZip 两个内置中间件的配置要点，并给出与 Flask 钩子的对照表。

子章节之间的逻辑关系

三节分别占据输出链路的三段：

4.1 响应体（正常路径：数据怎么出去）
        │
        ▼
4.2 错误响应（异常路径：失败怎么出去）
        │
        ▼
4.3 中间件（横切路径：两条路径共同的包裹层）
​

正常返回走 4.1 的序列化通道，业务失败走 4.2 的异常通道，而无论哪条通道的响应最后都要穿过 4.3 的中间件链——CORS 头、压缩、日志都在这一层统一添加。理解这个分流模型后，"某个响应头为什么没加上"这类排错问题可以直接定位到链路的对应环节。

本章与前后章的衔接

前置是第 2 章的 Pydantic 建模——response_model 完全建立在那一章的模型机制上，v1 与 v2 的序列化 API 差异也会在本章出现。后续方面，第 5 章的安全认证会在中间件与依赖之间做选择讨论，测试一章会针对本章的错误体系写断言，第 7 章的 GZip 与缓存配置则是本章中间件话题在生产侧的延伸。

一个建议的实践顺序

本章的三节适合按"先输出、再错误、后横切"的顺序各配一次动手：给第 2 章写的模型补上对应的输出模型，故意让返回值多带一个字段，在文档页验证它被过滤掉——这是对 response_model 的第一次亲手验证；接着给某个接口加两个 HTTPException 分支，写个测试断言状态码与 detail 结构；最后抄写 4.3 节的访问日志中间件并跑一遍，观察终端里每条请求的日志行。三件事合计不超过一小时，但完成后你对"输出链路三层结构"的理解就从阅读记忆变成了操作记忆——后续排查"字段怎么泄漏的""错误格式怎么不统一""响应头怎么没加上"这类问题时，你会直接知道该看哪一层。

排错速查也随之建立：响应里出现不该有的字段，查 response_model 的声明与模型定义；错误格式不统一，查是走了 HTTPException 通道还是自定义异常通道；响应头缺失，查中间件顺序（第 4.3 节的注册规则）；状态码不符合预期，回到语义归属表核对触发层。四个问题对应四层机制，一层一钥匙。

章末自测：六个场景题

检验本章掌握程度的六个场景，答案都在正文里：一，接口返回了用户表的哈希字段，问题出在哪层、怎么修（response_model 与模型分轨）；二，前端抱怨错误格式时对时错，排查什么（两条异常通道是否各安其位）；三，CORS 配置正确但预检失败，查哪里（中间件顺序与方法放行）；四，想在所有响应加安全头，放中间件还是依赖（影响面判断）；五，部分更新接口把没传的字段清空了，什么原因（更新模型的缺省语义）；六，大文件下载占满了 worker，换哪个 Response（FileResponse 的异步读盘）。六题全对，本章的机制与判断就都到手了。

本章小结

输出侧三件套——响应模型、错误体系、中间件链——合起来构成服务的"出口质量控制系统"：正常数据经过滤出去、失败经过翻译出去、一切经过包裹出去。三层各自的判断框架（契约同源、语义分层、影响面选择）比具体语法更值得带走：它们会在你接触任何新框架的输出体系时再次生效。下一章带着这套出口系统进入生产三件套（安全、任务、测试），那里会反复调用本章的机制——错误处理器接住认证失败、中间件包裹访问日志、测试断言错误契约——本章是它们共同的工具箱。