罗罗编程学习记录
本页内容 展开查看

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。

原理流程

  1. 构造 TestClient(app),内部建立 ASGI 传输与事件循环。
  2. 调用 client.get("/items"),httpx 构造请求经传输进入应用。
  3. 应用在循环内完成路由、依赖、端点与序列化。
  4. 响应回到客户端对象,断言 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 传输,端口可留空。
  • 在测试里直接 await TestClient 方法:它是同步接口,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 异步夹具、异步会话与任务组。

原理流程

  1. 构造 ASGITransport(app=app),传入 AsyncClient(transport=...)。
  2. 测试协程 await 请求方法,应用在同一循环内处理。
  3. 响应返回后断言 JSON 与状态码。
  4. 夹具按 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 恢复。适合替换数据库会话、认证用户、外部客户端等不希望在测试中真实初始化的依赖。

概念解释

  • 替换按依赖函数对象匹配,不是按名字字符串。
  • 覆盖优先级高于原始依赖,路由与子依赖链一并生效。

原理流程

  1. 测试夹具保存原依赖引用与覆盖表。
  2. 写入 dependency_overrides,返回测试用依赖结果。
  3. 请求经过路由时解析到替换后的依赖。
  4. 测试结束清空覆盖表,避免污染其他用例。

代码或图示

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 操作无法回滚时用清空策略。
  • 测试库与开发/生产库严格分离,配置走环境变量。

原理流程

  1. 测试启动前创建/迁移测试库与基线数据。
  2. 每个用例开启事务,结束回滚或清理相关表。
  3. 断言基于用例内构造的数据,不依赖残留状态。
  4. 套件结束销毁测试库实例(容器化环境)。

代码或图示

@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)包裹,避免提前提交污染隔离。

原理流程

  1. 夹具获取连接并开启外层事务。
  2. 构造绑定该连接的会话交用例使用。
  3. 用例执行请求与断言。
  4. 结束关闭会话,回滚外层事务,归还连接。

代码或图示

@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。

原理流程

  1. 定义 create_app(config),内部组装应用。
  2. 测试夹具用测试配置调用工厂。
  3. 在实例上写 dependency_overrides 并共享夹具。
  4. 每个用例可拿到干净实例,结束销毁。

代码或图示

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)会拖慢用例,通常用覆盖依赖替代。

原理流程

  1. TestClient(app) 进入 with 块,触发 lifespan 启动段。
  2. 应用资源初始化完成,请求正常处理。
  3. 退出 with 块,触发关闭段释放资源。
  4. 不使用上下文管理器时,需按所用版本确认 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 服务器。
  • 连接登记/广播逻辑可用多连接夹具覆盖跨连接推送。

原理流程

  1. 用 websocket_connect 建立测试连接。
  2. 发送消息,等待并接收广播/回显。
  3. 断言消息字段、房间归属与错误帧。
  4. 退出管理器触发关闭与清理逻辑。

代码或图示

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,断言字段问题列表。

原理流程

  1. 构造触发异常的请求(缺字段、越权、不存在资源)。
  2. 客户端收到处理器生成的响应。
  3. 断言状态码、错误码、消息与请求 ID 字段。
  4. 对比错误模型 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。覆盖保持与生产相同的依赖层级,避免测试绕过真实授权代码。

概念解释

  • 单元级测试替换用户加载;契约/集成测试走真实校验配合测试凭证。
  • 不同角色用夹具参数化,批量覆盖权限分支。

原理流程

  1. 定义可切换的测试用户依赖。
  2. 夹具按角色返回对应用户对象。
  3. 覆盖表注入替换依赖。
  4. 用例断言角色对应的访问结果。

代码或图示

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 共享程度最高。

原理流程

  1. 测试文件导入 pytest 与异步客户端。
  2. 标记异步测试函数,定义 async fixture。
  3. 插件在循环内执行用例,await 所有异步调用。
  4. 结束后按作用域清理夹具与循环。

代码或图示

@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 级造业务数据与会话;清理与创建对称(开事务/关事务、建实例/销毁实例)。数据清理优先自动隔离(回滚/重建),不依赖人工在测试末尾删除。

概念解释

  • 高复用夹具减少重复初始化成本;低作用域夹具保证用例隔离。
  • 夹具依赖图按作用域顺序初始化,逆序销毁。

原理流程

  1. 识别资源类别:连接/客户端高复用,业务数据每用例独立。
  2. 连接类夹具用 module/session 作用域。
  3. 数据类夹具 function 作用域,结束回滚或清理。
  4. 销毁逻辑写在 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 多一层成本。

