Python：FastAPI Annotated Depends：Annotated 写法的现代依赖注入

一、问题起点：为什么旧写法开始「不够用」

在 FastAPI 早期版本中，声明依赖的标准写法是把 Depends() 放在函数参数的默认值位置：

from fastapi import FastAPI, Depends

app = FastAPI()

def get_db():
    ...

@app.get("/items/")
def read_items(db = Depends(get_db)):
    ...

这段代码能跑，但它埋下了三个结构性隐患。第一，db 参数丢失了类型注解，IDE 无法推断 db 的真实类型，自动补全和类型检查形同虚设。第二，默认值位置被 Depends() 占用，导致无法再为参数设置真正的默认值语义。第三，也是更隐蔽的一点：依赖信息藏在「运行时求值的默认值」里，静态分析工具（mypy、pyright）在解析函数签名时看到的是一个 Depends 实例，而非类型信息，因此无法对依赖链做任何静态校验。

笔者认为，旧写法的根本矛盾在于「依赖是一种类型层面的契约，却被表达成了值层面的默认值」。这种错位在小型项目里无伤大雅，但一旦依赖层级加深、依赖项被跨模块复用，维护成本会呈非线性上升。FastAPI 官方文档在 0.95.0 版本发布说明中明确将 Annotated 写法列为推荐方式，并指出旧写法在可读性与工具支持上的局限（来源：FastAPI 官方 Release Notes 0.95.0，2023）。

本文评述：把依赖从「默认值」搬到「类型元数据」，本质上是把依赖关系从「运行时才知道」提前到「静态可分析」。这与 Python 类型系统整体演进方向一致——PEP 484 引入类型注解、PEP 593 引入 Annotated、PEP 604 统一联合类型语法，都在做同一件事：让更多语义在类型层面可表达、可检查。

二、理论根基：PEP 593 与 Annotated 的语义边界

2.1 Annotated 到底做了什么

PEP 593（Flexible function and variable annotations，Python 3.9 引入）定义了 typing.Annotated。其形式为 Annotated[T, x, y, ...]，其中 T 是真实类型，后续参数是任意元数据。关键语义是：类型检查器只关心 T，元数据对类型系统透明，但可在运行时被读取。

这意味着 Annotated[User, Depends(get_current_user)] 对 mypy 而言就是一个 User 类型，而 FastAPI 在运行时通过 get_type_hints(include_extras=True) 读取到 Depends(get_current_user) 这段元数据，从而完成依赖注入。

2.2 元数据的读取机制

FastAPI 内部通过 typing.get_type_hints(func, include_extras=True) 获取带元数据的注解。若不加 include_extras=True，Python 会默认剥离 Annotated 的元数据，只返回 T。这是很多手写依赖解析器时容易踩的坑。本文评述：理解这一点，就能明白 Annotated 依赖注入并非「魔法」，而是「标准类型系统 + 运行时反射」的组合，其可靠性完全建立在 Python 官方类型机制之上。

延伸阅读可参考 Python 官方文档 typing 模块中 Annotated 的说明，以及 PEP 593 原文（https://peps.python.org/pep-0593/）。

三、FastAPI 依赖解析的内部机制

3.1 依赖解析的四个阶段

FastAPI 在应用启动或路由注册时，会对每个路径操作函数做一次依赖图构建。这个过程大致分为四步：

1. 签名提取：通过 inspect.signature 获取函数参数列表。
2. 注解解析：调用 get_type_hints(include_extras=True) 拿到含元数据的类型。
3. 依赖识别：遍历元数据，识别出 Depends、Security 等标记，递归解析其依赖函数。
4. 求解器构建：生成一个可缓存的依赖求解结构，请求到来时按拓扑序执行。

值得注意的是，依赖图在应用启动阶段就基本确定，请求期只做「执行」而非「解析」，这也是 FastAPI 依赖注入性能较好的原因之一。

3.2 依赖缓存与作用域

FastAPI 默认对同一请求内的同一依赖做缓存（use_cache=True）。当依赖被多个子依赖引用时，只执行一次。这一点在 Annotated 写法下行为完全一致，因为缓存逻辑作用在依赖求解层，与声明语法无关。

from typing import Annotated
from fastapi import Depends

def get_db():
    ...

DB = Annotated[Session, Depends(get_db)]

def get_user(db: DB):
    ...

def get_order(db: DB):
    ...

上例中 get_user 与 get_order 共享同一个 get_db 依赖，在同一请求内只会打开一次数据库会话。笔者认为，这正是 Annotated 别名写法最大的工程价值——它把「依赖契约」变成了一个可命名、可导入、可复用的类型对象。

四、迁移路径：从默认值写法到 Annotated 写法

4.1 最小迁移步骤

对于存量项目，建议按以下步骤渐进迁移，避免一次性大改引入回归风险：

1. 升级 FastAPI 至 0.95.0 以上，确保支持推荐写法。
2. 在项目中新增 dependencies.py，集中定义依赖别名。
3. 按模块逐个替换，优先替换被复用最多的依赖。
4. 开启 mypy 或 pyright 严格模式，验证类型推断是否生效。
5. 补充针对依赖覆盖（dependency_overrides）的测试。

