dmr-from-drf

DRF から DMR への移行

概要

Django REST Framework のトランスポート層を、段階的に django-modern-rest へ移行します。 ユーザーから明示的な依頼がない限り、ビジネスロジックは変更しないでください。

必ず最初に参照する必須ドキュメント：

• DMR LLM ドキュメント：https://django-modern-rest.readthedocs.io/llms.txt
• DRF ドキュメント：https://www.django-rest-framework.org
• ローカルマップ：references/drf-to-dmr-map.md

移行ポリシー

• デフォルトモード：厳密なトランスポートの同等性。
• デフォルトで維持するもの：パス、メソッド、リクエスト／レスポンスのスキーマ、ステータスコード、ヘッダー、認証のセマンティクス、権限のセマンティクス、スロットリングのセマンティクス、ページネーションの形式、フィルター／クエリの動作。
• ユーザーが差異を承認した場合（たとえば、DMR ネイティブのエラー形式／ステータスへの切り替え）、従来の動作を強制するのをやめ、その内容を approved drift として記録します。
• 意図しない差異を混在させないでください。意図的な不一致はすべて明示的に列挙します。
• 実装方針として、DRF のトランスポート内部構造を維持しないでください。 外部から観測できる契約は維持しつつ、DMR とプロジェクト標準のライブラリで実現します。

ワークフロー

DRF の適用範囲を調査する

• まず、プロジェクトの API エントリーポイントと URL の配線を読みます。
• 次の使用箇所を探します：APIView、GenericAPIView、ViewSet、GenericViewSet、ModelViewSet、@api_view、DRF ルーター、DRF シリアライザークラス、パーサー／レンダラークラス、認証／権限／スロットリングの各クラス、DRF 例外ハンドラーのフック。
• エンドポイントごとの移行マトリクスを作成します：
  • パス、メソッド、認証、権限、スロットリング、パーサー／レンダラーの動作、
  • 入力 DTO、出力 DTO、
  • ページネーション／フィルタリングの契約、
  • 想定されるステータス、想定されるヘッダー、
  • 既知のエラーパス。

プロジェクト標準のライブラリを調査する（必須）

• アダプターを作成する前に、移行後のトランスポート層を支えるべき、既存のプロジェクトライブラリやインテグレーションを調査します。
• カスタムラッパーよりも、DMR の仕組みを通じてプロジェクトですでに使用されているライブラリを優先します。
• 例：
  • 認証／RBAC インテグレーション、
  • レート制限パッケージ、
  • リポジトリですでに接続されているページネーションおよびフィルタリングのライブラリ。

外部から観測できる動作を固定する

• 既存のテスト、シリアライザー、ルーティングから動作を把握します。
• コーディングを始める前に、作業を妨げる不一致を明示します：
  • ルート／メソッドの変更、
  • スキーマフィールドの変更、
  • 認証／権限／スロットリングの変更、
  • ページネーション／フィルタリングのレスポンス形式の変更、
  • パーサー／レンダラーのネゴシエーションの変更、
  • ステータス／ヘッダーの変更。

エラー戦略を決定する（必須ゲート）

編集前にいずれかを選び、記録します：

• strict parity：
  • 既存のエラーステータス／ペイロードのセマンティクスを維持します。
  • 必要に応じて、DMR のハンドラー／コンテキストに適合させます。
• approved DMR-native errors：
  • フレームワークネイティブのエラーマッピングを使用します。
  • それに応じて、テストとドキュメントの想定を更新します。
  • 成功時の動作と認証／権限／スロットリングの動作は引き続き維持します。

スライス単位（アプリまたはエンドポイントグループ）で移行する

• 範囲を限定したスライスを一度に1つずつ移行します。
• アーキテクチャや lint の契約で変更が必要な場合を除き、モジュール構成を維持します。
• DRF のトランスポート内部構造を表すクラス名を維持しないでください。 トランスポートクラスは、中立的な名前または DMR を意識した名前に変更します。
• 薄いトランスポートアダプターを優先します：
  • ユースケース／サービス／リポジトリには手を加えず、
  • DTO／コントローラー／ルーターの配線のみを変更します。