原理流程

  1. 端点返回业务对象/列表。
  2. 框架按 response_model 构造模型实例,校验字段。
  3. 模型 dump 为 dict,JSON 编码器转字节。
  4. 大列表时遍历与编码在单请求内重复放大。

代码或图示

# 大列表响应:模型遍历 + 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 内部实现不同,但“遍历字段 + 校验约束”的基本成本结构一致。
  • 校验越严(正则、嵌套、自定义校验器)单次成本越高。

原理流程

  1. 请求体进入,构造输入模型并逐字段校验。
  2. 嵌套字段递归构造子模型。
  3. 响应出口构造输出模型,过滤字段后 dump。
  4. 高 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、枚举)支持要逐一验证。

原理流程

  1. 定位 JSON 编码在 profile 中的占比。
  2. 评估替代库对项目数据类型的兼容性。
  3. 接入自定义 JSON 响应/编码器,跑回归对比输出。
  4. 压测验证吞吐与延迟改善,观察兼容性问题。

代码或图示

# 自定义 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 大列表响应的内存与序列化怎么优化?

一句话结论

大列表问题是一次性载入全量数据、构造全量模型再编码,内存峰值与首字节延迟都高;优化:分页/游标分批、流式响应逐块产出、精简输出字段、避免嵌套模型冗余,必要时用更高效编码路径。导出类接口优先流式分页,不返回全量数组。

概念解释

  • 内存峰值 = 原始数据 + 模型对象 + 编码缓冲区,三者同时驻留。
  • 分页控制单请求数据量,流式让内存随产出回收。

原理流程

  1. 识别大列表接口的数据量级与字段宽度。
  2. 改分页/游标查询,限制单页大小。
  3. 响应按批次序列化输出(StreamingResponse/NDJSON)。
  4. 裁剪非必要字段,降低每条记录宽度。

代码或图示

@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)。

原理流程

  1. 在关键阶段打点计时,拆分 DB/下游/序列化/编码耗时。
  2. 用采样工具(py-spy dump/record)或 cProfile 生成火焰图。
  3. 对照指标确认是 CPU 饱和、连接池排队还是下游慢。
  4. 优化后复测同口径对比,确认瓶颈转移或消除。

代码或图示

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。
  • 用户模拟要贴近真实行为:读多写少、页面跳转顺序、参数分布。

原理流程

  1. 编写任务:GET/POST 序列、参数生成、成功断言。
  2. 配置并发用户数、爬升速率与持续时间。
  3. 执行压测,采集 RPS、响应时间分布、失败率。
  4. 同步记录服务端 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 版本差异会影响结果。

原理流程

  1. 选择工具与并发模型,配置连接数与持续时间。
  2. 执行压测,记录 RPS、延迟分布、失败连接数。
  3. 对照服务端资源水位判断瓶颈层。
  4. 调整并发找到延迟开始劣化的吞吐拐点。

代码或图示

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 连接池等待与耗时、网络收发。指标按实例聚合,结合压测曲线观察拐点与资源瓶颈。

概念解释

  • 应用指标反映处理能力,系统指标反映资源约束,下游指标反映依赖瓶颈。
  • 单一指标不足以定位,要交叉对照。

原理流程

  1. 压测前确认基线:空闲水位与单次正常耗时。
  2. 加压过程采集应用与系统指标。
  3. 对比延迟上升段对应的资源饱和点。
  4. 记录容量拐点:吞吐上限、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 获得并行,代价是内存与连接按进程复制。

原理流程

  1. 协程等待 IO,释放循环与 GIL 供其他任务运行。
  2. 本地计算段持有 GIL,线程间串行执行字节码。
  3. CPU 密集任务多线程并行收益受限。
  4. 通过多 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 数 × 每进程池大小,不能超过数据库上限。

原理流程

  1. 确认部署环境可用 CPU 核数(容器按 limit)。
  2. 以核数附近为起点配置 worker。
  3. 压测观测 CPU 利用率、循环延迟与延迟分位。
  4. 结合内存占用与下游连接上限微调,记录容量基线。

代码或图示

# 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 读取真实信息。

原理流程

  1. 配置监听地址端口与 worker 数。
  2. 选择循环与 HTTP 实现,按平台兼容性确认。
  3. 设置 keep-alive 与优雅停机超时。
  4. 反代部署开启 --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 模式侧重进程管理生态。

原理流程

  1. 安装 gunicorn 与 uvicorn,指定 worker 类。
  2. 配置 worker 数、绑定地址、超时与日志。
  3. gunicorn fork 进程,各 worker 启动 ASGI 循环。
  4. 信号触发优雅停机,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 数与内存规划的依据。

