第6章 扩展与集成
第 6 章 · 扩展与集成
章节摘要：FastAPI 不提供全家桶，数据库、文档工具链、静态资源都要自己拼——本章演示怎么拼。数据库集成以 SQLAlchemy 为轴，对比同步引擎配线程池与异步引擎配事件循环两种形态，并落地"依赖注入管会话"的标准架构；OpenAPI 一节展开代码即契约的完整消费链（文档、客户端生成、契约测试）；静态文件与模板则对比应用内挂载与反向代理两种方案。
学习目标
阅读完本章，你应当能够：
- 搭出同步与异步两套 SQLAlchemy 会话架构并说明取舍；
- 解释 ORM 模型与接口模型分开维护的价值；
- 定制 OpenAPI 文档的元数据、标签与响应描述；
- 评估"文档生成客户端代码"在自己的协作链路里值不值得；
- 在 StaticFiles 挂载与 Nginx 托管之间按场景选择。
核心概念速览
一句金句：框架给了你胶水，没给你零件——自己选零件的过程，正是理清每个集成"该在哪个层做"的过程。
子章节导航
6.1 数据库集成：SQLAlchemy 同步与异步对比
两种引擎形态的完整写法对照、连接池参数的工程含义、会话由依赖管理的事务时序（呼应第 4 章的 yield 清理）、ORM 模型与接口模型的双轨维护，以及 SQLModel 这种"双轨合一"方案的收益与代价。
6.2 OpenAPI 与自动文档：代码即契约
从签名的类型约束（第 2 章）到本文档章的完整闭环：元数据与标签组织、错误响应的显式声明、文档安全的常见做法，以及把 OpenAPI JSON 当机器可读契约消费的三种方式。
6.3 静态文件：StaticFiles 与反向代理两种方案对比
开发期应用内挂载的便利与生产期反向代理托管性能、缓存头控制、HTTPS 终止的分工；Jinja2 模板渲染的挂法；以及"哪层该管静态资源"的判断框架。
子章节之间的逻辑关系
三节是三种典型的集成形态：
6.1 数据库（重集成：会话 事务 连接池） │ ▼ 6.2 OpenAPI（零集成：框架自带 只待深用） │ ▼ 6.3 静态资源（轻集成：一行挂载或交给代理）
6.1 是最重的集成——贯穿依赖注入、执行模型与事务边界三个前章主题，是前五章知识的综合应用；6.2 是最轻的集成——能力内建，工作在于定制与消费；6.3 介于两者之间，重心是架构分层的判断而非代码量。三节合起来展示了"没有全家桶"的完整含义：集成不是负担，是做分层决策的机会。
前置知识与后续延伸
- 前置：第 3 章的执行模型与依赖注入必须熟练（6.1 直接建立其上）；第 2 章的 Pydantic 建模（接口模型侧）。
- 为后续铺垫：6.1 的会话架构直接进入第 7 章生产部署的容量规划；6.2 的契约消费方式影响团队协作流程；6.3 的代理分工预告第 7 章的反向代理与容器化话题。
三种集成形态背后的一个母题
三节表面是三个工具的用法，内里是同一个判断母题的三次出现：这个职责应该放在哪一层。数据库会话放在依赖层而不是路由里（生命周期归请求）；契约文档放在代码里而不是文档平台（事实源唯一）；静态资源放在代理与 CDN 而不是应用进程（性能与缓存的专业分工）。每节的结论不同，推理结构相同——看清"这一层看得见完成这件事所需的全部信息吗、做好这件事是它的专长吗"。
这个母题在第 7 章还会出现第四次（部署层的进程守护归属）与第五次（性能防护在网关还是应用）。读者若能在本章就把推理结构提炼出来，第 7 章的两个决策可以直接套用——这也是对比驱动写法的用意：知识会过时，判断结构保值。
实践层面，本章三节各配了一个动手环节（6.1 的双会话事务实验、6.2 的文档生成规则实验、6.3 的两级服务压测对照），合计不到一小时，但能把"集成"从概念变成手感。
三个动手环节的价值
6.1 的双会话实验让你看见事务边界如何被依赖切割；6.2 的文档规则实验让你确认投影的稳定性；6.3 的两级压测让性能差距变成数据。三个实验共享一个特点：结论不依赖相信，依赖复现——这正是工程知识与传闻知识的分界。做完实验后，你对自己服务里的同类问题就有了量过、看过、改过的底气，后续遇到争论也能拿同样的实验方法回应，而不是互相转发链接。
本章小结
三种集成——重型的数据库、轻型的静态资源、零成本的文档——演示了同一个方法论在不同量级课题上的应用：先问职责归属（哪一层、哪个作用域），再搭机制骨架（依赖、挂载、声明），最后配容量与防护（三算、缓存、安全清单）。第 7 章把这个方法论带上最后一层：部署与运维。届时数据库的容量数字会直接进入 worker 规划，文档的契约会进入发布流程，静态资源的分层会变成反向代理的配置——本章是第 7 章全部决策的输入。
最后补一句关于集成测试的位置：本章三节的机制各自的测试要点——数据库集成的会话回滚正确性、文档生成的规范快照、静态挂载的路径可达——都该在第 5 章的测试体系里有对应用例。集成不是测试的例外区，恰恰是最该测的区域（它连接的边界最多、出问题的面最大）。本章每节动手环节的验证步骤，本质上就是这些用例的手工版，把它们自动化进测试目录，本章的收尾才算完整。