litestar-routing

ルーティング

API パスの設計、ハンドラーの登録、ルートの構成、パラメーターの動作がタスクの中心となる場合は、このスキルを使用します。

実行ワークフロー

1. 意味の明確なハンドラーデコレーターと厳密な型注釈を使って、エンドポイントの契約を定義します。
2. 構成モデルを選択します。
3. 単純なハンドラーはアプリに直接登録します。
4. パスのグループ化やネストされたルートツリーにはルーターを使用します。
5. 共通のコントローラーパス配下で、OOP スタイルのエンドポイントをグループ化するにはコントローラーを使用します。
6. パラメーターの取得元と制約（パス／クエリ／ヘッダー／Cookie／階層化パラメーター）を選択します。
7. ルートのメタデータとインデックス（name、opt）を適用し、見つけやすさとポリシーフックを確保します。
8. 逆ルーティング、一意なパスとメソッドの組み合わせ、階層化された優先順位の動作を検証します。

実装ルール

• URL の設計は安定性を保ち、リソース指向かつバージョンを考慮したものにします。
• ハンドラーは薄く保ち、ビジネスロジックはサービスに委譲します。
• OpenAPI の操作を明確にするため、@route() より意味の明確なデコレーター（@get、@post など）を優先します。
• 明示的なパスコンバーターと、型の範囲を絞ったパラメーターを使用します。
• 動的登録は例外的な手段として扱い、通常の構成には使用しないでください。
• メタデータとガードは、効果が得られる最も限定的なスコープに適用します。
• すべてのハンドラーパラメーターと戻り値に、完全な型注釈を付けます。

ルーティングの構成：アプリ、ルーター、コントローラー

アプリレベルの登録

• Litestar(route_handlers=[...]) は、ルート登録の起点です。
• 登録されたコンポーネントは、ルートパス / に追加されます。
• デコレーターにパスのリストを渡すことで、ハンドラーを複数のパスにアタッチできます。

動的登録

• 実行時の登録が本当に必要な場合は、app.register(handler) を使用します。
• アプリインスタンスは接続オブジェクト（Request、WebSocket、ASGIConnection）から利用できるため、ハンドラー／ミドルウェア／依存関係から動的登録を呼び出せます。
• 動的登録は運用の複雑さを増すため、必要最小限にとどめてください。

ルーター

• Router は、コントローラー、ハンドラー、ネストされたルーターを登録できます。
• ネストされたルーターはパスを結合します。ルーター A をルーター B に登録すると、A のパスが B のパス配下に追加されます。

コントローラー

• コントローラーは、クラスレベルの path を持つ Controller のサブクラスです。
• コントローラーのパスは、各ルートハンドラーメソッドのパスの先頭に付加されます。
• path を省略した場合、デフォルトは / です。
• 有効なルーティングツリー内で、パスと HTTP メソッドの組み合わせは一意でなければなりません。

コンポーネントの複数回登録

• コントローラーは異なるルーターに複数回登録できます。ルーターごとに独自のコントローラーインスタンスが作成されます。
• スタンドアロンハンドラーも複数回登録できます。Litestar は登録コンテキストごとにハンドラーをコピーします。
• ルーターはネストできますが、一度登録すると再登録できません。

ルートハンドラー

基本的な動作

• ハンドラーは、関数またはコントローラーメソッドに Litestar のデコレーターを適用して作成します。
• 同期および非同期の呼び出し可能オブジェクトの両方がサポートされています。
• 同期ハンドラーの場合：
• sync_to_thread=True はスレッドプールで実行します（ブロッキングコードに安全です）。
• sync_to_thread=False は、同期処理がノンブロッキングであることを示します。
• 同期処理の動作を暗黙のままにすると、警告が出ることがあります。

パスの宣言

• パスは位置引数（@get("/x")）またはキーワード引数（@get(path="/x")）で指定できます。
• パスには、複数パスでの登録や任意のパスパラメーターパターンに対応するため、リストを指定できます。

型注釈の要件

• すべてのハンドラー引数と戻り値に型を指定する必要があります。
• 注釈がない場合、アプリの起動時に ImproperlyConfiguredException が発生します。

予約済みキーワード引数の注入

予約済みの名前には、次のものがあります。

• cookies、headers、query
• request（HTTP ハンドラー）
• socket（WebSocket ハンドラー）
• scope、state、body（HTTP ハンドラーの body）

名前が衝突する場合は、別のパラメーター名を使用してください。

HTTP ハンドラー

• @route() は HTTPRouteHandler にマッピングされますが、通常の CRUD スタイルの API では一般に推奨されません。
• 意味の明確なデコレーターを優先してください。
• @get、@post、@put、@patch、@delete、@head

WebSocket ハンドラー

• @websocket() は、低レベルのソケット処理を直接サポートします。
• より高レベルなリアルタイムパターンには、専用の WebSocket アーキテクチャパターンを使用してください（スキル間の引き継ぎを参照）。

ASGI ハンドラー

• @asgi() ／ ASGIRouteHandler は、カスタム ASGI アプリをサポートします。
• ASGI ハンドラーのシグネチャは scope、receive、send に限定されます。
• ASGI ハンドラーは非同期である必要があります。

ASGI アプリのマウント

• @asgi(..., is_mount=True) を使用して、パスプレフィックスにサブアプリの動作をマウントします。
• マウントされたハンドラーは、そのプレフィックス以下のすべてのトラフィックを受け取ります。
• copy_scope=True を指定すると、転送される scope["path"] がマウントルートからの相対パスに書き換えられます。
• これはサードパーティ製 ASGI アプリの統合に便利です。

ルートのインデックス作成と逆引きルーティング

