FastAPI 依赖覆盖测试指南：用 `app.dependency_overrides` 为外部服务依赖编写可测的替身

在测试 FastAPI 应用时，经常需要绕开那些“不该在测试里真正执行”的依赖（例如每次调用都计费、耗时较长的外部认证服务）。本指南基于官方文档 docs/fr/docs/advanced/testing-dependencies.md 与其对应的英文源文 docs/en/docs/advanced/testing-dependencies.md，系统讲解利用应用自带的 app.dependency_overrides 字典在测试中临时替换依赖的实现原理与完整实操，并结合仓库源码与测试用例说明底层机制。读完你将掌握：什么是依赖覆盖、覆盖何时生效、如何注册与重置覆盖、以及如何在单个测试中精确控制覆盖范围。

为什么要覆盖依赖：先理解典型场景

依赖注入是 FastAPI 的核心能力（详见 docs/fr/docs/tutorial/dependencies/index.md 等教程章节）。但在某些测试场景下，你不希望原始依赖真正运行——包括它可能带出的所有子依赖（sub-dependencies）。你想要的是一份“仅用于测试的替身实现”，它返回的值能在原依赖被消费的位置继续被正常使用。

原文档给出了一个非常典型的用例——外部认证服务：

• 你的应用需要把一个 token 发给外部认证提供方，换取一个已认证用户；
• 该提供方可能按请求计费，而且单次调用可能比直接使用一个固定的 mock 用户更慢；
• 你希望“真正调用外部服务”这件事只发生一次（例如单独验证一次集成），而不是在每个测试中都真实调用它。

解决方案就是：覆盖那个调用外部提供方的依赖，改用一份返回 mock 用户的自定义依赖，且只对测试生效。

核心机制：app.dependency_overrides 就是一个字典

针对上述需求，每个 FastAPI 应用对象上都有一个公开属性 app.dependency_overrides。官方文档明确写到：

它是一个简单的 dict。

使用时遵循一套非常直观的“键值”约定：

• 键（key）：原始依赖，一个可调用对象（通常是一个函数，也可能是类）；
• 值（value）：你的覆盖依赖，另一个可调用对象。

注册完成后，FastAPI 在解析依赖时会调用这个覆盖函数，而不是原始函数。这一属性在 fastapi/applications.py 的 FastAPI.__init__ 中被初始化为空字典，源码注释也确认了它的用途——“每个键是原始依赖可调用对象，值是实际应被调用的依赖，用于测试时把昂贵的依赖替换成测试版本”。

一个完整可运行的示例

以下是仓库中该主题的官方示例代码 docs_src/dependency_testing/tutorial001_an_py310.py（使用 Annotated 风格）：

from typing import Annotated

from fastapi import Depends, FastAPI
from fastapi.testclient import TestClient

app = FastAPI()


async def common_parameters(q: str | None = None, skip: int = 0, limit: int = 100):
    return {"q": q, "skip": skip, "limit": limit}


@app.get("/items/")
async def read_items(commons: Annotated[dict, Depends(common_parameters)]):
    return {"message": "Hello Items!", "params": commons}


@app.get("/users/")
async def read_users(commons: Annotated[dict, Depends(common_parameters)]):
    return {"message": "Hello Users!", "params": commons}


client = TestClient(app)


async def override_dependency(q: str | None = None):
    return {"q": q, "skip": 5, "limit": 10}


app.dependency_overrides[common_parameters] = override_dependency


def test_override_in_items():
    response = client.get("/items/")
    assert response.status_code == 200
    assert response.json() == {
        "message": "Hello Items!",
        "params": {"q": None, "skip": 5, "limit": 10},
    }


def test_override_in_items_with_q():
    response = client.get("/items/?q=foo")
    assert response.status_code == 200
    assert response.json() == {
        "message": "Hello Items!",
        "params": {"q": "foo", "skip": 5, "limit": 10},
    }


def test_override_in_items_with_params():
    response = client.get("/items/?q=foo&skip=100&limit=200")
    assert response.status_code == 200
    assert response.json() == {
        "message": "Hello Items!",
        "params": {"q": "foo", "skip": 5, "limit": 10},
    }

仓库同时还提供了等价的“无 Annotated”版本 docs_src/dependency_testing/tutorial001_py310.py，写法为 commons: dict = Depends(common_parameters)，两种风格下覆盖机制完全一致。

示例中有三个关键点值得逐条拆解：