原理流程

  1. 基础镜像选精简运行时,安装系统依赖与 Python 包。
  2. 复制代码,切换非 root 用户。
  3. 注入环境配置,暴露端口与健康检查。
  4. 编排层配置资源限制、副本数与探针。

代码或图示

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/下游连通后再决定是否摘除流量。

概念解释

  • 存活失败触发重启;就绪失败只从负载均衡摘除,不重启进程。
  • 探针端点不应做重依赖长查询,避免误摘。

原理流程

  1. 编排平台周期调用 liveness 端点,失败重启容器。
  2. 调用 readiness 端点检查依赖连通性。
  3. 依赖未就绪时摘出流量,恢复后重新接入。
  4. 探针结果独立于业务接口状态。

代码或图示

@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 关闭段释放连接池/客户端 → 进程退出。超时配置覆盖在途请求等待与资源关闭;超过窗口强制退出,避免卡死发布流程。

概念解释

  • 优雅停机减少中断在途业务,避免连接与事务被硬切断。
  • 排队等待、下游响应、资源关闭各段都要有超时上限。

原理流程

  1. 编排/服务器收到 SIGTERM,停止接受新连接。
  2. 等待在途请求在宽限窗口内完成。
  3. lifespan 关闭段逆序释放池、客户端与订阅。
  4. 超时未排空则强制退出,记录未完成请求。

代码或图示

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 是应用对外可见的前缀,不影响内部路由匹配。
  • 代理头必须来自可信代理,直接暴露公网时不能信任客户端伪造值。

原理流程

  1. 反代按域名/路径转发,附加转发头。
  2. 应用配置 root_path 与可信代理列表。
  3. 生成链接、回调与 OpenAPI 地址时带上前缀与协议。
  4. 日志按转发头记录真实客户端 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 头。

原理流程

  1. Nginx 监听 443,按 location 反代到 uvicorn 实例。
  2. 转发 Host 与 X-Forwarded 头,设置超时与体限制。
  3. 长连接接口配置缓冲与升级支持。
  4. 后端连接 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。
  • 访问日志与业务审计日志分层存储。

原理流程

  1. 中间件解析或生成请求 ID,写入上下文变量。
  2. 记录请求开始,处理完成后记录状态码与耗时。
  3. 下游调用头透传请求 ID,串联跨服务日志。
  4. 日志聚合系统按 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(在途/水位)。
  • 高基数标签会撑爆时序数据库,标签维度只取稳定枚举。

原理流程

  1. 安装库并实例化 Instrumentator。
  2. 注册中间件/路由,暴露 metrics 端点。
  3. 自动采集 HTTP 指标,按需添加自定义业务指标。
  4. 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 率上升、在途堆积、连接池等待增长;指标要按接口与实例拆分,避免全局平均掩盖局部问题。

概念解释

  • 延迟看尾部分位,错误率按状态码与错误类型拆分。
  • 依赖指标反映下游瓶颈,应用指标反映本地处理能力。

原理流程

  1. 定义各接口 SLA:延迟目标、错误率上限。
  2. 采集应用、系统、依赖三层指标。
  3. 配置告警规则:分位延迟、错误率、资源饱和、连接等待。
  4. 值班看板按接口、实例、下游下钻定位。

代码或图示

请求: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 补充业务步骤。

原理流程

  1. 初始化 TracerProvider 与导出器,配置服务名与环境属性。
  2. 注册 ASGI/FastAPI 追踪中间件,请求进入创建根 Span。
  3. 下游调用经 instrumentation 生成子 Span,上下文随请求传播。
  4. 日志注入 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 自动完成,手动调用需显式处理。

原理流程

  1. 入口服务创建根 Span,生成 trace 上下文。
  2. 出站调用注入 traceparent 等传播头。
  3. 下游服务提取上下文,挂接为子 Span。
  4. 异步队列消息携带上下文属性,消费端恢复链路。

代码或图示

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 与内部函数要区分使用。
  • 小版本升级先跑测试套件与文档生成,再灰度发布。

原理流程

  1. 升级前阅读版本变更与弃用列表。
  2. 本地启动应用,收集弃用警告与行为差异。
  3. 迁移受影响写法(lifespan、Pydantic v2 语法等)。
  4. 测试通过后灰度,观察指标与错误追踪。

代码或图示

检查项: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,依赖库需同步升级兼容版本。