シリアライザーとリクエスト／レスポンスの契約を変換する

• トランスポート DTO としての Serializer ／ ModelSerializer の使用を、DMR シリアライザーと互換性のある明示的な型付き DTO に置き換えます。
• リクエストの取得元を明示的にマッピングします：
  • ボディ Body[...]、クエリ Query[...]、パス Path[...]、ヘッダー Headers[...]、Cookie Cookies[...]。
• レスポンスにサーバー管理フィールドが含まれる場合は、入力 DTO と出力 DTO を分けます。
• 契約の同等性に必要なフィールドのエイリアス、必須／任意の動作、バリデーション制約を維持します。

DRF ハンドラーを DMR に変換する

• 関数ベースの @api_view エンドポイントを、明示的な Controller[...] ハンドラーに置き換えます。
• APIView/GenericAPIView/ViewSet アクションを、DMR コントローラーとルーター構成に置き換えます。
• ユーザーが変更を要求しない限り、ルート名と URL の形状は安定させます。
• パーサーとレンダラーの期待値を意図的に移植します。
• 例外の動作を意図的に移植します:
  • 厳密一致モード: 以前のステータス/ペイロードを保持します。
  • 承認済みドリフトモード: DMR ネイティブのエラーを維持し、テストを更新します。

API の配線を置き換える

• DRF のルーター登録と URL 配線を、DMR ルーター + Django URL include 配線に置き換えます。
• ドリフトが承認されない限り、名前空間の安定性 (api:* 名) を保ちます。
• docs/openapi ルートは、プロジェクトがすでに公開している場合、またはユーザーが要求した場合にのみ追加します。

認証、権限、スロットリングをネイティブの仕組みで移植する

• 認証と権限の期待値をエンドポイントごとに保ちます。
• プロジェクトが DRF またはサードパーティツールの Opaque Token 認証を使用している場合、 同じモデルを維持し、DMR のデフォルトの Token モデルを既存のものに 差し替えるのが良いかもしれません。 これについてはユーザーに明示的に確認してください。
• ドリフトが承認されない限り、スロットリングの動作とヘッダー (たとえば Retry-After) を保ちます。
• メソッド固有の権限の動作とアクションレベルの違いを維持します。
• DMR フックを介して、既存のプロジェクトネイティブの認証/スロットルライブラリを優先します。
• ローカル開発とテストでは、常にグローバルの validate_responses 設定を有効にします。
• すべての追加レスポンスが ResponseSpec で明示的に宣言されていることを確認します。
• すべてのレスポンスがレスポンス検証を通過することを必須とします。
• 最終的な解決策として DRF 互換シムを避けます。 一時的なシムが避けられない場合は、明示的に一時的であるとマークし、 置き換え計画を文書化し、unresolved gaps に記載します。

DMR ツール用にテストを更新する

• 必要に応じて、DRF 固有の API テストの前提を、リポジトリネイティブの Django/DMR テストエントリポイントに置き換えます。
• API テストのフィクスチャとクライアントを第一級の移行スコープとして移行します: フィクスチャの意図 (api_client、認証フィクスチャ) は安定させますが、 移行後の DMR スタックに再バインドします。
• 契約アサーションをエンドポイントごとに保ちます: ステータスコード、ペイロード、ヘッダー、認証/権限の動作、スロットリングの動作、 パーサー/レンダラーの動作、ページネーション/フィルタリングのセマンティクス。
• ネガティブパスのテストが、宣言された追加レスポンスを網羅し、 ResponseSpec メタデータと一致することを確認します。
• 完全に移行されたトランスポート/テストモジュールから、永続的な DRF トランスポートのインポートを削除します (一時的なドリフトとして明示的に承認されている場合を除く)。

