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 のような不明瞭な名前を使い、依存関係を中身の見えないサービスロケーターとして扱う。
• プロバイダーから変更可能なグローバルシングルトンを返し、リクエストごとに変更する。
• sync_to_thread=True を指定せずに、同期プロバイダー内でブロッキング I/O を実行する。
• 型の境界を修正せず、広範囲に 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