breaking change とは？更新が呼び出し側を壊すとき

breaking change とは、既存の呼び出し側やデータの更新を強制する変更です。古い使い方が新しいバージョンに対してもう機能しなくなるためです。

breaking change は backward compatibility の反対です。呼び出し側が依存するものを削除・改名・厳格化するため、古い振る舞いに対して作られたものは更新されるまで失敗します。breaking change は禁止ではありませんが、協調、versioning、そして意図的なロールアウトを必要とします。だからこそ CI はそれを早期に指摘しようと努めます。

何が breaking にあたるか

フィールドや endpoint の削除・改名、任意フィールドの必須化、型の変更、検証の厳格化、値の意味の変更。以前は有効だった呼び出しを失敗させたり誤解させたりしうるものは、すべて breaking change です。

breaking か非 breaking か

非 breaking: 任意フィールドの追加、新しい endpoint、新しい enum ケース。
breaking: フィールドの削除、route の改名、型の変更。
微妙: 検証の厳格化やデフォルト挙動の変更。
判定基準: 既存の呼び出し側が動かなくなるか？

なぜ高くつくのか

共有インターフェースへの breaking change は、すべての consumer に、理想的には足並みをそろえた更新を強制します。これはまさにマイクロサービスと独立したデプロイが避けようとする協調です。consumer が多いほどコストは高く、blast radius も大きくなります。

CI で捕捉する

明示的な契約があれば、パイプラインは古いものと新しいものを diff し、breaking change があればビルドを失敗させられるため、偶然に出荷されません。これは、意図しない破損が consumer に届くことへの単一で最も効果的な guardrail です。

意図的に出荷する

破損が本当に必要なときの安全な道は、新しいバージョンです。古いものと新しいものを並行して動かし、consumer を移行し、その後で古いものを引退させます。パイプラインは、最後の consumer が古いものから移るまで両方のバージョンをテストし続けます。

バージョン混在デプロイの危険

versioning なしでデプロイされた breaking change が最も危険なのは、rolling deploy のバージョン混在期間で、呼び出し側がどちらのバージョンにも当たりうるときです。CI での互換性チェックが、その期間を障害に変えないようにするものです。

重要なポイント

breaking change は、既存の呼び出し側が更新されるまで失敗させる。
追加は通常安全だが、削除・改名・厳格化は通常壊す。
CI での契約 diff こそが、偶然に出荷してしまうことへの最善の防御である。