原理流程

  1. 升级 Pydantic 与相关库到兼容版本。
  2. 逐模型替换配置与校验器写法。
  3. 跑测试核对请求校验、响应序列化输出。
  4. 对比 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 依赖会进线程池,不阻塞循环;问题出在异步函数体内调用同步阻塞代码。
  • 阻塞点可能藏在被依赖引入的工具函数/客户端内部。

原理流程

  1. 请求进入异步端点,调用异步依赖。
  2. 依赖体内执行同步阻塞库调用。
  3. 循环线程被占住,其他请求与定时器排队。
  4. 症状:全接口延迟抬升、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,可能带来事务状态串扰、连接提前关闭或并发下状态污染。需要每处独立会话时,关闭该依赖缓存或改用独立工厂依赖。

概念解释

  • 依赖缓存是一次请求内的结果复用,跨请求不共享。
  • 缓存行为按依赖函数对象判定,嵌套依赖共享同一缓存结果。

原理流程

  1. 框架解析依赖图,检查缓存结果是否已存在。
  2. 命中缓存直接复用,不再执行依赖函数。
  3. 复用的 session 携带前序操作的事务状态。
  4. 多步操作共享会话导致提交/回滚边界混乱。

代码或图示

# 默认:同请求内 get_db 结果复用
async def get_db():
    session = AsyncSessionFactory()
    yield session

# 需要独立会话时:按依赖隔离或显式关闭缓存(按版本核对参数)

常见误区

  • 以为每次注入都新建 session:缓存复用让多个步骤共用一个连接。
  • 会话生命周期与请求生命周期不匹配:提前关闭后下游再用报错。

追问

  • 怎么确认依赖被缓存复用?答:在依赖函数内打日志,观察一次请求内执行次数。
  • 关闭缓存后要注意什么?答:重复创建连接池会话,开销上升;只在确有隔离需求时关闭。

04.7.15.5-039 生命周期资源泄漏的典型表现与排查方式?

一句话结论

泄漏表现:内存/连接数持续上涨不回落、池等待增加、文件描述符耗尽、停机时资源未释放。排查沿 lifespan 创建点 → 依赖注入 → 请求结束释放链,核对每个获取的资源是否有对应释放;压测后观察指标是否回落,对比连接/句柄计数。

概念解释

  • 常见泄漏:连接未关闭、后台任务未取消、缓存无界增长、订阅未退订。
  • 生命周期资源在 lifespan 创建,必须在关闭段或依赖退出段释放。

原理流程

  1. 监控内存、连接池占用、句柄数随请求量变化。
  2. 压测结束空闲观察水位是否回落。
  3. 对照资源获取点检查释放路径(finally/yield 退出段)。
  4. 修复后复测水位曲线,确认增长收敛。

代码或图示

@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 消费与重试。

原理流程

  1. 端点把任务函数加入 BackgroundTasks。
  2. 响应体发送完成后调度执行后台任务。
  3. 任务内异常捕获并记录日志,不影响已发响应。
  4. 进程停机时未完成任务随进程终止,需队列兜底。

代码或图示

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 导致环境耦合。

原理流程

  1. 定义 Settings 模型,从环境变量/配置文件读取。
  2. 测试夹具构造测试 Settings,覆盖连接串与开关。
  3. 工厂接收配置对象,不直接读全局环境。
  4. 必要时 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 校验响应与文档契约一致。

概念解释

  • 单元测试关注业务逻辑,契约测试关注对外接口形态稳定。
  • 破坏性变更应在契约测试中暴露。

原理流程

  1. 准备典型与边界请求样例。
  2. 调用接口,断言状态码与响应字段结构。
  3. 校验错误分支状态码与错误体字段。
  4. 接口变更时契约测试先失败,提示调用方影响。

代码或图示

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/连接池/缓存),丢弃预热阶段数据。数据集固定可复现,避免缓存命中率与数据倾斜干扰容量结论。

概念解释

  • 冷启动:连接池未建立、缓存未命中、代码未编译,首段延迟偏高。
  • 数据分布影响查询计划与缓存效果,要贴近真实访问比例。

原理流程

  1. 生成压测数据集,规模与分布对齐生产估算。
  2. 建池、填充必要缓存,执行预热请求。
  3. 丢弃预热指标,开始正式加压采集。
  4. 每轮压测重置或隔离数据,保证可复现。

代码或图示

# 预热:跑一轮请求建立连接与缓存
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 数、下游容量配置池大小、溢出、超时与回收。测试池配置不代表生产容量,生产参数必须按压测与下游上限确定。

概念解释

  • 池大小影响并发等待与下游连接占用。
  • 测试复用长会话可能掩盖连接释放问题。

