FastAPI 依赖项系统理论笔记

1. 依赖项的基本概念

在 FastAPI 中，依赖项（Dependencies）是指可以在路径操作函数（Path Operation Functions）中声明并执行的函数或类，它们主要用于提取请求参数、处理验证、提供预处理的数据等。依赖项系统为应用程序提供了一种干净、可重用的方式来解耦请求处理逻辑，并将复杂的业务逻辑与路径操作函数分离。

• 功能与目的：依赖项的核心目的是为了简化和复用代码。通过将常见的操作抽象成依赖项，开发者可以避免重复编写相似的代码，集中管理业务逻辑。
• 作用范围：依赖项不仅可以被路径操作函数所调用，也可以被嵌套、复用，甚至在应用级别统一管理。

2. 依赖项的声明与使用

FastAPI 中的依赖项通常通过函数或类的方式来声明，开发者通过 Depends() 语法将依赖项与路径操作函数的参数关联起来。

• 路径操作函数中的依赖项：在路径操作函数中声明的依赖项通常用于从请求中提取信息或执行某些前置操作，如验证用户身份、获取请求参数等。

  • 声明依赖项：依赖项通过函数的参数来声明，FastAPI 自动解析这些依赖项，并将解析结果传递给路径操作函数。

• 嵌套依赖项：FastAPI 支持依赖项的嵌套。一个依赖项可以依赖于另一个依赖项，FastAPI 会负责解析这些依赖项的执行顺序，并将结果传递给需要的地方。通过这种方式，开发者可以将复杂的逻辑拆分成多个小的、单一职责的部分，从而提高代码的可读性和可维护性。

3. 依赖项的缓存机制

FastAPI 中的依赖项有缓存机制，避免了同一请求中多次执行同一个依赖项。具体来说，对于每个请求，FastAPI 会在首次执行某个依赖项时保存该依赖项的结果，并将该结果传递给其他需要该结果的依赖项。

• 避免重复执行：如果多个依赖项共用同一个子依赖项，FastAPI 会在同一次请求中只调用一次该子依赖项，避免重复调用，提升性能。
• 缓存禁用：在某些情况下，开发者可能希望每次都执行某个依赖项，即使是同一个请求中的多次调用。此时，可以通过设置 Depends 的 use_cache=False 参数来禁用缓存。

4. 路径装饰器依赖项

FastAPI 提供了在路径装饰器中使用 dependencies 参数来声明依赖项的功能。这些依赖项与普通依赖项的执行方式相同，但其返回值不会传递给路径操作函数，而是仅用于执行某些前置操作，如身份验证、授权检查等。

• 目的与场景：路径装饰器依赖项主要用于执行那些不需要返回值的操作。例如，身份验证、权限检查等，这些操作可能会抛出异常，但不需要将任何数据传递给路径操作函数。
• 避免错误提示：某些编辑器会检查未使用的函数参数并显示警告或错误。通过将依赖项放入 dependencies 中，可以避免这一问题，即使这些依赖项的返回值不会直接传递到路径操作函数中。

5. 应用级依赖项

FastAPI 允许在应用层面为整个应用设置统一的依赖项。通过在 FastAPI 应用实例中传递 dependencies 参数，可以确保所有的路径操作函数都会执行这些依赖项。

• 全局适用性：应用级依赖项适用于需要对所有请求进行统一处理的场景。例如，身份验证、API 访问控制、日志记录等。
• 优点：使用应用级依赖项，可以确保所有路径操作都遵循相同的前置处理规则，从而避免遗漏或重复设置相同的逻辑。

6. 依赖项的异常处理

依赖项不仅可以返回结果，还可以抛出异常。依赖项抛出的异常会被 FastAPI 捕获并转换为 HTTP 响应，从而将错误信息传递给客户端。这种机制使得依赖项能够处理业务中的各种错误条件，如验证失败、权限不足等。

• 自定义异常：开发者可以在依赖项中根据需求自定义抛出的异常，例如使用 HTTPException 来返回特定的 HTTP 状态码和错误信息。
• 异常传递：如果一个依赖项在执行时抛出了异常，FastAPI 会终止该请求并返回对应的错误响应，其他依赖项将不会被继续执行。

7. 依赖项与测试

依赖项的设计使得 FastAPI 特别适合进行单元测试和集成测试。由于依赖项是解耦的，测试时可以通过依赖注入的方式替换掉实际的依赖项，从而让测试更加专注于路径操作本身。

• 模拟依赖项：在测试时，开发者可以通过模拟（mocking）依赖项来替换实际的依赖项，确保测试环境中的行为符合预期。
• 控制依赖项的执行：通过依赖项系统，开发者可以精确控制在测试中需要执行哪些依赖项，并验证它们的行为。