1. 测试替身固定返回值：override_dependency 不论原请求带了什么，都返回 {"q": ..., "skip": 5, "limit": 10}，其中 q 仍从查询参数透传，而 skip/limit 被强制固定。
2. 覆盖注册发生在模块顶层：app.dependency_overrides[common_parameters] = override_dependency 一行让后续所有经由 client 发起的请求都命中替身。
3. 断言验证覆盖生效：/items/?q=foo&skip=100&limit=200 这种“参数带满”的请求，响应里依然是 skip: 5, limit: 10——如果走的是原依赖，这里应返回 100/200。这正说明原始依赖根本没有执行。

覆盖是如何被查找到的：源码级机制

从源码看，覆盖查找发生在请求处理的依赖求解阶段，核心实现位于 fastapi/dependencies/utils.py 的 solve_dependencies() 函数：

if (
    dependency_overrides_provider
    and dependency_overrides_provider.dependency_overrides
):
    original_call = sub_dependant.call
    call = getattr(
        dependency_overrides_provider, "dependency_overrides", {}
    ).get(original_call, original_call)
    use_path: str = sub_dependant.path
    use_sub_dependant = get_dependant(
        path=use_path,
        call=call,
        name=sub_dependant.name,
        parent_oauth_scopes=_get_oauth_scopes(dependant=sub_dependant),
        scope=sub_dependant.scope,
    )

这段代码揭示了三点实现事实：

• 查找键是函数对象本身：solve_dependencies 以被注册的依赖可调用对象（sub_dependant.call，也就是你传给 Depends(...) 的那个函数）为键，在 dependency_overrides 字典中做精确查找（.get(original_call, original_call)）；找不到就回退到原函数。因此注册覆盖时，必须使用与 Depends(common_parameters) 中完全相同的函数对象作为键。
• 覆盖后依赖会被重新解析：命中覆盖后，FastAPI 会用覆盖函数调用 get_dependant() 重建一个 Dependant。这意味着覆盖函数自身的参数声明同样会被校验、解析，覆盖函数若还声明了它自己的子依赖，这些子依赖也会被递归求解。
• “provider”是可传递的：所谓 dependency_overrides_provider 就是创建路由时绑定到应用上的“覆盖提供者”（见 fastapi/applications.py，创建 self.router 时传入了 dependency_overrides_provider=self）。调用 include_router() 时，这个 provider 也会沿路由器传播给被包含的路由（相关逻辑见 fastapi/routing.py 一带），这正是“覆盖能对整棵应用树生效”的底层原因。

原依赖可以出现在哪些位置？覆盖都能生效

文档中的 tip 特别强调：只要某个依赖被用于 FastAPI 应用中的任何位置，你都可以为它设置覆盖，包括：

• 路径操作函数的参数：async def read_items(commons: ... = Depends(common_parameters))；
• 路径操作装饰器（不消费返回值时）：@app.get("/decorator-depends/", dependencies=[Depends(common_parameters)])；
• .include_router() 调用所带来的路由及其装饰器依赖；
• 还可以推断：其他依赖内部的子依赖同样会被覆盖——因为 solve_dependencies 对整个依赖树逐层递归求解，每一层子依赖都会执行上述查找逻辑。

仓库测试文件 tests/test_dependency_overrides.py 对该结论给出了直接验证。它在同一个 app 上挂载了四条路径：

• /main-depends/：路径操作函数参数中声明依赖；
• /decorator-depends/：路径操作装饰器 dependencies=[...] 中声明依赖；
• /router-depends/：经 include_router 加入的路由，在函数参数中声明依赖；
• /router-decorator-depends/：经 include_router 加入的路由，在装饰器中声明依赖。

覆盖注册后，参数化测试 test_override_simple 断言这四种位置全部返回了替身给出的 {"skip": 5, "limit": 10}，证明覆盖与依赖的“挂载位置”无关。

重置覆盖：恢复原始依赖

覆盖是全局的字典状态，测试结束后必须清理，否则会污染后续测试。官方文档给出的重置方法是把 app.dependency_overrides 重新赋值为一个空字典：

app.dependency_overrides = {}

从源码角度也很好理解：solve_dependencies 的查找被包裹在 if dependency_overrides_provider.dependency_overrides: 条件中（空字典为假值），所以清空字典后，所有依赖查找都会回退到原始函数。

仓库测试中还能看到两种更精细的做法：