原理流程

  1. 测试夹具创建独立测试库与小池。
  2. 生产配置按 DB max_connections 反推每进程池大小。
  3. 配置获取连接超时、空闲回收与溢出上限。
  4. 压测验证池等待水位在可接受范围。

代码或图示

# 生产示例:总连接 ≤ DB 上限
create_async_engine(url, pool_size=10, max_overflow=20, pool_timeout=5)

常见误区

  • 直接把测试池配置搬到生产:容量不足或连接打满下游。
  • 生产池过大:数据库连接被占满,拒绝新连接。

追问

  • 池等待超时设多少?答:短于接口整体超时,快速失败而不是长期挂起。
  • 空闲连接怎么回收?答:配置回收间隔,关闭长期空闲连接避免被下游断开。

04.7.15.5-045 进程内存增长怎么排查?

一句话结论

先区分增长类型:缓存增长(可预期)、连接/句柄持有、对象泄漏(不可回收)。观察压测后空闲水位是否回落,用内存采样/对象计数定位滞留对象;检查无界缓存、未关闭资源、全局列表累积与后台任务持有引用。

概念解释

  • Python 引用计数 + GC,泄漏通常是对象被意外长期引用。
  • 内存不归还 OS 不等于泄漏:CPython 内存分配器行为需结合工具判断。

原理流程

  1. 监控 RSS/堆内存随请求量与空闲变化曲线。
  2. 压测后观察空闲期是否回落。
  3. 采样堆对象分布,找数量异常增长的类型。
  4. 回溯引用链,解除长期引用,复测收敛。

代码或图示

# 采样思路:记录大对象/全局容器增长
import tracemalloc
tracemalloc.start()

常见误区

  • 把缓存预热增长当泄漏:确认是否有界与淘汰策略。
  • 只看 RSS:Python 内存碎片化与分配器保留会影响 RSS 判断。

追问

  • 常见泄漏源有哪些?答:全局 dict/list 只增不减、闭包持有大对象、未取消任务、静态缓存无 TTL。
  • 怎么验证修复有效?答:重复压测-空闲循环,观察内存阶梯式增长是否收敛到平稳。

04.7.15.5-046 慢查询与慢接口怎么定位链路?

一句话结论

慢接口先分段计时定位是 DB、下游、本地处理还是排队;DB 慢看执行计划、索引、锁等待与扫描行数;下游慢看 RTT、错误率与限流;本地慢看模型序列化与 CPU。链路追踪把各段串起来,避免只靠接口总耗时猜原因。

概念解释

  • 接口总耗时 = 排队 + 本地处理 + 各下游等待。
  • 慢 SQL 要看扫描行数、返回行数、索引命中与排序/临时表。

原理流程

  1. 接口打点拆分 DB/下游/序列化段耗时。
  2. 定位主导段后深入对应层:DB 看计划与索引,下游看指标。
  3. 追踪系统查看跨服务 Span 与依赖调用。
  4. 优化后复测分段耗时与 P99。

代码或图示

慢接口 → 分段计时
  ├─ DB 慢:执行计划/索引/扫描行数/锁
  ├─ 下游慢:RTT/错误率/熔断
  └─ 本地慢:模型构造/JSON 编码/CPU

常见误区

  • 接口慢就加索引:瓶颈可能在下游或序列化,索引无效。
  • 只看单次 SQL 耗时:批量 N+1 与连接等待常被忽略。

追问

  • N+1 怎么发现?答:追踪中一条接口触发大量重复 DB 查询,关联查询次数与主查询数量对比。
  • 锁等待怎么查?答:数据库侧看锁等待与阻塞链,结合事务持锁时长。

04.7.15.5-047 并发测试与协程泄漏怎么检测?

一句话结论

并发测试用多客户端/异步并发压测验证吞吐与正确性;协程泄漏检测:监控在途任务数,压测结束后任务数应回落;用任务清单/采样检查未取消的后台任务。异步测试中等待与取消不彻底会留下悬挂协程,长期运行累积成资源问题。

概念解释

  • 协程泄漏表现:任务数单调增长、内存/句柄随时间上升。
  • 任务组退出应等待所有子任务,异常路径也要取消子任务。

原理流程

  1. 并发发起批量请求,检查结果正确性与吞吐。
  2. 采集在途任务/协程数量曲线。
  3. 压测结束空闲观察任务数是否回落。
  4. 未回收任务回溯创建点,补取消与清理逻辑。

代码或图示

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、超时、日志级别。
  • 配置变更走发布流程,不手改容器内文件。