• 安定した検索のため、ハンドラーには明示的で一意な name を設定します。
• 名前は一意である必要があり、重複すると ImproperlyConfiguredException が発生します。
• route_reverse(name, **params) でパスを作成できます。
• request.url_for(name, **params) で絶対 URL を作成できます。
• 複数の一致するパスが曖昧になり得るハンドラーでは、逆引き検索を避けてください。結果の選択が予測不能になる場合があります。

opt による任意のルートメタデータ

• すべてのルートデコレーターは opt={...} メタデータを受け取ります。
• ルートデコレーターに指定した任意のキーワード引数は opt にマージされます。
• opt はガード、リクエストのルートハンドラーコンテキスト、ASGI スコープで利用できます。
• opt は階層化され（アプリ／ルーター／コントローラー／ハンドラー）、優先順位に従ってマージされます。
• キーが競合する場合は、ハンドラーに最も近い階層の値が優先されます。

シグネチャの名前空間解決

• Litestar は、ハンドラー／依存関係のランタイムシグネチャモデルを構築します。
• 型を TYPE_CHECKING の下でのみインポートしている場合は、次の方法で解決します。
• 必要に応じて、アプリ／ルーター／コントローラー／ハンドラーレイヤーに signature_types=[...] を指定します。
• エイリアス名がランタイム型の __name__ と異なる場合は、signature_namespace={...} を指定します。

デフォルトのシグネチャ名前空間には、次のものが含まれます。

• Headers、ImmutableState、Receive、Request、Scope、Send、State、WebSocket、WebSocketScope

パラメーター：パス、クエリ、ヘッダー、Cookie、階層化

パスパラメーター

• ルートパスでは {name:type} の形式で宣言します。たとえば {user_id:int} のように指定します。
• サポートされるパスコンバーターの型には、次のものがあります。
• date、datetime、decimal、float、int、path、str、time。
• 型変換が有効であれば、パスコンバーターの型と関数アノテーションが完全に一致している必要はありません。
• 関数シグネチャで宣言されていなくても、パス内にパスパラメーターを指定できます。その場合も検証とドキュメント生成が行われます。

Parameter() ヘルパー

• 追加の検証や OpenAPI メタデータには、Annotated[...] とともに Parameter(...) を使用します。
• 制約やドキュメント属性（例：gt、lt、タイトル／説明／例）をサポートします。

クエリパラメーター

• パスパラメーター以外の関数キーワード引数は、デフォルトでクエリパラメーターとして扱われます。
• クエリパラメーターはデフォルトで必須です。
• デフォルト値を指定すると、省略時に実行時で任意の値のように扱われます。
• 任意のアノテーション（str | None ／ Optional[str]）は、NULL 許容のクエリパラメーターを表します。
• クエリ値は、より複雑な型（例：datetime、数値、リスト）に型変換できます。

別名と制約

• Parameter(query="externalName") で URL のクエリ名を変更できます。
• たとえば数値の範囲など、Parameter(...) で検証制約を適用できます。

Enum クエリパラメーターのドキュメント

• デフォルトでは、Enum の docstring がスキーマの説明に使用されます。
• 同じ Enum にエンドポイントごとに異なるパラメーターの説明が必要な場合は、schema_component_key を使用します。

ヘッダーおよび Cookie パラメーター

• Parameter(header="...") または Parameter(cookie="...") で宣言する必要があります。
• それ以外の動作は、クエリパラメーターの解析／検証モデルに従います。

階層化パラメーター

• パラメーターはアプリ／ルーター／コントローラー／ハンドラーレベルで宣言できます。
• 階層化された宣言は、検証と OpenAPI 生成に反映されます。
• ハンドラー内の宣言で、外側の階層の制約をさらに絞り込めます。
• パスパラメーターは、ハンドラー以外のレイヤーでは宣言できません。

検証チェックリスト

• route_handlers のトポロジーが意図した最終パスに解決されることを確認します。
• パスとメソッドの組み合わせ、およびハンドラー名がそれぞれ一意であることを確認します。
• コントローラーとルーターのパスが意図どおりに結合されることを確認します。
• 同期ハンドラーで sync_to_thread の扱いが明示的に決定されていることを確認します。
• すべてのハンドラー引数と戻り値に型注釈があることを確認します。
• 予約済みのキーワード引数と注入された依存関係が予期せず衝突しないことを確認します。
• クエリ、ヘッダー、Cookie、パスの各パラメーターが期待どおりに検証および型変換されることを確認します。
• 階層化されたパラメーターで外側の制約が適用され、ハンドラーのオーバーライドが正しく機能することを確認します。
• 逆引きルーティング（route_reverse / url_for）が、インデックス化されたハンドラーに対して決定論的であることを確認します。
• opt メタデータのマージ動作が各階層で正しいことを確認します。
• マウントされた ASGI アプリが、期待されるパスの書き換えセマンティクスを受け取ることを確認します。
• OpenAPI の出力が、実際に有効なパス、パラメーター、オペレーションの分解と一致することを確認します。

スキル間の連携

• トランスポート契約の詳細については、litestar-requests と litestar-responses を使用します。
• ルートスコープのセキュリティやサービスについては、litestar-authentication と litestar-dependency-injection を使用します。
• より高度な WebSocket セッションアーキテクチャについては、litestar-websockets を使用します。
• オペレーション ID、パラメータースキーマ、ルートドキュメントの忠実性を確認するには、litestar-openapi を使用します。

Litestar のリファレンス

• https://docs.litestar.dev/latest/usage/routing/index.html
• https://docs.litestar.dev/latest/usage/routing/overview.html
• https://docs.litestar.dev/latest/usage/routing/handlers.html
• https://docs.litestar.dev/latest/usage/routing/parameters.html