laravel:api-surface-evolution について
公開済みクライアントとの契約を保ちながら API を進化させる Laravel 向けスキルです。バージョニング、DTO 変換、非推奨化、互換性テストを扱います。
主な機能
- 01URI またはヘッダーによるバージョニング
- 02バージョン別 DTO とトランスフォーマー
- 03非推奨化の期限と利用状況メトリクス
- 04契約テストと後方互換性テスト
活用シーン
- 01クライアントを壊さず API フィールドを追加
- 02API バージョン間で非推奨フィールドを管理
- 03リクエストとレスポンスの契約を検証
インストール
コマンドをコピーしてターミナルで実行します。
$
npx skills add https:/インストール後、Claude Code で/laravel:api-surface-evolutionを入力して読み込まれたか確認します。
詳細
API サーフェスの進化
クライアントを壊すことなく変更できるように設計します。
バージョニング戦略
- 明示的なバージョニング（URI
/v1/...またはヘッダーによるネゴシエーション）を選択します - 変更は追加を基本とし、リリース済みの契約は決して破壊しません
DTO とトランスフォーマー
- バージョン付き DTO を定義し、トランスフォーマーを介してモデルやサービスからマッピングします
- コントローラーは薄く保ちます。検証 → 変換 → 応答
非推奨化
- ドキュメントとレスポンス（例：ヘッダー）でフィールドに非推奨のマークを付けます
- 廃止までのスケジュールを示し、残りの使用状況を把握するためのメトリクスを追加します
テスト
- バージョンごとのコントラクトテスト（リクエスト／レスポンスの形式）
- よく使われるフローの後方互換性テスト
コメント
Markdown 対応