litestar-dependency-injection

依赖注入

执行工作流

1. 首先选择要注入的契约：设置对象、服务、存储库、会话、当前用户或请求派生值。
2. 选择应负责管理它的最小作用域：应用、路由器、控制器或处理程序。
3. 将提供器实现为用 Provide 包装的可调用对象，并根据生命周期需求选择异步、同步或生成器形式。
4. 确保依赖项键与注入参数名称完全一致。
5. 在较低作用域和测试中有意使用覆盖。
6. 当验证、默认值或 OpenAPI 行为需要明确指定时，使用 Dependency(...) 标记特殊情况。
7. 验证生成器依赖项的清理行为，以及缺少显式依赖项时是否会在启动阶段失败。

核心规则

• 在与复用边界匹配的最小作用域注册依赖项。
• 保持依赖项键稳定且具有描述性：settings、db_session、current_user、tenant、clock。
• 确保注入类型的注解在运行时可导入。除非同时提供可用的运行时签名命名空间，否则避免通过 TYPE_CHECKING 隐藏注入类型。
• 提供器应接受关键字参数和 self，不得使用仅限位置参数的运行时参数。
• 确保提供器键与使用方参数名称完全一致。
• 优先注入服务和存储库，而不是原始传输对象；除非该依赖项明确来自请求。
• 避免隐藏的可变单例。如果必须共享状态，应明确其生命周期和可变性。

作用域选择

Litestar 从外层到内层解析依赖项；当相同键被重复使用时，较低作用域会覆盖较高作用域。

• 应用作用域：全局设置、共享客户端、顶层服务工厂。
• 路由器作用域：在相关路由间共享的功能领域依赖项。
• 控制器作用域：控制器本地服务或授权上下文。
• 处理程序作用域：单个端点的自定义设置和本地覆盖。

选择仍与复用边界匹配的最低作用域。重复使用相同的键是有意设定的覆盖契约，而非偶然的命名结果。

提供器选择

• 对于自然采用异步方式的 I/O 密集型工作，使用异步提供器。
• 仅当工作确实是同步的，才使用同步提供器。
• 对于阻塞 I/O 或 CPU 密集型同步提供器，设置 sync_to_thread=True。
• 对于开销小且不会阻塞的同步提供器，设置 sync_to_thread=False，以表明意图并避免警告。
• 当设置和清理属于同一个逻辑资源时，使用生成器提供器。
• 当需要在构造时配置、但调用仍应由 DI 管理时，使用可调用实例。

参考文件

只阅读所需章节：

• 有关作用域示例、提供器形式、请求派生值、yield 清理、覆盖、缓存、嵌套依赖关系图和服务装配模式，请阅读 references/provider-patterns.md。
• 有关 Annotated[..., Dependency(...)] 的用法、验证控制、兼容 OpenAPI 的默认值，以及快速失败的显式依赖项标记，请阅读 references/dependency-markers.md。

推荐默认设置

• 除非提供器可信，且性能或类型系统方面的权衡确有依据，否则保持启用验证。
• 保持依赖关系图足够浅，以便快速理解。
• 组合稳定的层：设置 -> 客户端/会话 -> 存储库 -> 服务。
• 使用请求派生提供器，作为将传输输入转换为领域类型的边界。
• 在测试中复用相同的依赖项键，以便替换为伪对象，而无需改动处理程序代码。

反模式

• 为了方便，把所有内容都注册在应用级作用域。
• 将依赖用作不透明的服务定位器，并使用 dep1 这类含义不清的名称。
• 从提供器返回可变的全局单例，并针对每个请求修改它们。
• 在同步提供器中执行阻塞 I/O，却没有设置 sync_to_thread=True。
• 广泛使用 skip_validation=True，而不是修正类型边界。
• 在处理程序中重复查找逻辑，而这些逻辑本应由基于请求的提供器负责。

验证清单

• 确认每个注入参数的名称都与已注册的依赖项键匹配。
• 确认所选作用域符合复用和覆盖需求。
• 确认同步提供器声明了正确的 sync_to_thread 行为。
• 确认生成器依赖始终会关闭，包括发生异常时。
• 确认嵌套的提供器依赖图易于阅读和测试。
• 确认当备用依赖项必须排除在 OpenAPI 之外时，使用了 Dependency(default=...)。
• 确认显式的 Dependency() 标记能在启动时捕获缺失的必需接线。
• 确认测试可以干净地覆盖依赖项键，而无需猴子补丁修改内部实现。

跨技能交接

• SQLAlchemy 或 Piccolo 会话的提供请使用 litestar-databases。
• 依赖项覆盖模式和基于客户端的验证请使用 litestar-testing。
• 当 DI 携带身份验证上下文时，请使用 litestar-security 或 litestar-authentication。
• 当主要问题在于路由／控制器结构，而非服务接线时，请使用 litestar-routing。

Litestar 参考资料

• https://docs.litestar.dev/latest/usage/dependency-injection.html
• https://docs.litestar.dev/latest/usage/applications.html
• https://docs.litestar.dev/latest/usage/testing.html