FastAPI 故障分析：阻塞、校验、锁与事务结果

前置：完整项目、线程协程。本篇的状态与响应均是设计预期，示例未执行。排障先记录请求形状、错误阶段和数据库状态，不把所有失败都归到“异步不稳定”。

async def 中的阻塞

FastAPI为什么用了async还是会阻塞？async def不会把sqlite3变成异步驱动，直接调用阻塞I/O会占住事件循环；本例普通def路由让框架在线程池执行同步数据库工作。await只能等待可等待对象，不能给普通sqlite3.execute前加await来修复阻塞。

若同步工作被从async路由直接调用，普通工具函数仍在当前线程执行，框架不会自动搬走每个内部函数调用。需要明确把完整阻塞工作移入合适线程边界，或选择真正异步驱动并重审事务/连接所有权。CPU密集任务也不因async变快；线程池容量与排队、请求取消和外部数据库等待应分别测量，不能无证据承诺并发倍数。依据：FastAPI并发。

422 的来源

FastAPI返回422时先检查哪里？先检查JSON请求体的字段、严格整数与路径范围，再确认Content-Type和客户端实际发送内容；本例校验错误统一invalid_request，详细原始输入不会回显。cents="1250"即使可被人读作数字，也违反严格整数契约。

无效JSON、缺字段、多余id、未定义category及非整数路径都在请求边界失败。测试规格包含缺字段、空/超长reference、1.0浮点金额与原始无效JSON，同时检查状态与错误schema，并检查列表仍为空。只断言状态不够，错误处理器可能意外返回HTML或泄漏原输入；只检查响应JSON也不够，服务端可能错误返回200。不要把业务409改成422以减少状态种类，前者表示有效请求与当前账本状态冲突。

响应校验失败与已提交状态

FastAPI响应校验失败是否说明事务没有提交？不能据此推导；响应校验和网络发送发生在业务事务之外，提交后客户端仍可能收到服务器错误或连接中断。本例创建先构造Expense后COMMIT缩小风险，但不声称实现跨数据库与HTTP的原子提交。

已有坏行、错误SELECT投影或未来序列化修改仍可能导致读取失败。应保留请求关联信息、内部异常栈与必要的脱敏字段，区分模型构造失败、提交失败、响应验证失败和网络断开。客户端重试会遇到duplicate_reference；当前协议给409而不重放原结果。不要在except Exception中返回空列表，那会把真实故障伪装成合法空账本。

SQLite 忙锁与事务恢复

FastAPI的SQLite忙锁应该返回什么？本例只把SQLITE_BUSY和SQLITE_LOCKED主错误码转换成503 storage_busy，保留其他OperationalError作为服务器故障；忙锁不是非法输入，不能返回422。错误码低8位用于识别主码，不用脆弱的异常字符串匹配。

单请求连接timeout=0.2秒不是整体HTTP截止时间；线程排队、启动、查询和响应都可能增加延迟。BEGIN IMMEDIATE失败尚未进入事务；事务内出错则检查in_transaction回滚后重抛。依赖finally关闭连接，不能将异常吞掉后yield第二次或返回伪成功。恢复规格先用独立连接持锁、请求得503，再释放锁并预期新增成功；这比随机sleep更有因果约束，但本轮未执行。

503可提示调用方稍后重试，仍需退避、上限与重复处理策略；本例没有实现重试中间件或Retry-After承诺。磁盘满、路径权限、表缺失和损坏不应一律装成可重试锁。SQLite行为依据Python3.12文档。

环境、线程和生命周期排查

FastAPI出现线程或关闭连接错误如何排查？先检查是否误把连接放到全局、后台任务或并行协程，再检查check_same_thread与yield作用域；本例function作用域只适合路由内物化完成的结果。数据库连接关闭过早、内存数据库每连接隔离和lifespan未进入，是三个不同原因。

若TestClient没有作为with上下文进入，初始化可能不发生；若默认相对路径与预期工作目录不同，可能访问另一个数据库；若旧文件表结构不符，CREATE TABLE IF NOT EXISTS不会修复。若ModuleNotFoundError，先核对实际venv解释器及固定依赖，不在本轮自动安装。from __future__ import annotations和闭包中的Database别名需要共同审查；本例刻意使用立即求值注解，复制时不要无意改变解析条件。

固定版本元数据只是兼容范围证据。本轮没有安装、服务日志、端口探测、浏览器结果或HTTP返回记录，因而不能宣称“跨Windows/Linux已验证”。静态通过仍需由读者执行README步骤后记录解释器、依赖解析、测试输出和实际schema差异。

练习

1. 一个请求显示500，数据库却新增一条，为什么不应立刻重写回滚逻辑？
2. 所有OperationalError都映射503会隐藏哪些问题？
3. 准备一个确定性忙锁规格，为什么优先持有BEGIN而不是让测试sleep碰运气？
4. 把依赖改成request作用域后流式响应是否就自动安全？

参考答案

先确定提交与响应哪个阶段失败；已经提交的事务不能靠后续回滚撤销，需明确重复提交协议。表不存在、磁盘满或权限问题若伪装忙锁会导致无意义重试。独立连接先取得写锁建立明确前置条件，释放后再验证恢复；sleep无法证明锁是否被持有。request作用域仅调整资源退出时间，仍须处理生成器异常、取消、后台任务及实际持有资源，不能把作用域开关当成所有生命周期问题的修复。