原理流程

  1. 定义配置模型与默认值,标注来源环境变量。
  2. 部署时按环境注入变量/挂载密钥。
  3. 启动校验配置完整性与合法性。
  4. 配置变更经评审发布,记录版本。

代码或图示

Settings(默认)← 环境变量 ← 密钥挂载
启动校验:必填项存在、URL 合法、端口/超时范围

常见误区

  • 配置写死在代码分支判断环境:难维护且易漏改。
  • 密钥提交进仓库或镜像层:泄露面随镜像分发扩散。

追问

  • 多环境配置怎么组织?答:按环境独立配置源,应用工厂按 Settings 实例装配。
  • 配置热更新支持吗?答:常规部署重启生效;需要热更新需设计重载机制并评估连接重建。

04.7.15.5-049 多实例部署与会话/状态如何共享?

一句话结论

应用实例无状态化:会话、令牌吊销、缓存、限流计数、分布式锁放外部存储(Redis/DB);实例间不共享进程内存。WebSocket 广播等跨实例消息经 pub/sub 转发。本地进程状态只做可重建的缓存,实例可随时替换。

概念解释

  • 有状态实例限制弹性扩缩与滚动发布。
  • 外部存储成为共享状态瓶颈,需规划容量与高可用。

原理流程

  1. 识别进程内状态:会话、缓存、登记表、计数器。
  2. 迁移到外部存储或消息通道。
  3. 实例启动从存储加载必要数据,结束释放本地持有。
  4. 扩缩容与发布时实例可任意替换。

代码或图示

多实例 → Redis(会话/黑名单/限流/锁)
       → MQ pub/sub(WebSocket 跨实例广播)
       → DB(持久业务数据)

常见误区

  • 连接登记表留进程内:多实例下消息发不到其他实例连接。
  • 本地缓存当权威状态:实例重启丢失,多实例数据不一致。

追问

  • 外部存储挂了怎么办?答:按降级策略(只读/缓存兜底),高可用部署 Redis/DB。
  • 会话粘性需要吗?答:无状态设计下不需要会话粘性;有状态会话才需粘性路由。

04.7.15.5-050 滚动发布与连接 drain 怎么配合?

一句话结论

滚动发布逐实例替换:旧实例先摘流量(就绪探针失败/负载均衡摘除)→ 排空在途请求 → 关闭资源退出;新实例就绪后再接流量。drain 期间拒绝新连接,等待在途任务完成或达超时,避免发布中断用户请求与事务。

概念解释

  • 发布顺序:先下旧、再上新,避免新旧版本同时承接不确定流量。
  • 长连接(SSE/WS)需主动关闭并让客户端重连到新实例。

原理流程

  1. 编排平台标记旧实例不再接新流量。
  2. 等待在途请求在宽限窗口完成。
  3. lifespan 关闭段释放池与客户端。
  4. 旧实例退出,新实例通过就绪检查后接入。

代码或图示

摘流量 → drain 在途请求 → 释放资源 → 退出
新实例初始化 → 就绪探针通过 → 接入流量

常见误区

  • 旧实例直接强杀:在途事务与长连接被切断。
  • 新实例未就绪就接流量:启动失败/依赖未就绪导致 5xx。

追问

  • 长连接发布怎么处理?答:旧实例关闭 WS/SSE 连接,客户端重连到新实例;发布窗口通知前端重连策略。
  • drain 超时怎么定?答:覆盖 P99 长尾请求时长,长任务走队列不在请求内完成。

04.7.15.5-051 测试覆盖率怎么衡量,为什么不追数字?

一句话结论

覆盖率衡量代码被测试执行的比例,是发现遗漏的辅助指标,不代表断言质量;高覆盖可能只走通路径未校验结果。重点覆盖核心业务分支、错误路径与边界条件,按风险设定覆盖目标,不为凑数字写无效断言。

概念解释

  • 覆盖率工具统计行/分支执行,不检查断言是否充分。
  • 关键链路与高风险模块优先覆盖。

原理流程

  1. 运行测试采集覆盖率数据。
  2. 识别未覆盖的分支与异常路径。
  3. 补充用例并校验断言,而非仅执行代码。
  4. 按模块风险设目标,核心模块覆盖度高于工具类。

代码或图示

pytest --cov=app --cov-report=term-missing

常见误区

  • 追求 100% 行覆盖:低价值 getter/配置类浪费精力。
  • 覆盖了代码但无断言:测试不防回归,覆盖率虚高。

追问

  • 分支覆盖与行覆盖哪个更有意义?答:分支覆盖更能暴露条件路径遗漏,核心模块看分支。
  • 覆盖率下降怎么评审?答:新代码未补测试不合并,缺失分支说明原因。

