破壊的変更を避けるための互換性保持の設計がされているか？¶
Type: Structure
Category: API・権限・セキュリティ
Audience: 設計初心者 / 設計中のチーム / レビュワー
背景・概要¶
APIの互換性が壊れるとフロントエンドやCI/CDが止まりやすく、システム全体の信頼性が低下する
バージョニングやnullable項目の追加などで、後方互換を意識した開発が必要
例¶
- 既存項目の削除・型変更を避け、代わりに新しい項目で置き換える
- /v1/ などのバージョン付きエンドポイントでリリース
- APIの定義ファイル（YAMLやJSON、gRPCの .protoなど）を元にして、旧バージョンと新バージョンの差分を比較し、破壊的変更がないかを自動で検出する
よくある失敗例¶
- プロパティの型が変更されたりstatusが追加されたが、既存のAPI利用者のシステムでエラーになる
- 任意フィールドのnullableが外されたが内部処理が考慮してないためバグが発生する
FAQ¶
Q. 破壊的変更が必要な場合はどうする？
A. バージョン分岐を行うか、段階的リリース（新旧共存）で移行する
Q. 自動検知できる？
A. buf（gRPC）や openapi-diff（OpenAPI）などのdiffツールで差分検知・互換性チェックの自動化は可能。導入する場合はCI組み込み推奨