04.7.15.5 测试性能与生产部署
所属:全栈开发面试题库 / 04 后端语言与运行时 / 04.7 Python / 04.7.15 FastAPI 框架
覆盖范围
TestClient(httpx 后端)、AsyncClient+ASGITransport测试写法dependency_overrides、测试数据库、事务回滚隔离、app factory 与 fixture- lifespan 在测试中的执行、WebSocket 与异常处理器测试
- 性能热点:响应模型序列化、Pydantic 构造校验、JSON 编码、大列表内存
- locust/wrk 压测口径、GIL 与 worker 配置
- uvicorn/gunicorn 部署、容器与健康检查、优雅停机、
root_path反代与 Nginx - 日志、
prometheus-fastapi-instrumentator、OpenTelemetry 链路追踪 - 0.11x 版本兼容与弃用项、典型坑:同步依赖阻塞、
Depends缓存 session 复用、资源泄漏
04.7.15.5-001 TestClient 基于什么后端,怎么发起请求?
一句话结论
Starlette/FastAPI 的 TestClient 基于 httpx 客户端,通过 ASGI 传输把请求直接送入应用,不监听真实端口;用 client.get/post/... 发起同步调用,响应可断言状态码、JSON 体与头。它在测试线程内运行事件循环,适合 pytest 集成测试。
概念解释
TestClient包装了 ASGI 应用与 httpx 传输,测试不依赖网络端口与部署进程。- 同步 API 掩盖了内部异步执行,测试代码不必直接写 await。
原理流程
- 构造
TestClient(app),内部建立 ASGI 传输与事件循环。 - 调用
client.get("/items"),httpx 构造请求经传输进入应用。 - 应用在循环内完成路由、依赖、端点与序列化。
- 响应回到客户端对象,断言
status_code、json()、headers。
代码或图示
from fastapi.testclient import TestClient
from main import app
client = TestClient(app)
def test_list_items():
resp = client.get("/items")
assert resp.status_code == 200
assert isinstance(resp.json(), list)
常见误区
- 以为 TestClient 起了真实服务器:它走内存 ASGI 传输,端口可留空。
- 在测试里直接
awaitTestClient 方法:它是同步接口,await 用法错误。
追问
- TestClient 底层 HTTP 库是什么?答:httpx(Starlette 0.4x 版本对应实现,待确认:验证点:所用版本 TestClient 的传输类名与 httpx 版本约束)。
- 测试需要真实端口怎么办?答:另起 uvicorn 进程做端到端测试,TestClient 只做进程内集成测试。
04.7.15.5-002 AsyncClient + ASGITransport 与 TestClient 有什么差异?
一句话结论
httpx.AsyncClient 搭配 ASGITransport(app=app) 是异步测试写法:测试协程内直接 await client.get(...),事件循环由 pytest-asyncio 管理;TestClient 是同步封装,内部自行驱动循环。两者都不监听端口,异步写法更贴近生产异步栈,便于测试异步依赖与后台任务。
概念解释
ASGITransport把 httpx 请求转成 ASGI 调用,是连接 HTTP 客户端与 ASGI 应用的桥。- 异步测试可直接 await 异步夹具、异步会话与任务组。
原理流程
- 构造
ASGITransport(app=app),传入AsyncClient(transport=...)。 - 测试协程 await 请求方法,应用在同一循环内处理。
- 响应返回后断言 JSON 与状态码。
- 夹具按 async fixture 生命周期初始化/清理。
代码或图示
import pytest
from httpx import AsyncClient, ASGITransport
from main import app
@pytest.mark.asyncio
async def test_item():
transport = ASGITransport(app=app)
async with AsyncClient(transport=transport, base_url="http://test") as client:
resp = await client.get("/items")
assert resp.status_code == 200
常见误区
- 异步客户端忘了传 transport:默认走真实网络,测试访问不到内存应用。
- 混用同步 TestClient 与异步夹具:循环与上下文冲突,应整套保持一致。
追问
- 什么时候选异步写法?答:被测代码深度异步(异步 DB、消息队列、后台任务)或需要在测试中 await 协程时。
- ASGITransport 需要真实域名吗?答:不需要,
base_url仅用于拼接路径。
04.7.15.5-003 如何用 dependency_overrides 替换测试依赖?
一句话结论
app.dependency_overrides[原依赖] = 替换依赖 把原依赖在测试期间替换为 mock/测试实现,测完清空映射;按夹具作用域在 setup 注入、teardown 恢复。适合替换数据库会话、认证用户、外部客户端等不希望在测试中真实初始化的依赖。
概念解释
- 替换按依赖函数对象匹配,不是按名字字符串。
- 覆盖优先级高于原始依赖,路由与子依赖链一并生效。
原理流程
- 测试夹具保存原依赖引用与覆盖表。
- 写入
dependency_overrides,返回测试用依赖结果。 - 请求经过路由时解析到替换后的依赖。
- 测试结束清空覆盖表,避免污染其他用例。
代码或图示
async def override_get_db():
session = test_session_factory()
yield session
session.rollback()
app.dependency_overrides[get_db] = override_get_db
def test_create_item():
resp = client.post("/items", json={"name": "杯"})
assert resp.status_code == 201
app.dependency_overrides.clear()
常见误区
- 测完不清空覆盖:后续用例意外使用 mock 依赖。
- 覆盖函数签名与原依赖不一致:注入参数对不上,校验失败。
追问
- 能覆盖带
yield的依赖吗?答:能,替换依赖同样可用生成器表达 setup/teardown。 - 路由器级依赖能覆盖吗?答:能,覆盖表按函数对象匹配,路由器挂载的依赖同样生效。
04.7.15.5-004 测试数据库怎么隔离,有哪些策略?
一句话结论
常见策略:独立测试库(每轮套件重建/迁移)、事务回滚(每个用例在事务内结束后 rollback)、表清空(truncate/重插基线数据)。隔离目标是用例之间数据互不影响;单元测试可用内存/替身,集成测试用可重建的真实数据库实例。
概念解释
- 回滚隔离最快,适合支持事务的关系库;部分 ORM/DDL 操作无法回滚时用清空策略。
- 测试库与开发/生产库严格分离,配置走环境变量。
原理流程
- 测试启动前创建/迁移测试库与基线数据。
- 每个用例开启事务,结束回滚或清理相关表。
- 断言基于用例内构造的数据,不依赖残留状态。
- 套件结束销毁测试库实例(容器化环境)。
代码或图示
@pytest.fixture
def db_session():
conn = engine.connect()
trans = conn.begin()
session = Session(bind=conn)
yield session
session.close()
trans.rollback()
conn.close()
常见误区
- 测试连开发库:用例删除/修改他人数据,结果不可复现。
- 用例之间靠“记得清理”:遗漏即产生顺序依赖,flaky 难定位。
追问
- NoSQL 数据库怎么做隔离?答:按测试用例建独立集合/命名空间或用完删除文档,容器化实例按套件重建。
- 迁移脚本在测试中跑吗?答:集成测试应跑迁移,验证 schema 演进本身可用。
04.7.15.5-005 事务回滚式隔离的 fixture 怎么写?
一句话结论
夹具打开一个外层事务,会话绑定该连接;用例内所有写入落在事务里,结束后 rollback 撤销;提交类操作在测试中需特殊处理(嵌套事务/保存点)。回滚隔离避免 truncate 全表,速度快且不依赖表间关系顺序。
概念解释
- SQLAlchemy 2.x 用
begin()开启事务,会话rollback()回滚外层。 - 被测代码若调用
commit(),需用嵌套事务(SAVEPOINT)包裹,避免提前提交污染隔离。
原理流程
- 夹具获取连接并开启外层事务。
- 构造绑定该连接的会话交用例使用。
- 用例执行请求与断言。
- 结束关闭会话,回滚外层事务,归还连接。
代码或图示
@pytest.fixture
def session():
connection = engine.connect()
transaction = connection.begin()
session = Session(bind=connection)
yield session
session.close()
transaction.rollback()
connection.close()
常见误区
- 会话结束直接
commit():数据残留到下一个用例,隔离失效。 - 连接与事务生命周期不一致:回滚前连接已归还池,撤销不到写入。
追问
- 被测代码必须 commit 怎么办?答:用嵌套事务/保存点让 commit 只释放保存点,外层回滚仍可撤销。
- 回滚隔离对 DDL 有效吗?答:多数关系库 DDL 隐式提交,无法回滚,需改用清空策略。
04.7.15.5-006 app factory 模式与测试 fixture 怎么装配?
一句话结论
应用工厂 create_app(settings) 返回配置好的 FastAPI 实例;测试夹具调用工厂注入测试配置(测试库、关闭文档、覆盖依赖),按用例需要装配。工厂模式让测试能构造隔离实例,避免全局单例带来的状态串扰。
概念解释
- 工厂参数区分环境:开发、测试、生产读不同配置对象。
- 工厂内部注册路由、中间件、异常处理器与 lifespan。
原理流程
- 定义
create_app(config),内部组装应用。 - 测试夹具用测试配置调用工厂。
- 在实例上写
dependency_overrides并共享夹具。 - 每个用例可拿到干净实例,结束销毁。
代码或图示
def create_app(config: Settings) -> FastAPI:
app = FastAPI(lifespan=lifespan)
register_routers(app)
return app
@pytest.fixture
def app():
test_config = Settings(env="test", db_url=TEST_DB_URL)
return create_app(test_config)
@pytest.fixture
def client(app):
return TestClient(app)
常见误区
- 工厂内读全局环境变量而不接收参数:测试无法替换配置。
- 多个用例共享同一实例且改了全局状态:后续用例受污染。
追问
- 工厂模式与全局
app = FastAPI()相比优势?答:可按环境构造实例、便于测试隔离、支持多配置并行。 - 中间件顺序在工厂里定吗?答:是,工厂按生产相同顺序注册,测试才覆盖真实链路。
04.7.15.5-007 测试中 lifespan 会不会执行,怎么控制?
一句话结论
TestClient 作为上下文管理器使用时会触发 lifespan 启动/关闭事件;直接实例化不用 with 进入时,部分版本行为不完整。需要测试启动初始化(建池、预热)时用 with TestClient(app) as client:;想跳过 lifespan 可拆分资源初始化到可替换依赖,或在测试夹具中手动控制。
概念解释
- lifespan 对应 ASGI lifespan 协议,TestClient 进入/退出上下文时派发 startup/shutdown。
- 测试中真实启动外部依赖(DB/Redis)会拖慢用例,通常用覆盖依赖替代。
原理流程
TestClient(app)进入with块,触发 lifespan 启动段。- 应用资源初始化完成,请求正常处理。
- 退出
with块,触发关闭段释放资源。 - 不使用上下文管理器时,需按所用版本确认 lifespan 是否执行。
代码或图示
def test_with_lifespan():
with TestClient(app) as client:
resp = client.get("/items")
assert resp.status_code == 200
# 退出 with 后 lifespan 关闭段执行
常见误区
- 测试依赖 lifespan 建池,却没进
with:资源未初始化,用例报连接错误。 - 测试里真实启动外部中间件:套件变慢且不稳定,应覆盖为测试替身。
追问
- 怎么单独测 lifespan 逻辑?答:直接调用上下文管理器函数,断言启动后状态存在、关闭后资源释放。
- 跳过 lifespan 有什么风险?答:依赖启动段初始化的客户端/池在测试中不存在,需由夹具补齐。
04.7.15.5-008 如何测试 WebSocket 端点?
一句话结论
TestClient 提供 client.websocket_connect("/ws") 上下文管理器,连接后 send_json/receive_json 收发消息,断言消息内容与断开行为;鉴权握手可在连接 URL 带测试凭证,异常断连用 pytest.raises(WebSocketDisconnect) 捕获。
概念解释
- WebSocket 测试在内存 ASGI 内完成,不需要真实 WS 服务器。
- 连接登记/广播逻辑可用多连接夹具覆盖跨连接推送。
原理流程
- 用
websocket_connect建立测试连接。 - 发送消息,等待并接收广播/回显。
- 断言消息字段、房间归属与错误帧。
- 退出管理器触发关闭与清理逻辑。
代码或图示
def test_ws_echo():
with client.websocket_connect("/ws/room1") as ws:
ws.send_json({"msg": "hello"})
data = ws.receive_json()
assert data["echo"] == "hello"
常见误区
- 只测单连接回显,不测多连接广播:房间推送逻辑未覆盖。
- 握手鉴权没在测试里绕过/模拟:连接直接被 401 拒绝。
追问
- 怎么测试断连清理?答:退出或主动关闭连接后,断言登记表中连接已移除、订阅已取消。
- 心跳超时怎么在测试中模拟?答:测试环境缩短心跳间隔,或直接调用清理函数断言资源释放。
04.7.15.5-009 如何测试异常处理器与错误响应格式?
一句话结论
直接请求触发错误分支,断言状态码、错误体字段结构与错误码;覆盖 HTTPException、RequestValidationError 与业务异常处理器。统一错误格式测试要固定字段名与类型,防止后续改动破坏对外契约。
概念解释
- 处理器把异常转成统一 JSON,测试验证转换结果而非内部异常类型。
- 校验失败场景用错误请求体触发 422,断言字段问题列表。
原理流程
- 构造触发异常的请求(缺字段、越权、不存在资源)。
- 客户端收到处理器生成的响应。
- 断言状态码、错误码、消息与请求 ID 字段。
- 对比错误模型 schema,确保文档与响应一致。
代码或图示
def test_not_found_format():
resp = client.get("/orders/99999")
assert resp.status_code == 404
body = resp.json()
assert body["code"] == "ORDER_NOT_FOUND"
assert "message" in body
def test_validation_error():
resp = client.post("/items", json={"price": -1})
assert resp.status_code == 422
常见误区
- 只断言状态码不断言错误体:格式被改坏时测试仍通过。
- 测试依赖错误消息中文文案:文案调整导致用例脆弱,应断言稳定错误码。
追问
- 500 兜底处理器怎么测?答:注入抛未捕获异常的路由/依赖,断言返回通用 500 响应且不泄露堆栈。
- 异常处理器里的日志怎么验证?答:捕获日志记录或断言审计事件写入,不断言日志字符串。
04.7.15.5-010 测试中覆盖认证依赖的最佳实践?
一句话结论
用 dependency_overrides 把认证依赖替换成返回测试用户的实现,按用例构造普通用户/管理员/禁用用户;需要测真实鉴权链路时保留原依赖并签发测试 token。覆盖保持与生产相同的依赖层级,避免测试绕过真实授权代码。
概念解释
- 单元级测试替换用户加载;契约/集成测试走真实校验配合测试凭证。
- 不同角色用夹具参数化,批量覆盖权限分支。
原理流程
- 定义可切换的测试用户依赖。
- 夹具按角色返回对应用户对象。
- 覆盖表注入替换依赖。
- 用例断言角色对应的访问结果。
代码或图示
def override_user(user: User | None = None):
async def _dep():
return user
return _dep
app.dependency_overrides[get_current_user] = override_user(User(id=1, roles=["admin"]))
常见误区
- 所有测试都 mock 掉认证:真实 token 校验与授权规则零覆盖。
- 替换后用户对象缺少真实模型字段:下游业务取字段报错。
追问
- 怎么测未认证场景?答:覆盖依赖返回
None或抛 401,或不覆盖并请求无凭证接口。 - 权限矩阵怎么批量测?答:参数化角色 × 接口 × 期望状态码,遍历授权组合。
04.7.15.5-011 异步测试用 pytest-asyncio 怎么配置?
一句话结论
安装 pytest-asyncio,用 @pytest.mark.asyncio 标记异步测试与夹具;配置循环作用域(function/module/session)与模式(strict 自动收集按版本配置)。异步夹具用 async def 并 yield,测试内 await 异步客户端与会话。
概念解释
- 插件负责为每个异步用例创建/管理事件循环。
- 循环作用域影响夹具复用度:function 最隔离,session 共享程度最高。
原理流程
- 测试文件导入 pytest 与异步客户端。
- 标记异步测试函数,定义 async fixture。
- 插件在循环内执行用例,await 所有异步调用。
- 结束后按作用域清理夹具与循环。
代码或图示
@pytest.fixture
async def db():
session = await make_test_session()
yield session
await session.close()
@pytest.mark.asyncio
async def test_async_flow(db):
async with AsyncClient(transport=ASGITransport(app=app)) as client:
resp = await client.get("/items")
assert resp.status_code == 200
常见误区
- 异步夹具不加标记/插件配置:被当同步函数执行,协程不运行。
- 循环作用域与夹具生命周期不匹配:跨用例复用已关闭的会话。
追问
- strict 模式下怎么收集异步用例?答:显式标记
@pytest.mark.asyncio,按插件版本配置 mode(待确认:验证点:所用 pytest-asyncio 版本的默认模式与配置键)。 - 同步 TestClient 与异步用例能混用吗?答:同一用例内不要混;套件可分文件使用不同风格。
04.7.15.5-012 测试夹具作用域与数据清理策略怎么选?
一句话结论
夹具作用域按复用需求选:session/module 级建库连接与客户端,function 级造业务数据与会话;清理与创建对称(开事务/关事务、建实例/销毁实例)。数据清理优先自动隔离(回滚/重建),不依赖人工在测试末尾删除。
概念解释
- 高复用夹具减少重复初始化成本;低作用域夹具保证用例隔离。
- 夹具依赖图按作用域顺序初始化,逆序销毁。
原理流程
- 识别资源类别:连接/客户端高复用,业务数据每用例独立。
- 连接类夹具用 module/session 作用域。
- 数据类夹具 function 作用域,结束回滚或清理。
- 销毁逻辑写在 fixture yield 之后。
代码或图示
@pytest.fixture(scope="session")
def engine():
e = create_engine(TEST_DB_URL)
yield e
e.dispose()
@pytest.fixture
def session(engine):
s = Session(bind=engine)
yield s
s.rollback()
s.close()
常见误区
- 业务数据夹具用 session 作用域:用例间数据互相污染。
- 只在测试开头造数据,结束不清理:后续用例顺序依赖。
追问
- 全局基线数据怎么准备?答:session 夹具在套件开始插入只读基线,用例不修改它。
- 夹具间能传值吗?答:通过参数声明依赖,pytest 按注入传递。
04.7.15.5-013 响应模型序列化为什么是性能热点?
一句话结论
响应模型要遍历返回对象、按字段校验/过滤、再编码 JSON;大列表时字段遍历与编码随数据量线性增长,常成为高 QPS 接口的 CPU 热点。优化方向:减少模型嵌套、用更高效编码路径、批量场景流式分页,而不是先怀疑数据库。
概念解释
- 热点两段:Pydantic 模型构造/校验,JSON 序列化编码。
- 响应模型还会做字段排除与类型转换,比裸 dict 多一层成本。
原理流程
- 端点返回业务对象/列表。
- 框架按
response_model构造模型实例,校验字段。 - 模型 dump 为 dict,JSON 编码器转字节。
- 大列表时遍历与编码在单请求内重复放大。
代码或图示
# 大列表响应:模型遍历 + JSON 编码成本随行数增长
@app.get("/items")
def list_items() -> list[ItemOut]:
return item_repo.list_all()
常见误区
- 只优化 SQL 不看序列化:接口慢在模型与编码段,加索引无效。
- 响应模型嵌套过深:每层都重复遍历转换,成本叠加。
追问
- 怎么确认序列化占比?答:profile 看
model_validate/model_dump/json.dumps采样占比,对比裸 dict 响应耗时。 - 能跳过响应模型吗?答:可直接返回
Response/dict 手写编码,但失去输出校验与字段过滤。
04.7.15.5-014 Pydantic 模型构造与校验的 CPU 成本在哪?
一句话结论
成本包括字段类型检查、约束校验(长度/范围/正则)、默认值与别名处理、嵌套模型递归构造;Pydantic v2 经 Rust 核心提速,但复杂模型与大 payload 仍有可观开销。输入模型校验在请求入口,输出模型构造在响应出口,两侧都要关注。
概念解释
- v2 与 v1 内部实现不同,但“遍历字段 + 校验约束”的基本成本结构一致。
- 校验越严(正则、嵌套、自定义校验器)单次成本越高。
原理流程
- 请求体进入,构造输入模型并逐字段校验。
- 嵌套字段递归构造子模型。
- 响应出口构造输出模型,过滤字段后 dump。
- 高 QPS 下单次校验成本被放大成 CPU 占用。
代码或图示
class ItemOut(BaseModel):
name: str = Field(min_length=1, max_length=50)
price: float = Field(gt=0)
tags: list[str]
常见误区
- 大列表每项都套深模型:构造成本随条目数倍增。
- 不必要的正则/范围校验留在出口模型:响应路径白付校验成本。
追问
- v2 怎么进一步提速?答:利用模型复用、避免重复构造、合理使用
model_config,热点处对比裸结构序列化。 - 校验失败的请求也付成本吗?答:是,入口校验在报错前已遍历字段。
04.7.15.5-015 JSON 编码路径(内置 json / orjson / ujson)对比?
一句话结论
Python 内置 json 标准、跨版本稳定但纯 Python 实现;orjson(Rust)速度快、输出紧凑,常见于高吞吐接口;ujson 也是 C 扩展,历史上边界行为差异需注意。选型先 profile 确认编码是瓶颈,再引入替代编码器,注意日期/枚举/自定义类型的序列化兼容。
概念解释
- FastAPI/Starlette 默认走标准 JSON 响应编码;替换需在响应层配置或自定义 Response。
- 第三方编码器对非内置类型(datetime、UUID、Decimal、枚举)支持要逐一验证。
原理流程
- 定位 JSON 编码在 profile 中的占比。
- 评估替代库对项目数据类型的兼容性。
- 接入自定义 JSON 响应/编码器,跑回归对比输出。
- 压测验证吞吐与延迟改善,观察兼容性问题。
代码或图示
# 自定义 JSONResponse 示例(orjson 接入方式按框架版本核对)
import orjson
class ORJSONResponse(Response):
media_type = "application/json"
def render(self, content) -> bytes:
return orjson.dumps(content, default=str)
常见误区
- 没测就换编码器:日期/Decimal 序列化行为差异导致线上错误。
- 把编码优化当万能:瓶颈在 DB 或序列化模型构造时,换编码器收益有限。
追问
- orjson 输出日期是什么格式?答:默认 ISO 8601 bytes,复杂类型需
default回调处理(按版本核对)。 - 生产引入新依赖的成本?答:增加维护面,需锁定版本、验证安全补丁与平台 wheel 支持。 '@
04.7.15.5-016 大列表响应的内存与序列化怎么优化?
一句话结论
大列表问题是一次性载入全量数据、构造全量模型再编码,内存峰值与首字节延迟都高;优化:分页/游标分批、流式响应逐块产出、精简输出字段、避免嵌套模型冗余,必要时用更高效编码路径。导出类接口优先流式分页,不返回全量数组。
概念解释
- 内存峰值 = 原始数据 + 模型对象 + 编码缓冲区,三者同时驻留。
- 分页控制单请求数据量,流式让内存随产出回收。
原理流程
- 识别大列表接口的数据量级与字段宽度。
- 改分页/游标查询,限制单页大小。
- 响应按批次序列化输出(StreamingResponse/NDJSON)。
- 裁剪非必要字段,降低每条记录宽度。
代码或图示
@app.get("/export")
async def export():
async def gen():
async for batch in query_batches(size=500):
yield orjson.dumps([b.model_dump() for b in batch]).decode() + "\n"
return StreamingResponse(gen(), media_type="application/x-ndjson")
常见误区
- 用分页但前端一次拉完所有页:服务端压力只是转移到客户端。
- 导出接口复用详情响应模型:冗余字段放大数据量。
追问
- 游标分页与页码分页怎么选?答:大数据量/跳页少用游标(稳定、深翻页快);页码分页适合浅翻页与跳转。
- 大列表能靠加 worker 解决吗?答:横向扩容分摊单实例压力,但单请求内存峰值问题仍在,需先优化数据量。
04.7.15.5-017 怎么定位性能瓶颈(profile 工具与指标)?
一句话结论
先分阶段计时(DB、下游调用、模型构造、序列化、编码),再用 cProfile/py-spy 采样火焰图定位热点;线上看指标(QPS、P99、CPU、内存、连接池等待、下游延迟),离线用压测复现。不要凭感觉猜瓶颈,按数据定位到函数与阶段。
概念解释
- 本地 profile 看函数采样占比;线上指标看资源水位与尾延迟。
- 慢接口先区分是等待(IO)还是计算(CPU)。
原理流程
- 在关键阶段打点计时,拆分 DB/下游/序列化/编码耗时。
- 用采样工具(py-spy dump/record)或 cProfile 生成火焰图。
- 对照指标确认是 CPU 饱和、连接池排队还是下游慢。
- 优化后复测同口径对比,确认瓶颈转移或消除。
代码或图示
import time
@app.get("/item/{iid}")
async def item(iid: int):
t0 = time.perf_counter()
row = await repo.get(iid)
t1 = time.perf_counter()
out = ItemOut.model_validate(row).model_dump()
t2 = time.perf_counter()
logger.info("stage", db=t1 - t0, serialize=t2 - t1)
return out
常见误区
- 只看平均延迟:P99 尾部问题被均值掩盖。
- 优化没复测:瓶颈是否消除、有无转移无法确认。
追问
- py-spy 能抓线上进程吗?答:可附加采样生成火焰图,对进程影响较小(按部署权限与环境确认)。
- 怎么区分 IO 等待与 CPU 计算?答:看阶段耗时与 CPU 占用;等待高 CPU 低是下游/DB,计算高 CPU 高是本地处理。
04.7.15.5-018 locust 压测怎么设计场景与口径?
一句话结论
locust 用 Python 定义用户行为(请求序列、思考时间、任务权重),逐步加压观测吞吐与延迟;场景覆盖核心读接口、写接口与混合比例,口径固定并发数、爬升曲线、持续时长与断言项。压测前预热,数据量与生产接近,记录服务端资源指标一起分析。
概念解释
- 压测目标:找容量拐点、验证延迟 SLA、暴露资源瓶颈,不是单纯跑高 QPS。
- 用户模拟要贴近真实行为:读多写少、页面跳转顺序、参数分布。
原理流程
- 编写任务:GET/POST 序列、参数生成、成功断言。
- 配置并发用户数、爬升速率与持续时间。
- 执行压测,采集 RPS、响应时间分布、失败率。
- 同步记录服务端 CPU/内存/连接池/下游指标,定位瓶颈层。
代码或图示
from locust import HttpUser, task, between
class ApiUser(HttpUser):
wait_time = between(1, 3)
@task(3)
def list_items(self):
self.client.get("/items")
@task(1)
def create_item(self):
self.client.post("/items", json={"name": "压测商品", "price": 9.9})
常见误区
- 压测数据全是同一批重复数据:缓存命中与生产不符,结果偏乐观。
- 只看总 RPS 不看 P99 与错误率:容量拐点被高吞吐掩盖。
追问
- 分布式压测怎么跑?答:locust worker 节点分摊压测压力,master 汇总指标。
- 压测环境要连真实下游吗?答:核心依赖可用测试替身/影子流量,否则下游成为瓶颈干扰本服务判断。
04.7.15.5-019 wrk/ab 压测口径与指标怎么解读?
一句话结论
wrk 支持多线程与 Lua 脚本,输出平均延迟、标准差、吞吐与错误数;ab(Apache bench)单并发模型偏简单,适合快速冒烟。口径:固定连接数/线程数、请求时长或总请求数,关注延迟分位(wrk 需脚本扩展)、吞吐、错误率,而不是只看每秒请求数。
概念解释
- 压测工具自身能力是上限:客户端打不满时测得的是工具瓶颈而非服务瓶颈。
- 长连接/短连接、HTTP 版本差异会影响结果。
原理流程
- 选择工具与并发模型,配置连接数与持续时间。
- 执行压测,记录 RPS、延迟分布、失败连接数。
- 对照服务端资源水位判断瓶颈层。
- 调整并发找到延迟开始劣化的吞吐拐点。
代码或图示
wrk -t4 -c64 -d30s http://127.0.0.1:8000/items
ab -n 10000 -c 50 http://127.0.0.1:8000/items
常见误区
- 在同一台机器压测服务:客户端与服务争抢 CPU,结果失真。
- ab 高并发下结果当作容量结论:ab 并发模型简单,需 wrk/分布式工具复核。
追问
- 延迟标准差大说明什么?答:请求分布离散,存在排队或抖动,需看分位数而非均值。
- 怎么确认压测打满服务?答:服务 CPU/连接池接近饱和,再加并发吞吐不升、延迟上涨。
04.7.15.5-020 压测时要观测哪些服务端指标?
一句话结论
核心指标:QPS/吞吐、延迟分位(P50/P95/P99)、错误率、CPU 与内存占用、事件循环延迟、线程池队列、在途请求数、下游/DB 连接池等待与耗时、网络收发。指标按实例聚合,结合压测曲线观察拐点与资源瓶颈。
概念解释
- 应用指标反映处理能力,系统指标反映资源约束,下游指标反映依赖瓶颈。
- 单一指标不足以定位,要交叉对照。
原理流程
- 压测前确认基线:空闲水位与单次正常耗时。
- 加压过程采集应用与系统指标。
- 对比延迟上升段对应的资源饱和点。
- 记录容量拐点:吞吐上限、P99 达标最大并发、瓶颈层。
代码或图示
应用:RPS、P95/P99、错误率、在途请求、loop lag、线程池排队
系统:CPU、内存、磁盘 IO、网络
依赖:DB 连接池占用/等待、下游 RTT 与错误率
常见误区
- 只盯应用 QPS:CPU 已饱和或 DB 排队未被发现。
- 压测不记录下游指标:瓶颈在依赖却误调本服务。
追问
- 在途请求数过高说明什么?答:处理速度跟不上到达速率,请求排队堆积。
- 内存持续上涨怎么看?答:区分缓存增长、连接持有与泄漏,压测结束后观察是否回落。
04.7.15.5-021 GIL 对异步服务吞吐有什么影响?
一句话结论
GIL 保证同一进程同一时刻只有一个线程执行 Python 字节码;异步协程在等待 IO 时挂起让出循环,但 CPU 计算仍受 GIL 串行化。IO 密集异步服务受益于协程并发,CPU 密集部分多线程帮助有限,需进程扩容或卸载任务。
概念解释
- GIL 不影响 IO 等待阶段的并发:等待时线程释放 GIL。
- 多进程绕过 GIL 获得并行,代价是内存与连接按进程复制。
原理流程
- 协程等待 IO,释放循环与 GIL 供其他任务运行。
- 本地计算段持有 GIL,线程间串行执行字节码。
- CPU 密集任务多线程并行收益受限。
- 通过多 worker 进程分摊计算,或把重计算移出进程。
代码或图示
IO 等待:协程并发,GIL 释放,受益明显
CPU 计算:GIL 串行,线程并行有限,进程扩容才并行
常见误区
- 以为异步框架自动绕过 GIL:协程并发不是 CPU 并行。
- 用多线程跑批量哈希/计算:GIL 下吞吐提升有限。
追问
- free-threading 对 GIL 的改变?答:Python 3.13+ 无 GIL 构建实验性支持,按部署版本评估(待确认:验证点:所用 Python 版本与构建是否启用 free-threading)。
- 异步服务为什么仍建议多进程?答:利用多核并行,分摊单进程 GIL 与循环延迟。
04.7.15.5-022 异步 ASGI 服务的 worker 数量怎么配置?
一句话结论
异步 ASGI 每 worker 一个事件循环,worker 数接近 CPU 核数起步,按压测调整;过多 worker 增加上下文切换、内存与连接复制,过少浪费多核。容器内按 CPU limit 折算可用核数,再结合内存、DB 连接上限与下游容量确定。
概念解释
- 异步单 worker 可承载大量 IO 并发,不像同步服务靠线程数堆吞吐。
- 总 DB 连接 = worker 数 × 每进程池大小,不能超过数据库上限。
原理流程
- 确认部署环境可用 CPU 核数(容器按 limit)。
- 以核数附近为起点配置 worker。
- 压测观测 CPU 利用率、循环延迟与延迟分位。
- 结合内存占用与下游连接上限微调,记录容量基线。
代码或图示
# 4 核起步示例,压测后调整
uvicorn main:app --workers 4 --host 0.0.0.0 --port 8000
常见误区
- 照搬同步 WSGI 的
2n+1:异步模型不需要那么多进程。 - worker 数受限于 DB 连接仍盲目加大:连接打满后请求排队失败。
追问
- worker 越多吞吐越高吗?答:到 CPU/连接瓶颈后不再升,反而切换开销与内存上升。
- 单 worker 事件循环延迟高怎么办?答:先排查阻塞调用,再考虑扩容进程分摊。
04.7.15.5-023 uvicorn 部署参数有哪些关键项?
一句话结论
关键参数:--workers 进程数、--host/--port 监听地址、--loop 事件循环(auto/asyncio/uvloop)、--http 协议实现(auto/h11/httptools)、--timeout-keep-alive 空闲连接保持、--timeout-graceful-shutdown 优雅停机等待、--proxy-headers 信任代理头。按部署环境选择,生产关闭调试与重载。
概念解释
- loop 与 http 实现影响 IO 调度与协议解析性能。
- 代理头开启后才会从
X-Forwarded-For/Proto/Host读取真实信息。
原理流程
- 配置监听地址端口与 worker 数。
- 选择循环与 HTTP 实现,按平台兼容性确认。
- 设置 keep-alive 与优雅停机超时。
- 反代部署开启
--proxy-headers,关闭 reload 与 debug。
代码或图示
uvicorn main:app \
--workers 4 \
--host 0.0.0.0 --port 8000 \
--proxy-headers --forwarded-allow-ips="10.0.0.0/8" \
--timeout-keep-alive 5 \
--timeout-graceful-shutdown 30
常见误区
- 生产开
--reload:文件监听与额外进程开销,不适合长期运行。 - 信任任意来源代理头:应限制
forwarded-allow-ips为可信代理网段。
追问
--loop uvloop什么环境可用?答:Linux 等支持平台安装 uvloop 后启用;Windows 与兼容库需核对支持矩阵。- keep-alive 设多长?答:短连接多时复用连接,过长占用空闲连接;按代理与客户端习惯配置。
04.7.15.5-024 gunicorn + uvicorn worker 模式怎么配?
一句话结论
gunicorn 作为进程管理器,worker 类用 uvicorn.workers.UvicornWorker,每个 worker 内跑 ASGI 事件循环;适合已有 gunicorn 体系、需多进程管理与优雅重启的部署。worker 数与超时按异步模型配置,同步 worker 类不适用于 FastAPI 异步应用。
概念解释
- gunicorn 负责进程 fork、监控与重启;UvicornWorker 内部启动 uvicorn 协议层。
- 直接 uvicorn 多 worker 也可,gunicorn 模式侧重进程管理生态。
原理流程
- 安装 gunicorn 与 uvicorn,指定 worker 类。
- 配置 worker 数、绑定地址、超时与日志。
- gunicorn fork 进程,各 worker 启动 ASGI 循环。
- 信号触发优雅停机,worker 排空在途请求后退出。
代码或图示
gunicorn main:app \
--worker-class uvicorn.workers.UvicornWorker \
--workers 4 \
--bind 0.0.0.0:8000 \
--timeout 30 \
--graceful-timeout 30
常见误区
- 用同步 gthread/sync worker 跑异步应用:协程无法正确调度。
- gunicorn
--timeout过短:长请求被误杀;过长则故障恢复慢。
追问
- 直接 uvicorn 与 gunicorn 模式怎么选?答:单组件 uvicorn 简单;需要进程监控、滚动重启与既有 gunicorn 配置时用 gunicorn。
- worker 启动慢怎么处理?答:lifespan 初始化轻量化,预热异步化,避免启动阶段阻塞 worker fork。
04.7.15.5-025 容器化部署有哪些要点?
一句话结论
镜像基于精简基础镜像,只装运行依赖;进程以非 root 用户运行,只读文件系统,配置走环境变量/挂载密钥;设置 CPU/内存 requests 与 limits,健康检查接入编排平台;多实例无状态,会话与状态放外部存储。镜像分层缓存依赖层,减小体积与构建时间。
概念解释
- 容器内应用不感知宿主路径,脚本与配置用相对/环境变量定位。
- 资源 limit 是 worker 数与内存规划的依据。
原理流程
- 基础镜像选精简运行时,安装系统依赖与 Python 包。
- 复制代码,切换非 root 用户。
- 注入环境配置,暴露端口与健康检查。
- 编排层配置资源限制、副本数与探针。
代码或图示
FROM python:3.12-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY . .
USER app
EXPOSE 8000
CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]
常见误区
- 容器内跑开发依赖与源码挂载:镜像体积大、行为与生产不一致。
- 应用写本地磁盘当持久存储:容器重建后数据丢失,应挂外部存储。
追问
- 镜像怎么瘦身?答:合并层、清除缓存、用 slim/distroless 基础镜像、构建依赖分阶段安装。
- 容器内存 limit 怎么定?答:按单 worker 内存 × 副本数压测值,留缓冲余量。
04.7.15.5-026 健康检查端点与存活/就绪探针有什么区别?
一句话结论
存活探针(liveness)判断进程是否卡死/需重启;就绪探针(readiness)判断能否接流量(依赖可用、初始化完成)。FastAPI 提供轻量 /health//ready 端点:存活只返回进程在线,就绪检查 DB/Redis/下游连通后再决定是否摘除流量。
概念解释
- 存活失败触发重启;就绪失败只从负载均衡摘除,不重启进程。
- 探针端点不应做重依赖长查询,避免误摘。
原理流程
- 编排平台周期调用 liveness 端点,失败重启容器。
- 调用 readiness 端点检查依赖连通性。
- 依赖未就绪时摘出流量,恢复后重新接入。
- 探针结果独立于业务接口状态。
代码或图示
@app.get("/health", include_in_schema=False)
def health():
return {"status": "ok"}
@app.get("/ready", include_in_schema=False)
async def ready():
await check_db()
await check_redis()
return {"status": "ready"}
常见误区
- 存活探针也检查外部依赖:依赖抖动导致进程被反复重启。
- 就绪探针做重查询:探活自身成为压力点。
追问
- 启动慢的服务怎么配探针?答:用启动探针(startup probe)给初始化留窗口,再挂存活/就绪。
- 探针端点要鉴权吗?答:通常内网放行,可校验内网来源,不暴露内部细节。
04.7.15.5-027 优雅停机流程与超时怎么配置?
一句话结论
收到停机信号后:停止接收新请求 → 排空在途请求(等待完成或超时)→ 执行 lifespan 关闭段释放连接池/客户端 → 进程退出。超时配置覆盖在途请求等待与资源关闭;超过窗口强制退出,避免卡死发布流程。
概念解释
- 优雅停机减少中断在途业务,避免连接与事务被硬切断。
- 排队等待、下游响应、资源关闭各段都要有超时上限。
原理流程
- 编排/服务器收到 SIGTERM,停止接受新连接。
- 等待在途请求在宽限窗口内完成。
- lifespan 关闭段逆序释放池、客户端与订阅。
- 超时未排空则强制退出,记录未完成请求。
代码或图示
uvicorn main:app --timeout-graceful-shutdown 30
常见误区
- 关闭段阻塞在无超时的下游调用:优雅停机超时,进程被强杀。
- 不等待在途任务:发布瞬间中断用户请求与事务。
追问
- 后台任务停机时怎么办?答:任务队列消费先停拉取,在途任务完成后退出;无法完成的靠重试恢复。
- 滚动发布怎么配合?答:旧实例摘流量后排空,新实例就绪后再接入,逐步替换。
04.7.15.5-028 反代后 root_path 与代理头怎么配?
一句话结论
应用挂在反代子路径下时,设置 root_path(或代理头)让生成的文档 URL 与路由前缀正确;反代转发 X-Forwarded-For、X-Forwarded-Proto、X-Forwarded-Host,应用开启 proxy-headers 并限制可信代理网段。否则客户端拿到错误的回调地址与协议判断。
概念解释
root_path是应用对外可见的前缀,不影响内部路由匹配。- 代理头必须来自可信代理,直接暴露公网时不能信任客户端伪造值。
原理流程
- 反代按域名/路径转发,附加转发头。
- 应用配置 root_path 与可信代理列表。
- 生成链接、回调与 OpenAPI 地址时带上前缀与协议。
- 日志按转发头记录真实客户端 IP。
代码或图示
app = FastAPI(root_path="/api")
# uvicorn
# --proxy-headers --forwarded-allow-ips="10.0.0.0/8"
常见误区
- 子路径部署不设 root_path:Swagger 与回调地址 404。
- 应用信任公网传入的转发头:客户端可伪造 IP 与协议。
追问
root_path与路由前缀重复怎么办?答:内部路由不含对外前缀,root_path 只做外部映射,不要双重拼接。- 怎么验证代理头生效?答:日志/接口返回的客户端 IP、协议与外部访问一致。
04.7.15.5-029 Nginx 反代 FastAPI 的关键配置?
一句话结论
关键配置:proxy_pass 指向应用,转发代理头(Host、X-Forwarded-*),设置 proxy_read_timeout 适配长接口,关闭/按需调整缓冲以适配 SSE/WebSocket,上传大小限制 client_max_body_size,连接 keep-alive 到后端。WebSocket 需升级头转发;静态资源可由 Nginx 直接服务。
概念解释
- 反代层承担 TLS 终止、静态资源、连接复用与限流入口。
- 长连接类接口(SSE/WS)需关闭缓冲并转发 Upgrade 头。
原理流程
- Nginx 监听 443,按 location 反代到 uvicorn 实例。
- 转发 Host 与 X-Forwarded 头,设置超时与体限制。
- 长连接接口配置缓冲与升级支持。
- 后端连接 keep-alive 复用,降低握手开销。
代码或图示
location /api/ {
proxy_pass http://127.0.0.1:8000;
proxy_set_header Host $host;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_read_timeout 60s;
client_max_body_size 20m;
}
常见误区
- 不转发
X-Forwarded-Proto:应用判断为 HTTP,生成错误回调链接。 - SSE 走默认缓冲:推送被攒批,实时性丢失。
追问
- WebSocket 在 Nginx 怎么配?答:转发
Upgrade/Connection头,按连接类型设置超时。 - 后端多实例怎么做负载均衡?答:Nginx upstream 配多个实例,按策略轮询/最少连接。
04.7.15.5-030 访问日志结构与请求 ID 关联怎么做?
一句话结论
访问日志记录方法、路径、状态码、耗时、客户端、请求 ID、响应大小;请求 ID 在入口生成/透传,贯穿中间件、依赖、下游调用与错误追踪。结构化日志(JSON)便于检索聚合,敏感字段脱敏,不记录完整 token 与请求体。
概念解释
- 日志按请求关联:一条请求的应用日志、下游日志、错误追踪用同一 ID。
- 访问日志与业务审计日志分层存储。
原理流程
- 中间件解析或生成请求 ID,写入上下文变量。
- 记录请求开始,处理完成后记录状态码与耗时。
- 下游调用头透传请求 ID,串联跨服务日志。
- 日志聚合系统按 ID 检索整条链路。
代码或图示
@app.middleware("http")
async def access_log(request: Request, call_next):
rid = request.headers.get("x-request-id") or uuid.uuid4().hex
t0 = time.perf_counter()
resp = await call_next(request)
logger.info("access", extra={
"request_id": rid, "method": request.method,
"path": request.url.path, "status": resp.status_code,
"duration_ms": (time.perf_counter() - t0) * 1000,
})
return resp
常见误区
- 日志打完整请求体与 token:隐私与泄露风险。
- 耗时只记业务段不含排队:无法反映端到端延迟。
追问
- 日志格式选文本还是 JSON?答:集中采集分析用 JSON;本地开发可读文本。
- 慢请求怎么单独标记?答:耗时超阈值打 warning 级别并带请求 ID,便于告警检索。
04.7.15.5-031 prometheus-fastapi-instrumentator 怎么接入指标?
一句话结论
该库包装 FastAPI 应用,自动采集请求数、延迟、状态码等 Prometheus 指标,暴露 /metrics 端点供抓取;可自定义指标(业务计数、下游耗时)与标签。接入在应用构造后注册,指标命名与标签按规范规划,避免高基数标签(如用户 ID、订单 ID)。
概念解释
- 指标分计数器(累计请求)、直方图(延迟分布)、 gauge(在途/水位)。
- 高基数标签会撑爆时序数据库,标签维度只取稳定枚举。
原理流程
- 安装库并实例化 Instrumentator。
- 注册中间件/路由,暴露 metrics 端点。
- 自动采集 HTTP 指标,按需添加自定义业务指标。
- Prometheus 周期抓取,Grafana 按接口/状态码聚合看板。
代码或图示
from prometheus_fastapi_instrumentator import Instrumentator
Instrumentator().instrument(app).expose(app)
常见误区
- 标签放请求 ID/用户 ID:基数爆炸,指标存储成本失控。
- 只看请求总量不看延迟分位与错误率:容量与质量问题被掩盖。
追问
/metrics要鉴权吗?答:内网抓取可限制来源网段,不暴露内部业务细节。- 自定义指标怎么加?答:用 Prometheus 客户端注册 Counter/Histogram,在业务代码埋点。
04.7.15.5-032 关键业务指标有哪些,怎么设阈值?
一句话结论
核心:QPS/吞吐、延迟分位(P50/P95/P99)、错误率(4xx/5xx 拆分)、在途请求数、依赖成功率与耗时、资源水位。阈值按 SLA 设定告警,例如 P99 超阈值、5xx 率上升、在途堆积、连接池等待增长;指标要按接口与实例拆分,避免全局平均掩盖局部问题。
概念解释
- 延迟看尾部分位,错误率按状态码与错误类型拆分。
- 依赖指标反映下游瓶颈,应用指标反映本地处理能力。
原理流程
- 定义各接口 SLA:延迟目标、错误率上限。
- 采集应用、系统、依赖三层指标。
- 配置告警规则:分位延迟、错误率、资源饱和、连接等待。
- 值班看板按接口、实例、下游下钻定位。
代码或图示
请求:rate(http_requests_total[5m])
延迟:histogram_quantile(0.99, ...)
错误:rate(http_requests_total{status=~"5.."}[5m])
水位:在途请求、连接池占用/等待、CPU/内存
常见误区
- 告警只看 CPU:内存泄漏、连接池耗尽、下游慢都可能不体现在 CPU。
- 阈值拍脑袋:应基于压测基线与历史波动设定,避免告警风暴或漏报。
追问
- 4xx 要告警吗?答:4xx 多为客户端错误,异常突增(如批量 401/429)值得关注;5xx 是服务端质量红线。
- 指标保留多久?答:按监控系统容量与合规要求,原始明细短保留,聚合长保留。
04.7.15.5-033 OpenTelemetry 链路追踪怎么接入?
一句话结论
接入 OTel SDK:配置 TracerProvider 导出 trace(OTLP/Jaeger/Tempo 等),用 FastAPI/ASGI 中间件自动为请求建 Span,下游 HTTP/DB 客户端 instrumentation 补全子 Span;trace ID 与日志关联,跨服务串联整条调用链。
概念解释
- Span 记录一次操作:名称、耗时、属性、事件、状态。
- 自动 instrumentation 减少手写埋点,自定义 Span 补充业务步骤。
原理流程
- 初始化 TracerProvider 与导出器,配置服务名与环境属性。
- 注册 ASGI/FastAPI 追踪中间件,请求进入创建根 Span。
- 下游调用经 instrumentation 生成子 Span,上下文随请求传播。
- 日志注入 trace ID,链路在追踪系统按 ID 检索。
代码或图示
from opentelemetry.instrumentation.fastapi import FastAPIInstrumentor
FastAPIInstrumentor.instrument_app(app)
常见误区
- 只接入应用不接下游 instrumentation:链路在跨服务/DB 处断裂。
- Span 属性塞高基数数据:追踪存储膨胀,检索变慢。
追问
- trace 采样怎么配?答:高流量按比例采样,错误与慢请求优先保留;生产不全量采集。
- 日志怎么关联 trace?答:日志格式化器从 OTel 上下文取 trace_id/span_id 写入字段。
04.7.15.5-034 跨服务 trace 上下文怎么传播?
一句话结论
trace 上下文(trace ID、span ID、采样标志)通过 W3C traceparent 头在 HTTP 调用间传播;服务端从请求头提取上下文创建子 Span,下游客户端调用时注入头。消息队列按消息属性传递上下文,保证异步链路不断裂。
概念解释
- 传播规范统一跨语言/跨框架的上下文格式。
- 上下文提取与注入由 instrumentation 自动完成,手动调用需显式处理。
原理流程
- 入口服务创建根 Span,生成 trace 上下文。
- 出站调用注入
traceparent等传播头。 - 下游服务提取上下文,挂接为子 Span。
- 异步队列消息携带上下文属性,消费端恢复链路。
代码或图示
Service A → traceparent: 00-<trace-id>-<span-id>-01
Service B 提取 → 子 Span 挂到同一 trace 下
常见误区
- 内部服务间调用不透传上下文:链路在服务边界断开,无法端到端排障。
- 上下文在异步任务中丢失:任务切换需显式传递/恢复上下文。
追问
- 消息队列怎么传 trace?答:把 traceparent 写入消息头/属性,消费端提取后创建 Span。
- 采样标志会传播吗?答:会,子 Span 继承父级采样决策,避免链路半截。
04.7.15.5-035 FastAPI 0.11x 有哪些常见弃用项与兼容注意点?
一句话结论
0.11x 持续向 Pydantic v2、Starlette 新版对齐;已知弃用方向包括旧 on_event 钩子(推荐 lifespan)、部分 v1 兼容路径与旧版参数。升级前对照发行说明核对弃用警告,在启动日志与测试中捕获 DeprecationWarning,不依赖即将移除的内部 API。
概念解释
- 框架内部实现可能调整,公开稳定 API 与内部函数要区分使用。
- 小版本升级先跑测试套件与文档生成,再灰度发布。
原理流程
- 升级前阅读版本变更与弃用列表。
- 本地启动应用,收集弃用警告与行为差异。
- 迁移受影响写法(lifespan、Pydantic v2 语法等)。
- 测试通过后灰度,观察指标与错误追踪。
代码或图示
检查项:on_event → lifespan;Pydantic v1 写法 → v2;
旧响应/依赖参数;内部函数引用;文档生成是否正常
常见误区
- 跨多个大版本直接升级:弃用累积,回归面过大。
- 忽略启动期 DeprecationWarning:移除版本到来时被迫紧急改造。
追问
- 怎么查当前版本弃用项?答:运行时警告 + 官方 changelog/迁移指南(待确认:验证点:所用 FastAPI 版本 changelog 中标记 deprecated 的具体条目)。
- 内部函数被改了怎么办?答:改用公开 API;内部实现不保证兼容。
04.7.15.5-036 Pydantic v1 迁移到 v2 有哪些注意事项?
一句话结论
v2 核心由 Rust 实现,配置与校验 API 调整:Config 类改为 model_config,校验器装饰器改为 field_validator/model_validator,部分方法名变更(dict()→model_dump()、parse_obj→model_validate)。迁移逐模型核对行为差异,注意类型严格度、默认值与序列化输出变化。
概念解释
- v2 性能更高,但个别校验规则与 v1 不完全等价。
- FastAPI 0.11x 已适配 v2,依赖库需同步升级兼容版本。
原理流程
- 升级 Pydantic 与相关库到兼容版本。
- 逐模型替换配置与校验器写法。
- 跑测试核对请求校验、响应序列化输出。
- 对比 schema 生成结果,确认文档字段一致。
代码或图示
# v1
class Model(BaseModel):
class Config:
orm_mode = True
# v2
class Model(BaseModel):
model_config = {"from_attributes": True}
常见误区
- 直接全局替换方法名而不核对语义:
model_dump与旧dict参数行为有差异。 - 忽略第三方库 v2 兼容:未升级的库可能仍按 v1 接口调用。
追问
- v2 严格度变化有哪些?答:数字/字符串 coercion、可选字段、枚举等校验规则需逐模型验证(按版本 release notes 核对)。
- 迁移期能 v1/v2 共存吗?答:同一项目内谨慎共存,依赖冲突时统一升级。
04.7.15.5-037 同步依赖阻塞事件循环的典型坑是什么?
一句话结论
在 async def 链路中通过同步依赖/工具函数调用阻塞库(同步 DB 驱动、requests、同步哈希、重计算),阻塞占住事件循环线程;即使阻塞发生在依赖层,也会卡停整个循环。判断依据:依赖是否为同步函数、体内是否有阻塞调用,必要时改异步驱动或包线程池。
概念解释
- 同步
def依赖会进线程池,不阻塞循环;问题出在异步函数体内调用同步阻塞代码。 - 阻塞点可能藏在被依赖引入的工具函数/客户端内部。
原理流程
- 请求进入异步端点,调用异步依赖。
- 依赖体内执行同步阻塞库调用。
- 循环线程被占住,其他请求与定时器排队。
- 症状:全接口延迟抬升、loop lag 增大、在途堆积。
代码或图示
# 坑:异步依赖里直接用同步驱动
async def get_user(uid: int):
return sync_session.query(User).get(uid) # 阻塞循环
# 修:异步驱动,或 run_in_threadpool 包裹
常见误区
- 只检查端点函数体,漏掉依赖与服务层阻塞调用。
- 用线程池包裹后仍在协程内持有阻塞连接:连接复用方式需一并调整。
追问
- 怎么判断依赖该不该是同步 def?答:体内全是阻塞库调用就写
def,由框架调度线程池;有 await 异步调用才写async def。 - 阻塞修复后怎么验证?答:压测观察 loop lag 与 P99 是否回落。
04.7.15.5-038 Depends 缓存导致 session 复用有什么坑?
一句话结论
同一请求内,默认缓存的依赖只执行一次,结果被下游共享;若依赖创建数据库 session 且缓存生效,多个后续依赖/端点复用同一 session,可能带来事务状态串扰、连接提前关闭或并发下状态污染。需要每处独立会话时,关闭该依赖缓存或改用独立工厂依赖。
概念解释
- 依赖缓存是一次请求内的结果复用,跨请求不共享。
- 缓存行为按依赖函数对象判定,嵌套依赖共享同一缓存结果。
原理流程
- 框架解析依赖图,检查缓存结果是否已存在。
- 命中缓存直接复用,不再执行依赖函数。
- 复用的 session 携带前序操作的事务状态。
- 多步操作共享会话导致提交/回滚边界混乱。
代码或图示
# 默认:同请求内 get_db 结果复用
async def get_db():
session = AsyncSessionFactory()
yield session
# 需要独立会话时:按依赖隔离或显式关闭缓存(按版本核对参数)
常见误区
- 以为每次注入都新建 session:缓存复用让多个步骤共用一个连接。
- 会话生命周期与请求生命周期不匹配:提前关闭后下游再用报错。
追问
- 怎么确认依赖被缓存复用?答:在依赖函数内打日志,观察一次请求内执行次数。
- 关闭缓存后要注意什么?答:重复创建连接池会话,开销上升;只在确有隔离需求时关闭。
04.7.15.5-039 生命周期资源泄漏的典型表现与排查方式?
一句话结论
泄漏表现:内存/连接数持续上涨不回落、池等待增加、文件描述符耗尽、停机时资源未释放。排查沿 lifespan 创建点 → 依赖注入 → 请求结束释放链,核对每个获取的资源是否有对应释放;压测后观察指标是否回落,对比连接/句柄计数。
概念解释
- 常见泄漏:连接未关闭、后台任务未取消、缓存无界增长、订阅未退订。
- 生命周期资源在 lifespan 创建,必须在关闭段或依赖退出段释放。
原理流程
- 监控内存、连接池占用、句柄数随请求量变化。
- 压测结束空闲观察水位是否回落。
- 对照资源获取点检查释放路径(finally/yield 退出段)。
- 修复后复测水位曲线,确认增长收敛。
代码或图示
@asynccontextmanager
async def lifespan(app: FastAPI):
client = httpx.AsyncClient()
app.state.client = client
yield
await client.aclose() # 必须对应释放
常见误区
- 只在正常路径关闭资源:异常/取消路径泄漏被忽略。
- 全局缓存只增不减:业务数据堆积被误判为内存泄漏。
追问
- 怎么看连接池泄漏?答:池占用随请求单调上升、等待获取连接的请求增多。
- 后台任务泄漏怎么查?答:在途任务数持续增长,任务完成后未被回收。
04.7.15.5-040 BackgroundTasks 有哪些注意事项?
一句话结论
BackgroundTasks 在响应返回后执行后台任务,不阻塞响应;任务随请求生命周期调度,异常需自行记录。注意:后台任务不保证重试,不能承载必须可靠完成的业务(走任务队列);响应已发出后异常无法再转成 HTTP 错误;长任务占用 worker 进程资源。
概念解释
- 后台任务在响应发送后由 ASGI 调度执行。
- 可靠性要求高的任务应投递外部队列,由独立 worker 消费与重试。
原理流程
- 端点把任务函数加入
BackgroundTasks。 - 响应体发送完成后调度执行后台任务。
- 任务内异常捕获并记录日志,不影响已发响应。
- 进程停机时未完成任务随进程终止,需队列兜底。
代码或图示
from fastapi import BackgroundTasks
@app.post("/send")
async def send(background: BackgroundTasks):
background.add_task(send_email, to="x@example.com")
return {"ok": True}
常见误区
- 把核心事务逻辑放后台任务:进程重启即丢失,无重试保证。
- 后台任务里再抛 HTTPException:响应已结束,无法转换错误。
追问
- 后台任务阻塞会影响响应吗?答:响应发出后才执行,但占用同进程资源,长任务影响容量。
- 怎么实现可靠异步?答:Celery/RQ/任务队列 + 独立 worker + 重试与死信。
04.7.15.5-041 测试中如何覆盖真实配置与环境变量?
一句话结论
配置通过 Settings 对象注入应用工厂,测试构造测试配置覆盖 DB URL、开关、密钥等;环境变量在夹具中 monkeypatch/.env.test 加载,不依赖开发机全局环境。测试断言配置被正确读取,避免生产配置误进测试。
概念解释
- 配置分层:默认值 → 环境变量 → 测试覆盖;密钥类测试用假值。
- 避免测试读取本地
.env导致环境耦合。
原理流程
- 定义 Settings 模型,从环境变量/配置文件读取。
- 测试夹具构造测试 Settings,覆盖连接串与开关。
- 工厂接收配置对象,不直接读全局环境。
- 必要时 monkeypatch 环境变量后重载配置校验。
代码或图示
@pytest.fixture
def settings():
return Settings(env="test", db_url="sqlite:///:memory:", debug=False)
@pytest.fixture
def app(settings):
return create_app(settings)
常见误区
- 测试继承开发环境变量:连到开发库或使用真实密钥。
- 配置写死在应用代码里:无法按环境区分,测试也无法覆盖。
追问
- 敏感配置测试用什么?答:测试假值/本地内存替身,不读取生产密钥。
- 配置校验失败怎么测?答:构造非法配置对象,断言应用启动抛对应错误。
04.7.15.5-042 接口契约测试与响应模型校验怎么做?
一句话结论
契约测试固定请求样例与响应结构,断言状态码、字段存在性、类型与约束;响应模型在运行时已做输出校验,测试补充跨接口一致性与错误分支覆盖。可结合 OpenAPI schema 校验响应与文档契约一致。
概念解释
- 单元测试关注业务逻辑,契约测试关注对外接口形态稳定。
- 破坏性变更应在契约测试中暴露。
原理流程
- 准备典型与边界请求样例。
- 调用接口,断言状态码与响应字段结构。
- 校验错误分支状态码与错误体字段。
- 接口变更时契约测试先失败,提示调用方影响。
代码或图示
def test_item_contract():
resp = client.get("/items/1")
assert resp.status_code == 200
body = resp.json()
assert set(body) >= {"id", "name", "price"}
assert isinstance(body["price"], float)
常见误区
- 契约测试只断言 200:错误分支与字段缺失未覆盖。
- 断言具体文案:文案调整导致测试脆弱,优先断言稳定字段与类型。
追问
- 怎么校验响应符合 OpenAPI?答:用 schema 校验库对照
/openapi.json验证响应体结构。 - 多版本接口契约怎么管?答:按版本保留样例,旧版本契约随兼容期维护。
04.7.15.5-043 压测数据集与预热怎么准备?
一句话结论
压测数据量、字段分布与生产接近:准备足量用户、商品、订单数据,覆盖热门与冷门查询;执行前预热(冷启动 JIT/连接池/缓存),丢弃预热阶段数据。数据集固定可复现,避免缓存命中率与数据倾斜干扰容量结论。
概念解释
- 冷启动:连接池未建立、缓存未命中、代码未编译,首段延迟偏高。
- 数据分布影响查询计划与缓存效果,要贴近真实访问比例。
原理流程
- 生成压测数据集,规模与分布对齐生产估算。
- 建池、填充必要缓存,执行预热请求。
- 丢弃预热指标,开始正式加压采集。
- 每轮压测重置或隔离数据,保证可复现。
代码或图示
# 预热:跑一轮请求建立连接与缓存
wrk -t2 -c8 -d10s http://127.0.0.1:8000/items
# 正式压测
wrk -t4 -c64 -d30s http://127.0.0.1:8000/items
常见误区
- 空表压测:索引/缓存/查询计划与生产差异大,结果偏乐观。
- 压测数据反复被写入污染:后续轮次数据量失真。
追问
- 缓存预热到什么程度?答:热点数据命中,避免首轮全 miss;按业务定义热点集合。
- 怎么保证多轮压测可比?答:数据集、预热步骤、并发曲线固定,记录环境版本。
04.7.15.5-044 连接池在测试与生产的配置差异?
一句话结论
测试用最小/内存连接(SQLite、单连接、短超时),追求隔离与速度;生产按 worker 数、下游容量配置池大小、溢出、超时与回收。测试池配置不代表生产容量,生产参数必须按压测与下游上限确定。
概念解释
- 池大小影响并发等待与下游连接占用。
- 测试复用长会话可能掩盖连接释放问题。
原理流程
- 测试夹具创建独立测试库与小池。
- 生产配置按 DB max_connections 反推每进程池大小。
- 配置获取连接超时、空闲回收与溢出上限。
- 压测验证池等待水位在可接受范围。
代码或图示
# 生产示例:总连接 ≤ DB 上限
create_async_engine(url, pool_size=10, max_overflow=20, pool_timeout=5)
常见误区
- 直接把测试池配置搬到生产:容量不足或连接打满下游。
- 生产池过大:数据库连接被占满,拒绝新连接。
追问
- 池等待超时设多少?答:短于接口整体超时,快速失败而不是长期挂起。
- 空闲连接怎么回收?答:配置回收间隔,关闭长期空闲连接避免被下游断开。
04.7.15.5-045 进程内存增长怎么排查?
一句话结论
先区分增长类型:缓存增长(可预期)、连接/句柄持有、对象泄漏(不可回收)。观察压测后空闲水位是否回落,用内存采样/对象计数定位滞留对象;检查无界缓存、未关闭资源、全局列表累积与后台任务持有引用。
概念解释
- Python 引用计数 + GC,泄漏通常是对象被意外长期引用。
- 内存不归还 OS 不等于泄漏:CPython 内存分配器行为需结合工具判断。
原理流程
- 监控 RSS/堆内存随请求量与空闲变化曲线。
- 压测后观察空闲期是否回落。
- 采样堆对象分布,找数量异常增长的类型。
- 回溯引用链,解除长期引用,复测收敛。
代码或图示
# 采样思路:记录大对象/全局容器增长
import tracemalloc
tracemalloc.start()
常见误区
- 把缓存预热增长当泄漏:确认是否有界与淘汰策略。
- 只看 RSS:Python 内存碎片化与分配器保留会影响 RSS 判断。
追问
- 常见泄漏源有哪些?答:全局 dict/list 只增不减、闭包持有大对象、未取消任务、静态缓存无 TTL。
- 怎么验证修复有效?答:重复压测-空闲循环,观察内存阶梯式增长是否收敛到平稳。
04.7.15.5-046 慢查询与慢接口怎么定位链路?
一句话结论
慢接口先分段计时定位是 DB、下游、本地处理还是排队;DB 慢看执行计划、索引、锁等待与扫描行数;下游慢看 RTT、错误率与限流;本地慢看模型序列化与 CPU。链路追踪把各段串起来,避免只靠接口总耗时猜原因。
概念解释
- 接口总耗时 = 排队 + 本地处理 + 各下游等待。
- 慢 SQL 要看扫描行数、返回行数、索引命中与排序/临时表。
原理流程
- 接口打点拆分 DB/下游/序列化段耗时。
- 定位主导段后深入对应层:DB 看计划与索引,下游看指标。
- 追踪系统查看跨服务 Span 与依赖调用。
- 优化后复测分段耗时与 P99。
代码或图示
慢接口 → 分段计时
├─ DB 慢:执行计划/索引/扫描行数/锁
├─ 下游慢:RTT/错误率/熔断
└─ 本地慢:模型构造/JSON 编码/CPU
常见误区
- 接口慢就加索引:瓶颈可能在下游或序列化,索引无效。
- 只看单次 SQL 耗时:批量 N+1 与连接等待常被忽略。
追问
- N+1 怎么发现?答:追踪中一条接口触发大量重复 DB 查询,关联查询次数与主查询数量对比。
- 锁等待怎么查?答:数据库侧看锁等待与阻塞链,结合事务持锁时长。
04.7.15.5-047 并发测试与协程泄漏怎么检测?
一句话结论
并发测试用多客户端/异步并发压测验证吞吐与正确性;协程泄漏检测:监控在途任务数,压测结束后任务数应回落;用任务清单/采样检查未取消的后台任务。异步测试中等待与取消不彻底会留下悬挂协程,长期运行累积成资源问题。
概念解释
- 协程泄漏表现:任务数单调增长、内存/句柄随时间上升。
- 任务组退出应等待所有子任务,异常路径也要取消子任务。
原理流程
- 并发发起批量请求,检查结果正确性与吞吐。
- 采集在途任务/协程数量曲线。
- 压测结束空闲观察任务数是否回落。
- 未回收任务回溯创建点,补取消与清理逻辑。
代码或图示
import asyncio
async def count_tasks():
return len([t for t in asyncio.all_tasks() if not t.done()])
常见误区
- 只测单并发功能正确性:并发下竞态与泄漏不暴露。
- 后台任务 fire-and-forget 不持有引用:无法追踪与取消。
追问
- 任务组没退出会怎样?答:上下文管理器等待所有子任务完成,悬挂任务阻塞退出。
- 怎么在测试中断言无泄漏?答:用例结束记录任务数,与基线对比,差值超阈值失败。
04.7.15.5-048 部署环境变量与配置怎么分层?
一句话结论
配置分层:代码内默认值 → 环境变量/配置文件 → 环境区分(dev/test/staging/prod);敏感值走密钥管理或挂载,不进源码仓库。应用启动校验必填配置与取值范围,配置缺失快速失败,不在运行时读本地文件路径。
概念解释
- 环境差异:连接串、密钥、开关、外部地址;运行参数:worker、超时、日志级别。
- 配置变更走发布流程,不手改容器内文件。
原理流程
- 定义配置模型与默认值,标注来源环境变量。
- 部署时按环境注入变量/挂载密钥。
- 启动校验配置完整性与合法性。
- 配置变更经评审发布,记录版本。
代码或图示
Settings(默认)← 环境变量 ← 密钥挂载
启动校验:必填项存在、URL 合法、端口/超时范围
常见误区
- 配置写死在代码分支判断环境:难维护且易漏改。
- 密钥提交进仓库或镜像层:泄露面随镜像分发扩散。
追问
- 多环境配置怎么组织?答:按环境独立配置源,应用工厂按 Settings 实例装配。
- 配置热更新支持吗?答:常规部署重启生效;需要热更新需设计重载机制并评估连接重建。
04.7.15.5-049 多实例部署与会话/状态如何共享?
一句话结论
应用实例无状态化:会话、令牌吊销、缓存、限流计数、分布式锁放外部存储(Redis/DB);实例间不共享进程内存。WebSocket 广播等跨实例消息经 pub/sub 转发。本地进程状态只做可重建的缓存,实例可随时替换。
概念解释
- 有状态实例限制弹性扩缩与滚动发布。
- 外部存储成为共享状态瓶颈,需规划容量与高可用。
原理流程
- 识别进程内状态:会话、缓存、登记表、计数器。
- 迁移到外部存储或消息通道。
- 实例启动从存储加载必要数据,结束释放本地持有。
- 扩缩容与发布时实例可任意替换。
代码或图示
多实例 → Redis(会话/黑名单/限流/锁)
→ MQ pub/sub(WebSocket 跨实例广播)
→ DB(持久业务数据)
常见误区
- 连接登记表留进程内:多实例下消息发不到其他实例连接。
- 本地缓存当权威状态:实例重启丢失,多实例数据不一致。
追问
- 外部存储挂了怎么办?答:按降级策略(只读/缓存兜底),高可用部署 Redis/DB。
- 会话粘性需要吗?答:无状态设计下不需要会话粘性;有状态会话才需粘性路由。
04.7.15.5-050 滚动发布与连接 drain 怎么配合?
一句话结论
滚动发布逐实例替换:旧实例先摘流量(就绪探针失败/负载均衡摘除)→ 排空在途请求 → 关闭资源退出;新实例就绪后再接流量。drain 期间拒绝新连接,等待在途任务完成或达超时,避免发布中断用户请求与事务。
概念解释
- 发布顺序:先下旧、再上新,避免新旧版本同时承接不确定流量。
- 长连接(SSE/WS)需主动关闭并让客户端重连到新实例。
原理流程
- 编排平台标记旧实例不再接新流量。
- 等待在途请求在宽限窗口完成。
- lifespan 关闭段释放池与客户端。
- 旧实例退出,新实例通过就绪检查后接入。
代码或图示
摘流量 → drain 在途请求 → 释放资源 → 退出
新实例初始化 → 就绪探针通过 → 接入流量
常见误区
- 旧实例直接强杀:在途事务与长连接被切断。
- 新实例未就绪就接流量:启动失败/依赖未就绪导致 5xx。
追问
- 长连接发布怎么处理?答:旧实例关闭 WS/SSE 连接,客户端重连到新实例;发布窗口通知前端重连策略。
- drain 超时怎么定?答:覆盖 P99 长尾请求时长,长任务走队列不在请求内完成。
04.7.15.5-051 测试覆盖率怎么衡量,为什么不追数字?
一句话结论
覆盖率衡量代码被测试执行的比例,是发现遗漏的辅助指标,不代表断言质量;高覆盖可能只走通路径未校验结果。重点覆盖核心业务分支、错误路径与边界条件,按风险设定覆盖目标,不为凑数字写无效断言。
概念解释
- 覆盖率工具统计行/分支执行,不检查断言是否充分。
- 关键链路与高风险模块优先覆盖。
原理流程
- 运行测试采集覆盖率数据。
- 识别未覆盖的分支与异常路径。
- 补充用例并校验断言,而非仅执行代码。
- 按模块风险设目标,核心模块覆盖度高于工具类。
代码或图示
pytest --cov=app --cov-report=term-missing
常见误区
- 追求 100% 行覆盖:低价值 getter/配置类浪费精力。
- 覆盖了代码但无断言:测试不防回归,覆盖率虚高。
追问
- 分支覆盖与行覆盖哪个更有意义?答:分支覆盖更能暴露条件路径遗漏,核心模块看分支。
- 覆盖率下降怎么评审?答:新代码未补测试不合并,缺失分支说明原因。
04.7.15.5-052 单元测试与集成测试边界怎么划?
一句话结论
单元测试隔离业务逻辑,替身外部依赖,快速验证规则与分支;集成测试接真实/测试数据库、应用链路与外部替身,验证装配、配置与端到端行为。核心领域逻辑以单元测试为主,接口与持久化走集成测试,两层互补不互相替代。
概念解释
- 单元快而多,覆盖分支;集成慢而少,验证真实接线。
- 依赖注入让两层都能替换外部资源。
原理流程
- 领域服务/规则抽成可单测的纯函数/类。
- 单元测试 mock 仓储与外部客户端,断言业务规则。
- 集成测试通过 TestClient/AsyncClient 走完整链路。
- 两层按模块分配比例,接口契约由集成测试覆盖。
代码或图示
单元:服务 + mock 仓储 → 规则/分支/边界
集成:TestClient + 测试库 → 路由/依赖/序列化/持久化
常见误区
- 全写集成测试:慢、脆弱,定位问题要穿透多层。
- 全写单元测试:依赖接线与配置错误发现不了。
追问
- 外部第三方服务怎么测?答:单元测试替身,集成测试用沙箱/录制回放,不依赖生产环境。
- 测试夹具属于哪层?答:共享夹具服务两层,隔离级别按夹具作用域控制。
04.7.15.5-053 mock 下游外部依赖的边界在哪里?
一句话结论
mock 用于隔离不可控/慢/有副作用的外部依赖(第三方 API、短信、支付),验证本服务调用参数与交互;不要 mock 自己拥有的业务逻辑与数据库核心规则。替身按接口契约构造,记录调用次数与参数,避免过度 mock 导致测试与真实行为脱节。
概念解释
- mock 验证“怎么调用”,stub 提供“返回什么”。
- 真实数据库查询、本地业务规则应尽量用真实实现测试。
原理流程
- 识别依赖:外部不可控服务优先替身,自有仓储可用测试库。
- 定义替身返回样例与异常场景。
- 断言本服务发出的请求参数、重试与错误处理。
- 关键外部链路另用沙箱/契约测试补充。
代码或图示
async def fake_client(path):
return {"status": "ok"}
app.dependency_overrides[get_http_client] = lambda: fake_client
常见误区
- mock 掉数据库验证业务规则:持久化与约束错误测不出来。
- 替身返回与真实接口不符:测试通过但线上集成失败。
追问
- 怎么保证替身契约正确?答:结合外部接口文档/录制响应,定期与沙箱联调核对。
- mock 太多个怎么拆?答:按外部服务分组替身,依赖注入点清晰对应。
04.7.15.5-054 异步代码测试常见的 flaky 来源有哪些?
一句话结论
flaky 来源:未等待后台任务完成就断言、事件循环/夹具复用不当、依赖真实时间/睡眠、并发竞态、外部环境不稳定、共享测试数据串扰。治理:显式等待任务完成、固定时钟/超时、隔离数据、消除共享状态,把偶发失败转成可复现用例。
概念解释
- flaky 是同一用例时过时不过,根因多为时序与共享状态。
- 异步测试必须明确任务边界:哪些等待完成,哪些独立后台。
原理流程
- 失败用例复现:加大并发/重复执行定位时序窗口。
- 检查断言前是否等待所有相关协程完成。
- 消除时间依赖(固定时间/可控 sleep)与共享数据。
- 修复后重复跑套件确认稳定。
代码或图示
# 等待后台任务完成再断言
await asyncio.gather(*pending_tasks)
常见误区
- 用
time.sleep等待异步任务:时长不够失败,过长拖慢套件。 - 多测试用例共享同一数据集:执行顺序影响结果。
追问
- 后台任务怎么在测试中收尾?答:持有任务引用并 await,或用任务组等待;必要时测试专用同步实现。
- 怎么批量发现 flaky?答:CI 中重复执行套件、记录偶发失败用例并隔离修复。
04.7.15.5-055 生产日志级别与敏感信息脱敏怎么配?
一句话结论
生产默认 info 级别,异常与慢请求 warning/error;调试细节按需临时开启。日志禁止记录密码、令牌、身份证/手机号等敏感信息,必要字段脱敏(掩码/哈希)。结构化字段统一,日志量与级别按环境配置,避免磁盘被刷屏日志打满。
概念解释
- 日志级别:debug 开发、info 运行、warning 异常苗头、error 失败。
- 脱敏在日志输出层统一处理,不靠各业务自觉。
原理流程
- 配置日志格式、级别与输出目标。
- 敏感字段在序列化层掩码或剥离。
- 关键事件按级别记录,异常带堆栈与请求 ID。
- 监控日志量与错误级别,告警异常增长。
代码或图示
def mask(value: str | None) -> str:
if not value:
return ""
return value[:3] + "***"
常见误区
- 生产开 debug:日志量暴增,且内部细节外泄。
- 异常日志打完整请求体:敏感数据进入日志系统。
追问
- 堆栈要打全吗?答:error 级别记录堆栈用于排障,注意不混入敏感请求参数。
- 日志保留与合规?答:按隐私合规要求保留周期,个人信息最小化记录。
04.7.15.5-056 错误追踪与异常上报怎么接入?
一句话结论
接入错误追踪平台(如 Sentry 类),捕获未处理异常并上报堆栈、请求上下文、用户标识与请求 ID;捕获处理器内补充环境与版本信息,过滤噪声与预期业务错误。追踪系统与日志按 trace/request ID 关联,便于从告警下钻到现场。
概念解释
- 上报的是未预期异常;受控
HTTPException不一定要上报为错误。 - 上下文脱敏:不上报密码、令牌与敏感个人信息。
原理流程
- 初始化追踪 SDK,配置服务名、环境、版本。
- 异常处理器/中间件捕获未处理异常,附加上下文上报。
- 按类型过滤预期业务错误,降低噪声。
- 告警关联追踪事件,按 ID 检索日志与链路。
代码或图示
@app.exception_handler(Exception)
async def fallback(request: Request, exc: Exception):
capture_exception(exc, context={"path": request.url.path})
return JSONResponse({"detail": "internal error"}, 500)
常见误区
- 把 4xx 业务错误全部上报:追踪被噪声淹没,真问题被忽略。
- 上报请求原文:敏感信息进入第三方追踪平台。
追问
- 异步任务异常怎么上报?答:在任务内捕获并显式上报,后台任务异常不经过请求处理器。
- 采样上报怎么配?答:高错误量按规则采样,错误与慢请求优先保留。
04.7.15.5-057 限流熔断在部署层怎么配合?
一句话结论
分层保护:网关/反代层入口限流与连接限制,应用层按主体速率限流与并发信号量,下游客户端熔断降级。各层阈值协同,避免单点过载;熔断在下游故障时快速失败,防止请求堆积拖垮本服务。限流响应带 Retry-After 便于退避。
概念解释
- 限流控制到达速率;熔断切断故障下游调用;两者保护对象不同。
- 部署层配置与应用内限流策略要对齐,不重复冲突。
原理流程
- 网关层限制总连接与请求速率。
- 应用层按用户/接口配额限流,信号量控制并发。
- 下游客户端统计失败率,超阈值熔断并降级。
- 故障恢复后半开探测,逐步恢复调用。
代码或图示
网关限流 → 应用速率/并发限制 → 下游熔断/降级
超限:429 + Retry-After;熔断:快速失败 + 兜底响应
常见误区
- 只在应用层限流:流量在到达应用前已打满连接/CPU。
- 熔断不设恢复探测:下游恢复后仍长期拒绝调用。
追问
- 限流计数放哪里?答:分布式配额用 Redis 共享,单机配额用进程内信号量/计数器。
- 熔断阈值怎么定?答:基于下游历史错误率与响应延迟,压测与线上观测调整。
04.7.15.5-058 静态文件与上传存储在部署中怎么处理?
一句话结论
静态资源(前端构建产物、文档)由 Nginx/CDN 直接服务,应用只挂必要的静态目录;上传文件不存应用本地磁盘,放对象存储或共享卷,多实例共享访问。临时文件用完清理,限制大小与类型,备份与权限在存储层管理。
概念解释
- 本地磁盘在容器重建/多实例下不可靠,不作为持久存储。
- 上传链路:接收 → 校验 → 转存外部存储 → 记录元数据。
原理流程
- 构建产物部署到静态目录,反代直接返回。
- 上传接口校验大小/类型后写入对象存储/共享卷。
- 数据库只存文件键与元数据,不存二进制。
- 临时文件按策略清理,存储层做备份与访问控制。
代码或图示
from fastapi.staticfiles import StaticFiles
app.mount("/static", StaticFiles(directory="static"), name="static")
常见误区
- 上传文件写容器本地目录:实例重建丢失,多实例互不可见。
- 静态目录挂在应用后经 Python 服务:浪费应用进程资源,应反代直出。
追问
- 大文件上传怎么做?答:分片上传 + 对象存储直传,服务端合并校验。
- 静态资源缓存策略?答:按内容哈希文件名配长缓存,入口 HTML 短缓存。
04.7.15.5-059 版本升级回归检查清单有哪些?
一句话结论
升级清单:依赖版本兼容矩阵、弃用警告清理、Pydantic/框架 API 迁移、测试套件全绿、文档 schema 生成正常、启动 lifespan 与依赖初始化、核心接口契约、压测基线对比、配置与密钥兼容、灰度回滚方案。跨版本分批升级,不在生产直接跳大版本。
概念解释
- 回归覆盖:功能正确性、性能基线、配置装配、文档与错误分支。
- 升级前备份与回滚路径要预先确认。
原理流程
- 核对 changelog 与依赖兼容版本,锁定版本范围。
- 本地迁移写法,清理 DeprecationWarning。
- 跑测试、生成文档、压测对比基线。
- 灰度发布观测指标与追踪,保留回滚方案。
代码或图示
兼容矩阵 → 弃用清理 → 测试 → schema 生成 → 启动/依赖 → 契约 → 压测 → 灰度
常见误区
- 只跑单元测试:集成链路、配置与序列化回归未覆盖。
- 升级后不对比性能:新版本序列化/调度行为变化可能降低吞吐。
追问
- 怎么记录升级差异?答:变更清单、测试结果、压测对比与灰度观察项归档。
- 第三方库不兼容怎么办?答:先升级兼容层,锁定已知可用版本,分批解耦。
04.7.15.5-060 上线前验收检查项汇总有哪些?
一句话结论
验收清单:核心接口通过测试与契约校验;认证授权、错误格式与限流生效;配置/密钥注入正确;健康检查与探针可用;日志、指标、追踪接入;容量按压测规划 worker 与资源;优雅停机与回滚流程确认;文档按环境关闭或保护;敏感信息不进日志与响应;监控告警阈值就位。
概念解释
- 验收从功能、安全、性能、可观测、发布流程五个维度逐项核对。
- 每项有可验证结果,不停留在“已完成”描述。
原理流程
- 功能与契约:测试套件通过,核心链路手工验证。
- 安全:鉴权归属校验、脱敏、文档暴露面、密钥来源。
- 性能:worker/资源配置对齐压测基线,限流熔断就位。
- 发布可观测:探针、日志、指标、追踪、告警、回滚方案确认。
代码或图示
功能:测试/契约/核心链路
安全:认证授权/脱敏/文档/密钥
性能:worker/池/限流/熔断/压测基线
运维:探针/日志/指标/追踪/告警/停机/回滚
常见误区
- 验收只看功能可用:可观测性、容量与发布流程遗漏,线上故障无法定位与恢复。
- 上线前未演练回滚:出问题时回滚路径不清晰,扩大故障时间。
追问
- 怎么形成验收记录?答:逐项记录检查结果、负责人与遗留项,遗留风险明确降级方案。
- 第一次上线重点补什么?答:监控告警、健康检查与日志关联,保证出问题可发现可定位。
本节高频题
- TestClient 与 AsyncClient/ASGITransport(001、002)
dependency_overrides与测试库隔离(003、004、005)- app factory、lifespan 测试与异步夹具(006、007、011)
- WebSocket/异常处理器/认证依赖测试(008、009、010)
- 序列化、Pydantic 构造与 JSON 编码热点(013、014、015、016)
- 瓶颈定位与压测口径(017、018、019、020)
- GIL、worker 与 uvicorn/gunicorn 部署(021、022、023、024)
- 容器、探针、优雅停机与反代配置(025、026、027、028、029)
- 日志、Prometheus 指标与 OpenTelemetry(030、031、032、033、034)
- 版本兼容与 Pydantic v2 迁移(035、036、059)
- 典型坑:同步阻塞、依赖缓存 session、资源泄漏、后台任务(037、038、039、040)
- 配置注入、契约测试与 mock 边界(041、042、053)
- 压测数据、连接池、内存与慢链路排查(043、044、045、046)
- 并发泄漏、flaky 治理与覆盖率(047、051、052、054)
- 生产安全:脱敏、追踪上报、限流熔断、存储部署(055、056、057、058)
- 多实例状态共享与滚动发布(049、050)
- 上线验收清单(060)