FastAPI 依赖覆盖测试指南：用 app.dependency_overrides 以 Mock 依赖替换昂贵的外部服务调用

在 FastAPI 的测试体系中，直接让测试命中真实的外部依赖（认证服务、付费 API、慢速第三方接口）既慢又贵。本篇指南讲解 app.dependency_overrides 这一官方提供的测试机制：如何注册依赖覆盖、它为什么能作用于应用中任意位置的依赖声明、以及如何在测试结束后正确重置覆盖，并结合仓库源码说明覆盖生效的底层调用链。读完本文，你将掌握在不修改业务代码的前提下，为任意依赖注入 Mock 实现并用 TestClient 验证其行为的完整方案。

测试中为什么需要覆盖依赖

FastAPI 的依赖注入系统允许把公共逻辑（参数解析、认证、数据库会话等）抽成函数，通过 Depends 注入到路由函数、路由装饰器参数或 .include_router() 调用中。但在测试场景下，有些依赖不应被执行，原因通常包括：

• 成本：例如你接入了一个外部认证提供方——把 Token 发过去，换回一个已认证用户。如果该提供方按请求计费，那么每一条测试请求都在花钱；
• 速度：外部网络调用的延迟远大于返回一个预定义好的 Mock 用户；
• 隔离性：你只想对那个提供方做一次真实的集成验证，而不是在每个单元测试里都调用它。

典型的处理方式是：保留一条"真实调用一次"的集成测试，而在其余测试中用一条覆盖规则把该依赖替换成返回 Mock 数据的函数，且仅在测试期间（甚至只在某些特定测试期间）生效。

app.dependency_overrides：一个简单的字典

为支持上述场景，FastAPI 应用提供了一个属性 app.dependency_overrides，它是一个普通的 dict（字典）。使用方式只有两条规则：

• 键（key）：原始依赖（一个函数）；
• 值（value）：用于覆盖它的函数（另一个函数）。

之后 FastAPI 在解析依赖时会调用你的覆盖函数，而不是原始依赖。

在源码中，该属性定义于 FastAPI 应用构造函数：

self.dependency_overrides: Annotated[
    dict[Callable[..., Any], Callable[..., Any]],
    Doc(
        """
        A dictionary with overrides for the dependencies.

        Each key is the original dependency callable, and the value is the
        actual dependency that should be called.

        This is for testing, to replace expensive dependencies with testing
        versions.
        ...
        """
    ),
] = {}

其类型标注清楚地说明了键值语义：键是"原始依赖 callable"，值是"真正被调用的依赖 callable"，初始值为空字典 {}。构造函数同时把应用自身传入主路由：routing.APIRouter(..., dependency_overrides_provider=self, ...)——也就是说，应用实例就是所有路由的"覆盖提供方"，这正是覆盖能作用于任意位置依赖的原因。

提示：你可以为在 FastAPI 应用的任何位置被使用的依赖设置覆盖。原始依赖可能是：

• 某条路径操作函数（路径操作函数）中的参数依赖；
• 某个路径操作装饰器参数（dependencies=[...]，即使你不使用其返回值）；
• 某个 .include_router() 调用上的依赖；
• 等等。

无论原始依赖声明在哪一层，FastAPI 都可以将其覆盖。仓库测试 tests/test_dependency_overrides.py 中的用例覆盖了路径操作依赖、装饰器级依赖（/decorator-depends/）和路由级依赖（/router-depends/），验证了这些位置都会命中覆盖规则。

完整示例：覆盖一个公共参数依赖

以下代码来自官方文档示例 docs_src/dependency_testing/tutorial001_an_py310.py（另有非 Annotated 风格版本 tutorial001_py310.py），它在一个文件里同时定义了应用和测试，可直接运行验证：

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},
    }

示例要点拆解：

