外观
交付真实 API:FastAPI 生命周期、中间件与错误契约
摘要
函数正常,服务器却缺资源,错误响应还对不上日志。本文面向有开发经验的 Python 初学者,用 FastAPI 和 uvicorn 的真实请求验证生命周期、分页与错误契约。
资料核验日期为 2026-10-29;FastAPI 与 uvicorn 官网使用滚动文档,本文不把该页面称为固定版本源码。实际安装版本和运行证据以工程实践与验收手册为准。
本篇已在 Windows x64、CPython 3.13.7、FastAPI 0.162.0、uvicorn 0.54.0、Starlette 1.10.0、Pydantic 2.14.1 与 pydantic-core 2.50.1 实跑通过。测试使用一个 worker、asyncio loop 和 h11 HTTP 实现;这些条件不代表其他部署组合已验证。
1. 场景:业务函数能用,网络接口却没有完成交付
这是教学场景:日志查询函数通过了单元测试,开发者把它放进 Web 路由。启动过程中没有准备仓储,第一次请求得到属性不存在;修复后参数错误返回框架默认结构,资源不存在返回自定义文本,客户端必须猜错误格式;再加入请求编号,只给成功响应添加了头,失败日志无法关联用户请求。
沿两条方向追请求:进入时,服务器与框架逐层把字节变成合法业务参数;返回时,业务结果或已处理异常逐层变成带编号的HTTP响应。资源还有一条独立生命线:启动时准备,服务中借用,关闭时释放。把这三条线分开,首次请求缺资源、未知路由错误格式和清理遗漏就不再是一个模糊的“Web问题”。
先保持查询业务不变,只把入口从直接调用查询函数换成真实TCP。函数能返回列表并不能预测HTTP参数错误会不会带编号,也不能预测服务启动是否已创建仓储。上一章测试分层的边界判断在这里继续适用:新增哪一段链路,就为那一段补实际证据。
FastAPI 是构建 ASGI Web 应用的框架;uvicorn 是运行 ASGI 应用的服务器。ASGI,即 Asynchronous Server Gateway Interface,是服务器与应用之间的调用协议。FastAPI 内部使用 Starlette 提供路由和中间件等能力,并使用 Pydantic 进行数据验证;具体版本以配套环境和工程实践与验收手册为准。不要把框架和服务器当同一个进程职责,框架定义处理规则,服务器负责监听与协议驱动。
本例面向可信本机教学环境,只绑定 127.0.0.1,不提供身份认证、授权或互联网入口。它验证框架生命周期和响应契约,不宣称已经具备生产安全。后续安全篇补充认证与资源访问规则;本篇也不会因为一个 health 成功就把服务称为生产就绪。
2. 从 TCP 请求到路由函数,谁负责哪一段
客户端连接本机监听 socket,经 uvicorn 处理 HTTP 得到 ASGI scope 与消息接口,再交给应用。Scope 可以理解为本次连接或请求的上下文,其中含请求路径、方法、头等信息。框架进行中间件包装和路由选择,对匹配路由的参数做校验,之后才调用业务处理函数。
@app.get("/events") 注册 GET 路由,不是在模块导入时执行一次查询。after: int = Query(0, ge=0) 指定默认值与非负约束,limit 限定一到一百。HTTP 查询参数到达时本质上是文本,框架根据声明完成解析及验证;不能说 Python 的 int 注解本身在所有函数调用时都会强制转换。普通函数直接传入字符串,仍需由自己的代码负责。
本例接受框架对查询文本的整数解析规则,没有要求最严格的原始文本语法。若业务只接受十进制规范格式、不允许特定空白或表示形式,需要进一步约束并测试实际请求,不能把“类型是 int”当成完整协议。限制 limit 同时保护输出大小,但仓储扫描成本仍要另算。
响应对象从路由或异常处理器返回后,框架编码为 HTTP 响应,经服务器发送到 socket。当前示例返回普通字典,FastAPI 负责序列化;正式 API 应进一步声明 response model,即响应结构模型,避免内部字段意外进入接口,并明确 OpenAPI 文档。网络测试应解析真实字节而不是直接比较返回的 Python 对象。
图表将在阅读到此处时加载…
若想追到服务器与应用消息协议,继续看HTTP 与 WSGI/ASGI;本篇重点是框架实际调用顺序,不重复把协议名当实现答案。
3. Lifespan 把资源拥有者放在应用边界
先预测事件列表什么时候可读。只调用create_app得到应用对象,不表示服务器已经驱动startup;业务请求必须等准备完成。Lifespan是ASGI的应用生命周期协议,示例用asynccontextmanager把这条生命线写成yield前准备、yield期间服务、finally清理:
| 位置 | 拥有者动作 | 应该观察的状态 |
|---|---|---|
| yield之前 | 创建教学事件并设置started | 准备完成后才发送业务请求 |
| yield期间 | 路由借用该应用的数据 | 分页与单查读取同一实例的资源 |
| finally之后 | 清空数据并标记closed | 服务器线程结束,清理标记与列表同时符合断言 |
uvicorn显式配置lifespan="on",所以实验不是猜测自动探测结果。将close放进单次查询会提前截断资源生命线;只等待线程退出却不检查closed,则遗漏了应用清理这一段。
这比模块顶层创建资源更适合服务装配。导入模块时可能只是收集测试、生成文档或启动管理命令,不能顺便连接数据库或读取一次配置。应用工厂 create_app 每次创建独立应用对象,资源由应用生命周期持有;后续可在这里组装Protocol 仓储,业务路由依赖能力,而不负责关闭整个应用资源。
应用级资源在每个服务器进程里分别创建。若部署多个 worker,内存列表不会自动共享,启动标记也不是全局共享状态。真实数据必须放入具有合适一致性和持久化保证的外部存储,连接池一般属于各 worker。不能把本例全局事件列表直接扩大成跨进程业务数据库。
启动失败意味着该应用实例没有完成准备,应该阻止接收业务流量;健康检查要区分进程还活着和业务已经准备。示例 health 只检查教学 startup 已完成,真实 readiness 是否需要数据库、消息系统等依赖,取决于服务的可用性设计。过度检查所有下游也可能把部分故障放大成全面摘流,需要后续可用性实验。
关闭时,服务器先停止接收并协调已有任务,再驱动应用清理,具体超时和实现依服务器版本及配置。本例在 finally 请求 uvicorn 退出、限时 join,并确认关闭标记与列表清空。它不测试强制杀进程;如果进程被立即终止,不能承诺 Python finally 执行。持久化与恢复必须另有机制,生命周期回调不是崩溃恢复协议。 可进一步阅读网络超时与重试:客户端服务器下游分别有超时边界。
4. Request ID 是关联字段,不是可信身份
Request ID,请求编号,用于将响应、应用日志和后续调用关联到一次请求。示例中间件尝试把输入头解析为 UUID,合法则规范化,非法则生成新 UUID。UUID 是一种通用唯一标识格式;这里要求格式只是限制任意文本进入关联字段,不证明客户端身份,也不保证恶意客户端不重复提供编号。
编号保存在 request.state,表示本次请求上下文,不放入模块级变量。并发请求如果共享一个全局 current_request_id,后来的请求可能覆盖先前编号,造成日志串线。异步任务需要继续关联时,可考虑 contextvars,但要明确任务继承与线程边界;保存为请求属性是本例最小可理解方案。
中间件调用 call_next 将处理交给内层,再为返回响应追加 x-request-id 头。已被框架处理的参数错误和业务 HTTP 错误同样沿返回路径,因此都能带头。未处理异常、流式响应中途出错、客户端断开等情况有不同边界,不能只凭 call_next 的成功路径保证全部故障都会得到完整 JSON。本例明确只统一已处理的 HTTP 与输入错误。
客户端提供的请求编号应限制格式、长度并规范化;日志仍应结构化编码,不能用字符串拼接把头内容写成日志语法。此处 UUID 规则避免直接回显任意文本,但请求编号不是权限令牌,不能用它访问别人的数据。面试解释关联与认证时,先说清两者使用目的,避免把一个看似随机的字符串当安全凭证。
5. 错误契约需要覆盖框架边界
本例错误响应是 {"error": {"code": "...", "request_id": "..."}}。参数验证失败为 HTTP 422 与 invalid_input;事件不存在为 HTTP 404 与 event_not_found;未知路由的 HTTP 404 也经过统一包装。具体状态码选择是本例接口契约,不能说所有系统必须使用 422。
保持相同错误envelope,比较两种404:路由内单查不存在事件,以及请求/unknown根本没有匹配路由。前者由业务抛FastAPI的HTTPException,后者由框架产生;它们都应该回到公共响应约定。FastAPI异常基于Starlette类型,因此示例注册StarletteHTTPException,在更基础的类型边界接住这两条返回路径。
这时request_id不只是成功头。已处理异常先被转为响应,再返回外层中间件添加头,体与头中的编号才可对应。主例专门请求未知路由:如果只验业务404,可能漏掉框架默认detail结构。这里仍不推导未处理异常或流式发送中断也走同样路径,那些情况需要另扩边界验证。
当前 unknown route 的 code 使用框架提供的 Not Found 文本,是教学协议明确验收的返回值,不适合作为长期跨语言错误枚举设计。正式服务应将框架异常映射成稳定业务代码,并给出兼容性约定。参数错误不回显全部原始输入,避免详细验证结构与敏感数据进入公共响应;服务端若记录细节,也需要脱敏。
业务空页不是异常,应返回 items 空列表、next_after 为 null;资源单查不存在才是 404。外部依赖失败也不能伪装成空页,否则客户端会误认记录不存在。未处理的程序错误需要安全的通用 500 响应、日志与指标,本文保留为生产扩展边界,不能在中间件里捕获所有错误后统一返回 200。
6. 完整实验:真正启动服务器并发送请求
请使用完整 CPython 的隔离环境安装锁定依赖。Windows 命令如下;Linux/macOS 将环境解释器改为 .venv/bin/python,该平台命令未在本机执行。框架、服务器以及间接依赖一起锁定,避免只写主包版本却忽略验证器与 ASGI 依赖的变化。
powershell
python -m venv .venv
.venv/Scripts/python.exe -m pip install -r docs/python/examples/capstone/requirements.lock.txt
.venv/Scripts/python.exe docs/python/examples/28_api.py完整代码 28_api.py 在本机创建监听 socket,绑定端口零让操作系统分配空闲端口,把已绑定 socket 交给 uvicorn。这样避免“先寻找空闲端口、关闭它、再启动服务器”之间端口被抢占的窗口。服务器在线程里运行,但请求仍经真实 TCP 与 HTTP,没有直接调用路由。
python
"""真正启动 uvicorn 经 TCP 验证 FastAPI 生命周期与错误协议。"""
from contextlib import asynccontextmanager
import json
import socket
import threading
import time
from urllib.error import HTTPError
from urllib.request import Request, urlopen
from uuid import UUID, uuid4
from fastapi import FastAPI, HTTPException, Query, Request as APIRequest
from fastapi.exceptions import RequestValidationError
from fastapi.responses import JSONResponse
from starlette.exceptions import HTTPException as StarletteHTTPException
import uvicorn
def create_app():
@asynccontextmanager
async def lifespan(app):
app.state.events = [{"id": 1, "path": "/health"}, {"id": 2, "path": "/orders"}]
app.state.started = True
app.state.closed = False
try:
yield
finally:
app.state.events.clear()
app.state.closed = True
app = FastAPI(lifespan=lifespan)
@app.middleware("http")
async def request_id(request: APIRequest, call_next):
incoming = request.headers.get("x-request-id", "")
try:
correlation = str(UUID(incoming))
except (ValueError, AttributeError):
correlation = str(uuid4())
request.state.request_id = correlation
response = await call_next(request)
response.headers["x-request-id"] = correlation
return response
def error_response(request, status, code):
return JSONResponse(status_code=status, content={"error": {
"code": code, "request_id": request.state.request_id}})
@app.exception_handler(RequestValidationError)
async def validation_error(request, exc):
return error_response(request, 422, "invalid_input")
@app.exception_handler(StarletteHTTPException)
async def business_error(request, exc):
return error_response(request, exc.status_code, str(exc.detail))
@app.get("/health")
async def health():
return {"ready": app.state.started}
@app.get("/events")
async def events(after: int = Query(0, ge=0), limit: int = Query(1, ge=1, le=100)):
selected = [event for event in app.state.events if event["id"] > after][:limit]
return {"items": selected, "next_after": selected[-1]["id"] if selected else None}
@app.get("/events/{event_id}")
async def event(event_id: int):
for value in app.state.events:
if value["id"] == event_id:
return value
raise HTTPException(status_code=404, detail="event_not_found")
return app
def main():
app = create_app()
listener = socket.socket()
listener.bind(("127.0.0.1", 0))
listener.listen(16)
port = listener.getsockname()[1]
server = uvicorn.Server(uvicorn.Config(app, log_level="error", lifespan="on",
workers=1, loop="asyncio", http="h11"))
thread = threading.Thread(target=lambda: server.run(sockets=[listener]))
thread.start()
def get(path, correlation=None):
headers = {"x-request-id": correlation} if correlation else {}
request = Request(f"http://127.0.0.1:{port}{path}", headers=headers)
try:
response = urlopen(request, timeout=2)
except HTTPError as exc:
response = exc
with response:
return response.status, response.headers["x-request-id"], json.loads(response.read())
try:
deadline = time.monotonic() + 5
while not server.started:
if not thread.is_alive() or time.monotonic() >= deadline:
raise RuntimeError("server startup failed")
time.sleep(0.01)
assert get("/health")[2] == {"ready": True}
correlation = "00000000-0000-0000-0000-000000000001"
status, echoed, first = get("/events?limit=1", correlation)
assert status == 200 and echoed == correlation and first["next_after"] == 1
assert get("/events")[2] == first # 明确验证默认 after=0、limit=1。
assert get("/events?after=1&limit=1")[2]["items"] == [{"id": 2, "path": "/orders"}]
assert get("/events?after=2")[2] == {"items": [], "next_after": None}
for path, expected_status, code in (("/events?limit=0", 422, "invalid_input"),
("/events/no-number", 422, "invalid_input"),
("/events/999", 404, "event_not_found"),
("/unknown", 404, "Not Found")):
status, echoed, payload = get(path, correlation)
assert (status, payload["error"]["code"], payload["error"]["request_id"]) == (
expected_status, code, echoed)
_, generated, _ = get("/health", "untrusted arbitrary text")
assert str(UUID(generated)) == generated
finally:
server.should_exit = True
thread.join(timeout=5)
listener.close()
assert not thread.is_alive()
assert app.state.closed and app.state.events == []
print("28 checks: real TCP; validation/paging/error IDs; startup/shutdown cleanup")
if __name__ == "__main__":
main()在配套环境运行 python docs/python/examples/28_api.py。实跑输出 28 checks: real TCP; validation/paging/error IDs; startup/shutdown cleanup。测试确认 health、默认分页、两页游标、空页、非法 limit、非法路径参数、资源不存在、未知路由、合法编号回显与非法编号重建;退出后确认线程结束及 lifespan 清理。真实依赖版本和运行结果见工程实践与验收手册。
等待 startup 使用 monotonic 限制五秒,并检查服务器线程仍存活;循环里的短 sleep 只是减少忙等,不是证明应用已启动的固定延迟。业务开始条件由 server.started 决定。若启动失败,测试抛错误并进入 finally 请求停止,不会无限等待。服务器测试线程不是 daemon,必须明确关闭,不能依赖主进程退出掩盖泄漏。
HTTPError 仍可包含真实状态、头和响应体,因此客户端捕获后继续按同样协议读取。若只调用 urlopen 的成功路径,错误响应测试会在工具异常处中止,根本没有验收错误 JSON。这里使用 with 关闭响应对象,服务端清理也由 finally 保证;测试自身同样要遵守资源规则。
7. 容易踩的坑:异步路由、分页与框架默认值的边界
async def 路由不意味着所有代码都非阻塞。同步数据库查询或长 CPU 循环直接放进协程,仍可能占住事件循环。已查读 FastAPI 0.162.0 的安装源码:普通 def 路由由 routing.run_endpoint_function 经 run_in_threadpool 交给线程工作流程;非生成器同步依赖也由 dependencies.utils.solve_dependencies 走该流程,协程调用则被 await。这个包装发生在框架调用边界,路由内部自己调用的普通函数不会因此自动移出 loop。当前教学列表读取很小,没有构造吞吐结论。
再将“参数转换→业务能力→响应”迁移到数据库仓储。after与limit的公共规则可以不变,但列表推导式现在仍扫描整个列表,limit只缩小结果,不保证计算费用也缩小。替换成SQL时,要让查询、装载与连接生命线在返回响应前闭合,再用索引计划、借出数和查询次数补存储层证据。
这解释了为何本篇TCP分页通过后还需要连接池与ORM:公共接口可以保持,内部资源与成本改变了。线程数、池大小和尾延迟由后续容量实验判断,不能从几条顺序请求推导吞吐。
同样不把本地端到端测试叫压测。它发送顺序请求,证明功能与清理,不证明高并发、慢客户端、流式响应、进程重启或生产 TLS 配置。要讨论性能必须固定服务器版本、worker 配置、硬件与负载模型,并通过性能测量的原则分析。
8. 独立练习与验收
把事件列表替换成 Protocol 仓储,通过应用工厂注入内存实现;新增写入路由,规定重复 id 的 HTTP 状态与稳定错误代码。要求输入、业务与框架错误使用同一公共 envelope,并保留 request_id。不要让路由直接访问 SQLite connection,否则接口分层在接入框架时又消失。
验收需实际启动 uvicorn,经 TCP 检查成功写入、重复写入、非法字段、空页、连续分页、未知路由、非法请求编号;关闭后确认仓储释放。再故意删掉生命周期初始化,测试必须在准备或请求边界失败;恢复后全部通过。提交的证据包括依赖版本、启动方式、请求与响应、清理结果及未覆盖边界,而不是一张接口文档截图。
将应用资源、请求资源与事务资源分开
应用级资源适合保存连接池或不可变配置,请求级资源适合请求编号与当前访问上下文,事务资源适合一次一致性操作。把三者都放入 app.state 并不意味着作用域正确:一个共享连接若不支持跨线程使用,会在并发路由里失败;把请求编号共享给所有请求,会串线;把事务持续整个应用生命,则锁与未提交数据长期占用。
FastAPI 的依赖机制可以为路由提供已装配能力,也可以用带 yield 的依赖管理资源,但释放时机需要结合实际版本、依赖 scope 与流式响应核验。本例不使用这些版本敏感默认值,而把教学资源集中在 lifespan。引入请求级数据库会话时,应让测试覆盖正常响应、业务异常和取消,不只确认依赖函数曾被调用。
中间件链的顺序决定错误经过哪一层。已处理的 HTTP 异常由异常层转为响应再返回,中间件能够添加头;未处理错误可能传播到外层服务器错误处理。若要求所有错误都具有统一编号,需要具体检查异常层与中间件装配,尤其验证内部异常和响应发送中断。不能依据一张抽象图认定任何装配顺序都正确。
当前测试采用一个 uvicorn 实例与一个监听 socket。把多个 worker 加入部署后,还要证明各进程启动、各自资源释放、共享存储正确性和负载分配。应用工厂有助于重复创建,但不会自动生成部署策略。后续发布与容量篇将从进程管理、健康检查、回滚和预算角度补足这些问题。
独立验收可增加两次 create_app 的资源隔离:修改第一个应用的教学事件,不应改变第二个应用;分别启动和关闭两者,清理标记各自准确。再通过 TCP 请求未声明路由和非法参数,检查头与体中的 request_id 一致。这样同时证明工厂隔离、生命周期和公共协议,不依赖模块导入顺序恰好正确。
一句话总结:API 交付要在真实服务器链路上同时证明输入、响应、生命周期和错误关联。
- 框架处理路由与校验,ASGI 服务器负责监听和协议驱动,职责各有边界。
- 资源由
lifespan的拥有者管理,模块导入和进程强杀都不能代替生命周期。 - 错误契约与
request_id必须覆盖框架产生的错误,并由真实网络请求验收。
参考:FastAPI lifespan、middleware、handling errors、uvicorn settings、ASGI lifespan。核验范围见工程实践与验收手册。