litestar-responses

レスポンス

実行ワークフロー

1. 契約に合う最もシンプルな戻り値の形式から始めます。型付きデータ、Response[T]、または専用のレスポンスコンテナーを選びます。
2. デフォルトでは不十分な場合は、ステータスコード、メディアタイプ、ヘッダー、Cookieを明示的に設定します。
3. リダイレクト、ファイル、ストリーム、SSE、テンプレート、またはサードパーティのASGIレスポンスには、専用のレスポンスタイプを選びます。
4. 複数のハンドラーでシリアライズやエンベロープの動作を共通化する場合に限り、レスポンスクラスのレイヤー化を適用します。
5. 型付きレスポンス、ドキュメント専用のヘッダー／Cookie、空の本文を返すステータス、専用のレスポンスコンテナーについて、OpenAPIの正確性を確認します。

基本ルール

• 標準的なJSONレスポンスには、型付きの値をそのまま返す方法を優先します。
• ヘッダー、Cookie、バックグラウンドタスク、ステータスコードを実行時に制御する必要がある場合は、Response[T]を使用します。
• スキーマ生成の正確性を保つため、レスポンスクラスのジェネリック引数は厳密に指定します。
• クライアントが依存する実行時のヘッダーやCookieは、特に値が動的に設定される場合、必ずドキュメントに記載します。
• 204、304などの本文を持たないレスポンスは、Noneを返す契約として扱います。
• APIで共通の契約を使用する場合は、成功時のエンベロープを例外処理時のエンベロープと一貫させます。
• ファイル、リダイレクト、ストリーム、SSEの動作を手動で再実装せず、専用のレスポンスコンテナーを使用します。
• レイヤー化されたresponse_class、response_headers、response_cookiesのオーバーライドは、意図を持って局所的に適用します。

選択ガイド

• Litestarのデフォルトが契約に合う場合は、データをそのまま返します。
• ペイロードは通常のままでメタデータが動的な場合は、Response[T]を返します。
• 多くのエンドポイントで同じシリアライズ方法を使う場合は、response_class=を使用します。
• サードパーティのASGIレスポンスオブジェクトをラップする場合や、低レベルの動作をカスタマイズする場合は、ASGIAppを返します。
• トランスポートの動作が特殊な場合は、File、Stream、ServerSentEvent、またはリダイレクト用レスポンスを使用します。
• ライブサーバーを必要とするシナリオのうち、特に無限SSEストリームなど、プロセス内クライアントでは適切に再現できないものには、サブプロセスのテストクライアントを使用します。

参考ファイル

必要なセクションだけを読みます。

• 型付きの戻り値、Response[T]、ステータスコード、レイヤー化されたresponse_class、カスタムレスポンスクラス、バックグラウンドタスクについては、references/response-basics.mdを読みます。
• ヘッダー、Cookie、リダイレクト、ファイル、ストリーム、SSE、テンプレート、ASGIアプリの戻り値については、references/response-containers.mdを読みます。

推奨されるデフォルト

• トランスポートレベルの制御が必要な場合を除き、通常のJSONの戻り値はLitestarにシリアライズさせます。
• コードとテストの両方で、litestar.status_codesのステータスコード定数を使用します。
• 動的なヘッダーやCookieは、documentation_only=Trueのメタデータでドキュメントに記載し、レスポンスまたはフックで実行時の値を設定します。
• ストリームやSSEのジェネレーターは、キャンセルに安全で、切断時の動作に応じて適切に終了するようにします。
• 中継サーバーやクライアントが予測可能に動作するよう、ファイルの配信とリダイレクトの動作を明示します。

アンチパターン

• どこでもResponse[Any]を返し、スキーマの正確性を損なう。
• 通常のResponse[T]や組み込みコンテナーで十分な場合に、カスタムレスポンスクラスを使用する。
• 204 No Contentエンドポイントで本文を返す。
• クライアントが依存する動的なヘッダーやCookieを設定しながら、OpenAPIのドキュメントに記載しない。
• 無限ストリームやSSEの動作を、プロセス内クライアントだけでテストする。
• Fileを使用せず、ファイル配信を手動で再実装する。

検証チェックリスト

• 戻り値のアノテーションが、実際のレスポンス本文およびステータスコードと一致していることを確認します。
• 空の本文を返すレスポンスでは、None のアノテーションと本文が使われていることを確認します。
• 階層化された response_class、response_headers、response_cookies の優先順位が意図したとおりであることを確認します。
• クライアントが動的なヘッダーや Cookie に依存する場合、それらが文書化されていることを確認します。
• ストリーム、SSE、リダイレクト、ファイルのレスポンスで、意図したメディアタイプとトランスポート動作が使われていることを確認します。
• バックグラウンドタスクが、レスポンス本文の送信後にのみ実行されることを確認します。
• カスタムのレスポンスクラスやコンテナーを変更した後も、OpenAPI の出力が正確であることを確認します。
• レスポンスのドキュメントが、litestar-openapi のメタデータおよび例と整合していることを確認します。

スキル間の連携

• エラーエンベロープと失敗レスポンスの設計には、litestar-exception-handling を使用します。
• レスポンスの変更がスキーマ出力に大きく影響する場合は、litestar-openapi を使用します。
• テンプレートエンジンについてさらに詳しく扱う場合は、litestar-templating を使用します。
• ステータス、ヘッダー、Cookie、ストリーム、リダイレクト、SSE の動作を検証する場合は、litestar-testing を使用します。

Litestar の参考資料

• https://docs.litestar.dev/latest/usage/responses.html
• https://docs.litestar.dev/latest/reference/response/index.html
• https://docs.litestar.dev/latest/usage/testing.html