litestar-middleware

ミドルウェア

実行ワークフロー

1. その要件が本当にミドルウェアに適しているか確認します。ルートのビジネスロジックではなく、ASGI 全体をラップする処理である必要があります。
2. まずは組み込みの設定ベースのミドルウェアを優先します。
3. 適切なレイヤーと順序を慎重に選びます。
4. その処理がミドルウェア、ライフサイクルフック、ルートロジックのどれに該当するか判断します。
5. カスタムミドルウェアを使う場合は、要件を満たす最もシンプルな実装スタイルを選びます。
6. 成功時と例外によって生成されたレスポンスの両方に加え、除外設定とスコープの扱いも検証します。

基本ルール

• ミドルウェアは、横断的関心事を 1 つだけ扱うようにします。
• カスタム実装を作成する前に、組み込みのミドルウェアや設定オブジェクトを優先します。
• ミドルウェアの順序は API の動作の一部として扱います。
• 必要に応じて、ミドルウェアのスコープを http、websocket、lifespan に対応させます。
• ASGI メッセージをラップするのではなく、レスポンスオブジェクトを変更する処理にはライフサイクルフックを使います。
• ミドルウェアはノンブロッキングで、ASGI に準拠させます。
• ルーターが生成するこれらの例外はミドルウェアスタックに入る前に発生するため、404 と 405 の想定を明確にします。

判断ガイド

• CORS、CSRF、圧縮、レート制限、ロギング、セッション、許可ホストには、組み込みの設定ミドルウェアを使います。
• ごく小さなラッパーには、ミドルウェアファクトリーを使います。
• 設定可能な本番用カスタムミドルウェアには、ASGIMiddleware を使います。
• 最小限の低レベル処理には、MiddlewareProtocol を使います。
• AbstractMiddleware は、互換性の維持や移行の場合にのみ使います。
• コンストラクター形式の引数をミドルウェアファクトリーまたはクラスに渡す必要がある場合は、DefineMiddleware を使います。
• 処理が after_request、before_send、または関連するフックの段階に該当する場合は、代わりに litestar-lifecycle-hooks を使います。

リファレンスファイル

必要なセクションだけを読んでください。

• ミドルウェアの基本、順序、除外設定、組み込みミドルウェアの選択については、references/builtin-and-ordering.md を読んでください。
• カスタムミドルウェアの実装スタイル、ASGIMiddleware、MiddlewareProtocol、AbstractMiddleware、DefineMiddleware については、references/custom-middleware-patterns.md を読んでください。

推奨されるデフォルト

• 一度に扱うミドルウェアの関心事は 1 つにします。
• 組み込みの設定値を明示し、レビューします。
• 除外設定と opt に基づくスキップは範囲を絞り、テストします。
• 順序に関する前提が本当に自明でない場合に限り、コードコメントで明示します。
• 成功するハンドラーと失敗する下流ハンドラーの両方に対して、ミドルウェアをテストします。

アンチパターン

• ルート固有のビジネスルールをミドルウェアに入れる。
• 組み込みの設定やライフサイクルフックで対応できるのに、カスタムミドルウェアを作成する。
• 複数のラッパーが相互作用するときに、ミドルウェアの順序を無視する。
• 誤った ASGI の段階でリクエストまたはレスポンスの状態を変更する。
• ルーターが生成する 404 と 405 がミドルウェアを通過すると想定する。
• 文書化されていない opt の除外設定やパスパターンに、ミドルウェアが暗黙に依存する状態にする。

検証チェックリスト

• ミドルウェアが意図したレイヤーだけに適用されていることを確認します。
• レイヤーの優先順位とリストの順序の両方に合致していることを確認します。
• パスパターン、exclude_opt_key、またはスコープによる除外設定が意図どおりに動作することを確認します。
• 成功時と例外によって生成されたレスポンスの両方で、動作が正しいことを確認します。
• 404 と 405 の動作が適切な境界で処理されることを確認します。
• カスタムミドルウェアが引き続き ASGI に準拠し、ノンブロッキングであることを確認します。
• 組み込みのセキュリティおよびロギングミドルウェアの設定が、デプロイ時の要件に合っていることを確認します。

他のスキルへの引き継ぎ

• 生の ASGI ラップではなく、フックの段階で行うロジックには litestar-lifecycle-hooks を使います。
• ドメイン固有のミドルウェア処理には、litestar-authentication、litestar-security、litestar-logging、litestar-metrics を使います。
• ミドルウェアの相互作用がランタイムの不具合の原因である場合は、litestar-debugging を使います。
• ミドルウェアの動作がレイヤーの配置や opt の戦略に依存する場合は、litestar-routing を使います。

Litestar References

• https://docs.litestar.dev/latest/usage/middleware/index.html
• https://docs.litestar.dev/latest/usage/middleware/using-middleware.html
• https://docs.litestar.dev/latest/usage/middleware/builtin-middleware.html
• https://docs.litestar.dev/latest/usage/middleware/creating-middleware.html