4.2 对照改写示例

需要特别说明的是「带默认值」这一行：旧写法中默认值位置被 Depends() 占用，若还想给参数一个业务默认值就非常别扭；Annotated 写法把依赖放进类型元数据，默认值位置被彻底释放，这是很多团队迁移后才体会到的一个「意外收益」。

五、工程实践：依赖别名、分层与可复用契约

5.1 依赖别名：把契约变成类型

Annotated 写法最实用的模式是定义依赖别名。官方文档给出的范式是：

from typing import Annotated
from fastapi import Depends, FastAPI

app = FastAPI()

def get_current_user(token: str):
    ...

CurrentUser = Annotated[User, Depends(get_current_user)]

@app.get("/me")
def read_me(user: CurrentUser):
    return user

这样 CurrentUser 就成了一个可跨模块导入的「依赖契约类型」。本文评述：这相当于在 Python 类型系统里给依赖关系做了一次「命名抽象」，其意义类似领域驱动设计中把隐式概念显式化为值对象。

5.2 分层架构中的依赖组织

在中大型项目中，建议按「基础设施依赖 → 领域依赖 → 接口依赖」三层组织：

• 基础设施层：数据库会话、缓存客户端、消息队列连接。
• 领域层：当前用户、租户上下文、权限校验结果。
• 接口层：分页参数、排序参数、过滤条件。

每层各自定义 Annotated 别名，接口层只导入自己需要的别名，从而在类型层面就形成了清晰的依赖边界。笔者认为，这种组织方式让「谁能依赖谁」不再只靠代码评审约束，而是可以被静态工具部分验证。

5.3 与依赖覆盖的配合

测试时常用的 app.dependency_overrides 在 Annotated 写法下依然有效，因为覆盖的键仍是原始依赖函数对象。这一点保证了迁移的向后兼容性。

def fake_get_db():
    return FakeSession()

app.dependency_overrides[get_db] = fake_get_db

六、可测性与性能实测

6.1 可测性提升

Annotated 写法对可测性的提升主要体现在两点：一是依赖别名可被直接导入并覆盖，测试代码更集中；二是类型信息完整，测试中对返回值的断言能被类型检查器辅助校验。本文评述：可测性的本质是「替换成本」，Annotated 把依赖替换点从散落的默认值收敛为集中的别名定义，替换成本显著下降。

6.2 性能对比（模拟数据）

需要说明的是，以下数据为笔者在本地环境整合的模拟测试数据，用于说明量级差异，并非官方基准，实际结果会随版本与硬件变化。

从量级上看，两种写法在运行时性能上几乎没有差异，因为依赖解析逻辑相同，差别只在声明阶段。真正的收益在开发体验与静态可维护性上。笔者认为，把 Annotated 迁移当成「性能优化」是方向性误判，它本质是一次「可维护性投资」。

七、常见陷阱与反模式清单

• 忘记 include_extras：手写解析器时若调用 get_type_hints 不加参数，元数据会被剥离。
• 别名命名混乱：建议统一后缀，如 CurrentUser、DB、Pagination，避免同名不同义。
• 在别名里塞业务逻辑：别名应只做声明，逻辑放在依赖函数里。
• 过度抽象：只为一次性使用的依赖定义别名，反而增加跳转层级。
• 忽略循环依赖：Annotated 写法不会自动解决循环依赖，仍需人工拆分。

八、前沿预判：类型元数据驱动的框架演进

把依赖放进类型元数据，打开了一个更大的想象空间。本文评述：未来框架很可能基于 Annotated 元数据做更多「声明式」能力，例如自动生成 OpenAPI 扩展、自动注入可观测性埋点、自动做权限矩阵校验。这些能力在旧写法下很难实现，因为元数据位置被默认值占用，语义空间有限。

从生态看，Pydantic v2 与 FastAPI 的深度整合也在强化「类型即契约」的方向。可以合理预判，围绕 Annotated 的工具链（静态检查插件、依赖图可视化、契约测试生成）会逐步丰富。笔者认为，掌握 Annotated 写法不仅是跟上 FastAPI 的推荐实践，更是为未来类型驱动开发做好准备。

九、结论与行动清单

1. 升级 FastAPI 到 0.95.0 以上，确认官方推荐写法。
2. 集中定义依赖别名，形成可复用的类型契约。
3. 按模块渐进迁移，配合 mypy/pyright 验证。
4. 补充依赖覆盖测试，保证可测性不回退。
5. 把别名按基础设施/领域/接口三层组织。

主要参考文献

1. FastAPI Release Notes 0.95.0, 2023.
2. PEP 593 – Flexible function and variable annotations, Python Software Foundation.
3. FastAPI Official Documentation – Dependencies, 2024.
4. Pydantic v2 Documentation, 2024.
5. mypy Documentation – Annotated types, 2024.
6. Python typing 模块官方文档, 2024.
7. Starlette Documentation – Dependency Injection, 2024.
8. Real Python – FastAPI Dependency Injection Guide, 2024.
9. TestDriven.io – Modern FastAPI Patterns, 2024.