各スライスをリポジトリネイティブの CI エントリポイントで検証する

• このリポジトリで CI が使用するのと同じコマンドを実行します。
• アドホックなコマンドセットよりも、公式のスクリプトエントリポイントを優先します。
• Docker 専用の CI/テスト環境が必要な場合は、Docker 内で実行します。

完了ゲート

以下を満たすまでスライスを完了とマークしないでください:

• リンターがパスすること、
• テストがパスすること (または失敗が明示的に承認済みドリフトであること)、
• レポートが更新されていること。

翻訳ルール

• ビジネスロジックはデフォルトで変更しません。
• トランスポートは決定的かつ型付きに保ちます。
• 隠れたルート正規化の変更 (末尾スラッシュ/プレフィックス) を避けます。
• エラーペイロードの形式がドリフトしても、認証、権限、スロットリングのセマンティクスを保持します。
• ドリフトが承認されない限り、ページネーションのエンベロープとカーソル/ページのセマンティクスを保持します。
• パーサー/レンダラーのネゴシエーションを保持するか、承認済みドリフトを明示的に列挙します。
• フレームワークの制約について明示します (たとえば DMR ネイティブの検証動作)。
• ユーザーが一時的であると明示的に承認しない限り、移行済みスライスで DRF トランスポートクラスを使用しないでください。
• 移行済みトランスポートコードに DRF にバインドされたクラス名を残さないでください。

レポート形式 (必須)

意味のある各チェックポイントと完了時に、3 つのセクションで報告します:

1. preserved behavior
2. approved drift
3. unresolved gaps

unresolved gaps には、具体的なファイル/エンドポイントと、未解決である理由を含める必要があります。

移行時の落とし穴（DRF に由来するもの）

• DRF のルーターでは、末尾のスラッシュの動作がデフォルトで設定されていることがよくあります。URL の形を正確に維持してください。
• 必須／任意の DTO 制約を機械的に変換すると、partial=True による更新のセマンティクスが異なる場合があります。
• ページネーションのレスポンスエンベロープ（count/next/previous/results と並び順）は、差異の承認がない限り維持する必要があります。
• パーサー／レンダラーのデフォルト設定を意図的に移植しないと、コンテンツネゴシエーションによって動作が変わる可能性があります。
• ViewSet クラスのアクション単位の権限とスロットリングは、クラス単位だけでなく、各アクションで維持する必要があります。
• ヘッダーを含むレスポンス（例：location ヘッダーやスロットリングヘッダー）は、明示的に宣言し、テストする必要があります。

出力チェックリスト

• 移行対象の範囲について、DRF のルート配線を DMR のルーティングに置き換えた。
• DRF の API ビュー／ビューセットを DMR のコントローラーに置き換えた。
• 移行対象のエンドポイントについて、DRF のトランスポートシリアライザーを DTO に置き換えた。
• 認証／権限／スロットリングの動作を維持したか、差異を明示的に承認した。
• ページネーション／フィルタリングおよびパーサー／レンダラーの動作を維持したか、差異を明示的に承認した。
• プロジェクト標準のバッテリーを最初に評価し、可能な場合は使用した。
• 移行したトランスポート層に、永続的な DRF シムや DRF に依存した命名が残っていない。
• 選択した方針に基づく同等の動作カバレッジを維持するために必要な場合に限り、テストを更新した。
• レスポンス検証が有効になっており、移行したすべてのエンドポイントのレスポンスが検証に合格する （ResponseSpec で宣言された追加のレスポンスも含む）。
• 範囲ごとに、リポジトリ標準の CI エントリーポイントを実行した。
• 必須の 3 セクション形式で最終レポートを出力した。
• 移行が成功し、移行した API サーフェスの CI がすべて成功した後、ユーザーが保持を明示的に承認していない限り、プロジェクトの依存関係から djangorestframework を削除する。