• 在 tests/test_dependency_overrides.py 的每个测试函数末尾执行 app.dependency_overrides = {} 复位；
• 在 tests/test_tutorial/test_testing_dependencies/test_tutorial001.py 的 test_normal_app 中，通过 app.dependency_overrides = None 关闭覆盖后，/items/?q=foo&skip=100&limit=200 恢复了原始行为（返回 100/200），从反面验证了覆盖确实在生效。

只在部分测试中启用覆盖的推荐写法

文档给出的建议是：如果只想在个别测试中覆盖依赖，就在该测试函数的开头设置覆盖，在函数结尾重置。也就是说，把覆盖的“生命周期”收窄到单个测试内部，避免影响同模块里的其他测试。

下面把“设置—执行—清理”写成标准模式（结合文档语义的实践写法，可运行于任何 TestClient 场景）：

from fastapi.testclient import TestClient

client = TestClient(app)


def test_auth_with_mock_user():
    # 1. 测试开头：注册覆盖，用假用户替换真实的外部认证提供方
    app.dependency_overrides[get_current_user] = fake_get_current_user
    try:
        response = client.get("/users/me")
        assert response.status_code == 200
        assert response.json() == {"username": "fake-user"}
    finally:
        # 2. 测试结尾：无论断言成败都重置覆盖
        app.dependency_overrides = {}

使用 try/finally 可以保证即使断言抛错，覆盖也会被清理，避免污染后续测试。此处 get_current_user 是原始的认证依赖（会真实调用外部服务），fake_get_current_user 则是返回固定 mock 用户的替身——这正是文档描述的“外部认证提供方”用例在代码层的落点。

覆盖函数的签名与子依赖：一个易踩的细节

因为命中覆盖后 FastAPI 会用覆盖函数重新解析依赖，所以覆盖函数自身若有必填参数或自己的子依赖，这些参数在请求中同样必须被满足。这一点有仓库测试作为依据：tests/test_dependency_overrides.py 用如下覆盖函数测试：

async def overrider_sub_dependency(k: str):
    return {"k": k}


async def overrider_dependency_with_sub(msg: dict = Depends(overrider_sub_dependency)):
    return msg

当 common_parameters 被替换为 overrider_dependency_with_sub 后：

• 请求不带 ?k=... 时返回 422，错误位置指向 ["query", "k"]——覆盖函数自己的子依赖 overrider_sub_dependency 要求必填参数 k；
• 请求带 ?k=bar 时返回 200，路径操作函数收到的 params 变成了 {"k": "bar"}，即覆盖链上所有依赖按新签名重新求解的结果。

这提醒测试编写者：覆盖函数的参数签名决定了测试请求需要携带哪些参数，设计替身时应尽量使其签名与消费方期望的返回值结构对齐，或提供无必填参数的宽松签名。

覆盖只影响运行时，不影响已生成的 API 文档

从代码位置可以推断一个重要特性：依赖覆盖的查找发生在请求处理期的 solve_dependencies（运行时依赖求解）阶段，而 OpenAPI 模式是在应用启动构造路由时基于原始依赖声明生成的（见 fastapi/applications.py 的 openapi() 相关路径）。因此注册/重置覆盖不会改写已生成的 OpenAPI 文档与 Swagger UI 中的参数定义——测试替身不会“漏”到 API 文档里，二者互不干扰。

延伸阅读与本仓库中的相关佐证

• 覆盖依赖的官方测试集：由 tests/test_tutorial/test_testing_dependencies/test_tutorial001.py 直接运行文档示例中的各个 test_* 函数（同时参数化覆盖 _py310 与 _an_py310 两个变体），是验证本主题行为的权威回归测试；
• 依赖注入基础：docs/fr/docs/tutorial/dependencies/index.md；
• 结合 TestClient 做整体 API 测试：docs/fr/docs/tutorial/testing.md；
• 覆盖机制还常与事件钩子、WebSocket 测试结合使用，见 docs/fr/docs/advanced/testing-events.md 与 docs/fr/docs/advanced/testing-websockets.md；
• 涉及数据库替换等更实际用例可参考 docs/fr/docs/how-to/testing-database.md。

核心结论一句话总结：app.dependency_overrides 是一张“原函数 → 替身函数”的字典，键是被 Depends 引用的原始可调用对象，值是为测试准备的替身；FastAPI 在每次请求的依赖求解阶段按对象精确查找，命中即用替身重建依赖，清空字典即可一键还原。 把这条机制用好，就能让昂贵的、有副作用的、需要真实环境的外部依赖在绝大多数测试中被安全地“隐身”，只留下稳定可控的替身行为。