1. common_parameters 是原始依赖：接收查询参数 q、skip、limit 并原样返回一个字典。它同时被 /items/ 和 /users/ 两个路由使用；
2. override_dependency 是覆盖函数：它只接收 q 参数，skip 和 limit 则被硬编码为 5 和 10。注意覆盖函数可以有自己不同的签名——测试中 ?skip=100&limit=200 这类参数会被覆盖函数直接忽略，最终响应里的值永远是 {"skip": 5, "limit": 10}；
3. app.dependency_overrides[common_parameters] = override_dependency 一行完成注册：以原始函数对象为键、覆盖函数为值；
4. 三个测试分别验证了：无参请求、仅传 q 请求、传齐 q/skip/limit 三种情况下，覆盖均生效且 skip/limit 固定为覆盖函数的返回值。

底层实现：覆盖是在依赖求解阶段动态查表的

覆盖为什么能生效？答案在依赖求解函数 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  # type: ignore
    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,
    )

从源码结构看，可以得出三个关键结论：

• 查表时机是每次请求解析依赖时，而非应用启动时。因此你可以在测试运行中途随时修改 app.dependency_overrides，下一个请求立即使用新规则，这也是"按单个测试设置/重置覆盖"可行的底层原因；
• 查不到则原样执行：.get(original_call, original_call) 表示若字典中没有该键，就回落到原始依赖，行为与未开启覆盖完全一致；
• 覆盖函数会被重新做一次依赖解析：命中覆盖后，get_dependant(call=call, ...) 用覆盖函数重建了一个 Dependant。这意味着覆盖函数自身也可以声明子依赖（比如从请求读取 k: str 参数），其参数校验规则按覆盖函数自己的签名生效。仓库测试 tests/test_dependency_overrides.py 中 test_override_with_sub_* 系列用例验证了这一点：带子依赖的覆盖函数在缺少必需参数时会返回 422 校验错误。

此外，由于 solve_dependencies 是递归的，且递归时透传了同一个 dependency_overrides_provider，覆盖不仅作用于直接依赖，也会递归地作用于被依赖的依赖树中的任意一层。

重置覆盖：恢复原始依赖

测试结束后（或某一批测试结束后），把 app.dependency_overrides 设为空字典即可移除全部覆盖：

app.dependency_overrides = {}

提示：如果你只想在某些测试期间覆盖某个依赖，可以在测试开始处（测试函数内部）设置覆盖，在测试结束处（测试函数末尾）重置它。仓库对教程示例的验证测试 tests/test_tutorial/test_testing_dependencies/test_tutorial001.py 正是这一思路的体现：前若干用例断言 /items/ 与 /users/ 的响应都命中了 override_dependency（skip: 5, limit: 10），而最后一个 test_normal_app 用例将覆盖清空后再次请求，断言 ?q=foo&skip=100&limit=200 被原样返回——证明重置后应用恢复使用原始依赖。

实践建议小结

• 键必须是函数对象本身：app.dependency_overrides[common_parameters] = ... 中写入的是可调用的函数引用，而不是字符串名称或 Depends() 实例；
• 覆盖函数签名自由：它只接收它自己声明的参数，原始依赖的参数定义（默认值、校验）对覆盖函数不再生效；
• 覆盖范围是全局的：只要该函数在任何地方被 Depends 引用（路由参数、路由装饰器、include_router），都会被替换；
• 覆盖是进程内状态：它只影响共享同一个 app 实例的测试。TestClient(app) 与生产服务器使用同一个字典，因此务必在测试中及时重置，避免覆盖"泄漏"到后续用例；
• 与 dependency_overrides_provider 的关系：源码中路由持有的是"提供方"引用（fastapi/applications.py 中 APIRouter 以 dependency_overrides_provider=self 构建），所以读取的始终是 app.dependency_overrides 当前的值——覆盖在每次请求时实时生效，这也是测试中逐用例切换覆盖的可靠基础。

至此，app.dependency_overrides 的完整使用链路为：定义原始依赖 → 在测试中注册覆盖 → TestClient 发请求验证 Mock 行为 → 重置字典恢复原状。配合仓库中的源码与测试（fastapi/dependencies/utils.py、tests/test_dependency_overrides.py），你可以进一步验证覆盖在装饰器级、路由级以及带子依赖等边界场景下的行为。