04.7.15.5-052 单元测试与集成测试边界怎么划?

一句话结论

单元测试隔离业务逻辑,替身外部依赖,快速验证规则与分支;集成测试接真实/测试数据库、应用链路与外部替身,验证装配、配置与端到端行为。核心领域逻辑以单元测试为主,接口与持久化走集成测试,两层互补不互相替代。

概念解释

  • 单元快而多,覆盖分支;集成慢而少,验证真实接线。
  • 依赖注入让两层都能替换外部资源。

原理流程

  1. 领域服务/规则抽成可单测的纯函数/类。
  2. 单元测试 mock 仓储与外部客户端,断言业务规则。
  3. 集成测试通过 TestClient/AsyncClient 走完整链路。
  4. 两层按模块分配比例,接口契约由集成测试覆盖。

代码或图示

单元:服务 + mock 仓储 → 规则/分支/边界
集成:TestClient + 测试库 → 路由/依赖/序列化/持久化

常见误区

  • 全写集成测试:慢、脆弱,定位问题要穿透多层。
  • 全写单元测试:依赖接线与配置错误发现不了。

追问

  • 外部第三方服务怎么测?答:单元测试替身,集成测试用沙箱/录制回放,不依赖生产环境。
  • 测试夹具属于哪层?答:共享夹具服务两层,隔离级别按夹具作用域控制。

04.7.15.5-053 mock 下游外部依赖的边界在哪里?

一句话结论

mock 用于隔离不可控/慢/有副作用的外部依赖(第三方 API、短信、支付),验证本服务调用参数与交互;不要 mock 自己拥有的业务逻辑与数据库核心规则。替身按接口契约构造,记录调用次数与参数,避免过度 mock 导致测试与真实行为脱节。

概念解释

  • mock 验证“怎么调用”,stub 提供“返回什么”。
  • 真实数据库查询、本地业务规则应尽量用真实实现测试。

原理流程

  1. 识别依赖:外部不可控服务优先替身,自有仓储可用测试库。
  2. 定义替身返回样例与异常场景。
  3. 断言本服务发出的请求参数、重试与错误处理。
  4. 关键外部链路另用沙箱/契约测试补充。

代码或图示

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 是同一用例时过时不过,根因多为时序与共享状态。
  • 异步测试必须明确任务边界:哪些等待完成,哪些独立后台。

原理流程

  1. 失败用例复现:加大并发/重复执行定位时序窗口。
  2. 检查断言前是否等待所有相关协程完成。
  3. 消除时间依赖(固定时间/可控 sleep)与共享数据。
  4. 修复后重复跑套件确认稳定。

代码或图示

# 等待后台任务完成再断言
await asyncio.gather(*pending_tasks)

常见误区

  • 用 time.sleep 等待异步任务:时长不够失败,过长拖慢套件。
  • 多测试用例共享同一数据集:执行顺序影响结果。

追问

  • 后台任务怎么在测试中收尾?答:持有任务引用并 await,或用任务组等待;必要时测试专用同步实现。
  • 怎么批量发现 flaky?答:CI 中重复执行套件、记录偶发失败用例并隔离修复。

04.7.15.5-055 生产日志级别与敏感信息脱敏怎么配?

一句话结论

生产默认 info 级别,异常与慢请求 warning/error;调试细节按需临时开启。日志禁止记录密码、令牌、身份证/手机号等敏感信息,必要字段脱敏(掩码/哈希)。结构化字段统一,日志量与级别按环境配置,避免磁盘被刷屏日志打满。

概念解释

  • 日志级别:debug 开发、info 运行、warning 异常苗头、error 失败。
  • 脱敏在日志输出层统一处理,不靠各业务自觉。

原理流程

  1. 配置日志格式、级别与输出目标。
  2. 敏感字段在序列化层掩码或剥离。
  3. 关键事件按级别记录,异常带堆栈与请求 ID。
  4. 监控日志量与错误级别,告警异常增长。

代码或图示

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 不一定要上报为错误。
  • 上下文脱敏:不上报密码、令牌与敏感个人信息。

原理流程

  1. 初始化追踪 SDK,配置服务名、环境、版本。
  2. 异常处理器/中间件捕获未处理异常,附加上下文上报。
  3. 按类型过滤预期业务错误,降低噪声。
  4. 告警关联追踪事件,按 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 便于退避。

概念解释

  • 限流控制到达速率;熔断切断故障下游调用;两者保护对象不同。
  • 部署层配置与应用内限流策略要对齐,不重复冲突。

原理流程

  1. 网关层限制总连接与请求速率。
  2. 应用层按用户/接口配额限流,信号量控制并发。
  3. 下游客户端统计失败率,超阈值熔断并降级。
  4. 故障恢复后半开探测,逐步恢复调用。

代码或图示

网关限流 → 应用速率/并发限制 → 下游熔断/降级
超限:429 + Retry-After;熔断:快速失败 + 兜底响应

常见误区

  • 只在应用层限流:流量在到达应用前已打满连接/CPU。
  • 熔断不设恢复探测:下游恢复后仍长期拒绝调用。

追问

  • 限流计数放哪里?答:分布式配额用 Redis 共享,单机配额用进程内信号量/计数器。
  • 熔断阈值怎么定?答:基于下游历史错误率与响应延迟,压测与线上观测调整。

04.7.15.5-058 静态文件与上传存储在部署中怎么处理?

一句话结论

静态资源(前端构建产物、文档)由 Nginx/CDN 直接服务,应用只挂必要的静态目录;上传文件不存应用本地磁盘,放对象存储或共享卷,多实例共享访问。临时文件用完清理,限制大小与类型,备份与权限在存储层管理。

概念解释

  • 本地磁盘在容器重建/多实例下不可靠,不作为持久存储。
  • 上传链路:接收 → 校验 → 转存外部存储 → 记录元数据。

原理流程

  1. 构建产物部署到静态目录,反代直接返回。
  2. 上传接口校验大小/类型后写入对象存储/共享卷。
  3. 数据库只存文件键与元数据,不存二进制。
  4. 临时文件按策略清理,存储层做备份与访问控制。

代码或图示

from fastapi.staticfiles import StaticFiles

app.mount("/static", StaticFiles(directory="static"), name="static")

常见误区

  • 上传文件写容器本地目录:实例重建丢失,多实例互不可见。
  • 静态目录挂在应用后经 Python 服务:浪费应用进程资源,应反代直出。

追问

  • 大文件上传怎么做?答:分片上传 + 对象存储直传,服务端合并校验。
  • 静态资源缓存策略?答:按内容哈希文件名配长缓存,入口 HTML 短缓存。

04.7.15.5-059 版本升级回归检查清单有哪些?

一句话结论

升级清单:依赖版本兼容矩阵、弃用警告清理、Pydantic/框架 API 迁移、测试套件全绿、文档 schema 生成正常、启动 lifespan 与依赖初始化、核心接口契约、压测基线对比、配置与密钥兼容、灰度回滚方案。跨版本分批升级,不在生产直接跳大版本。

概念解释

  • 回归覆盖:功能正确性、性能基线、配置装配、文档与错误分支。
  • 升级前备份与回滚路径要预先确认。

原理流程

  1. 核对 changelog 与依赖兼容版本,锁定版本范围。
  2. 本地迁移写法,清理 DeprecationWarning。
  3. 跑测试、生成文档、压测对比基线。
  4. 灰度发布观测指标与追踪,保留回滚方案。

代码或图示

兼容矩阵 → 弃用清理 → 测试 → schema 生成 → 启动/依赖 → 契约 → 压测 → 灰度

常见误区

  • 只跑单元测试:集成链路、配置与序列化回归未覆盖。
  • 升级后不对比性能:新版本序列化/调度行为变化可能降低吞吐。

追问

  • 怎么记录升级差异?答:变更清单、测试结果、压测对比与灰度观察项归档。
  • 第三方库不兼容怎么办?答:先升级兼容层,锁定已知可用版本,分批解耦。

04.7.15.5-060 上线前验收检查项汇总有哪些?

一句话结论

验收清单:核心接口通过测试与契约校验;认证授权、错误格式与限流生效;配置/密钥注入正确;健康检查与探针可用;日志、指标、追踪接入;容量按压测规划 worker 与资源;优雅停机与回滚流程确认;文档按环境关闭或保护;敏感信息不进日志与响应;监控告警阈值就位。

概念解释

  • 验收从功能、安全、性能、可观测、发布流程五个维度逐项核对。
  • 每项有可验证结果,不停留在“已完成”描述。

原理流程

  1. 功能与契约:测试套件通过,核心链路手工验证。
  2. 安全:鉴权归属校验、脱敏、文档暴露面、密钥来源。
  3. 性能:worker/资源配置对齐压测基线,限流熔断就位。
  4. 发布可观测:探针、日志、指标、追踪、告警、回滚方案确认。

代码或图示

功能:测试/契约/核心链路
安全:认证授权/脱敏/文档/密钥
性能: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)