API契約の互換性

コントラクト互換性の理由

契約の互換性は、既存の統合を破ることなくAPIが進化する能力です。成長するシステムでは、APIはクライアントコードよりも頻繁に変化します。互換性により、「大きな動き」を配置することなく、機能を反復的にリリースできます。

主なアイデア：契約は主であり、変更は互換性ルールに従って実行され、自動的にチェックされます。

基本的なコンセプト

契約-正式なインターフェイス仕様：リソース/メソッド/イベント、データスキーマ、エラーコード、制限、SLA、セキュリティ要件。
Provider-APIの所有者。コンシューマー-クライアント/インテグレーション。

互換性：

後方：新しいサプライヤーは古い消費者と協力します。
前方：古いサプライヤーは、新しい消費者（通常は「寛容な読者」によって達成されます）で動作します。
フル：後方と前方の両方（最強のオプション）が観察されます。
Additivity-既存の要素を壊すことなくオプション要素を追加します。

バージョン管理ポリシー

セマンティックバージョニング（推奨）：

MAJOR-壊れた変更（新しいAPI行がリリースされた場合のみ：'/v2'、'サービス。v2'）。
MINOR-追加の変更（新しいオプションフィールド/メソッド）。
PATCH-契約を変更せずに修正。
拒否ポリシー：廃止された要素の宣言、サポートウィンドウ（日没）、ヘッダー/メタデータの警告、撤退計画。

セーフvs危険な変更

セキュア（通常は下位互換）

JSON/Protobuf/Avroにオプションのフィールドを追加します。
新しいエンドポイント/メソッド/イベントを追加します。
消費者が未知の値に寛容であれば、新しい値で列挙を拡張する。
最小値を引き締めることなく制限（例えば"maxItems'）を上げます。
正しいデフォルトでnullableを追加します。
説明/サンプルテキストを編集します。

危険（休憩互換性）

フィールドの名前変更/削除、タイプの変更、または必須。
ステータスコード/エラーセマンティクスの変更（例：'200'、'204'または'404'）。
識別子の形式を変更する（UUID→int）。
バージョンなしで検証（厳密な最小/パターン）の締め付け。
gRPCストリーム/イベントの順序と構造を変更します。
Protobufのタグ番号を新しいフィールドに再利用します。

インタラクションスタイルによる相互運用性

REST/HTTP+JSONスキーマ

Additivity：新しいフィールドを'optional'/'nullable'としてマークします。
クライアントのTolerant Reader：未知のフィールドを無視します。注文に頼っていません。
バージョン管理：major-途中（'/v2'）またはメディアタイプ（'application/vnd。例を示します。v2+json'）。
ETag/If-Match：レースを行わない安全なアップデートのために。
エラー：単一のフォーマット（'type'、 'code'、 'title'、 'detail'、 'trace_id'）は、メジャーなしで'code'の値を変更しません。
ページネーション：カーソルはオフセットすることをお勧めします。'next_cursor'フィールドを追加します。既存のフィールドの意味は変更しません。

gRPC/Protobuf

タグ番号は変更されません。削除されたタグは再利用できません。
新しいフィールドは'optional'/'repeated'であり、サーバー上では妥当なデフォルト値です。
streaming-RPCの順序と必須メッセージを変更しないでください。
エラーのステータスは安定しています（'INVALID_ARGUMENT'、 'FAILED_PRECONDITION'など）。新しい意味→メソッド/サービスの新しいバージョン。

イベント駆動（Kafka/NATS/Pulsar）+Avro/JSONスキーマ

イベント名：'domain。アクション。v {major}'。
新しいフィールドはオプションです。コアと濃縮（'。enriched'）を分離します。
スキーマレジスタ：テーマ/イベントの互換性ルール（BACKWARD/FORWARD/FULL）。
Enum拡張は、消費者側の許容リーダーで有効です。
集計=変更を破るためのパーティション/オーダーキーの変更。

GraphQL

フィールド/タイプの追加は安全です。delete/rename-deprecatedとマイグレーションウィンドウのみ。
majorなしでタイプ/非nullableを変更しないでください。
制御の複雑さ/深さ-限界は契約の一部です。

持続可能な進化パターン

Additive-first：破損せずに展開します。
機能ネゴシエーション：クライアントは（ヘッダ/パラメータ/契約）をサポートしていることを報告し、サーバーは調整します。
契約の境界：MGC（最低保証契約）と個別の拡張（逆ピラミッドモデル）を修正します。
デフォルトでは、許容差：クライアントは不要な値を無視し、未知の列挙（フォールバック）値を正しく処理します。
Dual-write/Dual-emit：大きな変更の場合は、'v1'と'v2'をしばらく並列にリリースします。
Sunsetヘッダー/イベント：バージョンが削除されたときに事前に通知します。

ガバナンスと自動化

API Linters：

OpenAPI/Spectral：ネーミング、ページネーション、エラーコード、フィールド形式。
Buf/Protobuf：タグ、パケット表記の再利用を禁止します。
AsyncAPI/Schema Registry： CIレベルのスキーマ互換性。
契約カタログ（SSOT）：拡散履歴を持つ一元化されたスキーマ/バージョンレジスタ。
APIギルド：ルール、テンプレート、レビューの変更を採用するギルド/委員会。
変更管理：RFC/ADR、リリースノート、移行ガイド。

互換性試験

CIのSchema-diff：ブロックブレイクケーキ（OpenAPI-diff、 Buf breaking、 SR互換性）。
消費者主導の契約（CDC）：協定/類似-サプライヤーと消費者固有の契約。
ゴールデンサンプル：回帰のための参照クエリ/応答とイベント。
E2E Canary：トラフィック/個々のコンサマグループのシェアに展開します。
カオス/レイテンシ：タイムアウト/リトレイチェック-レイテンシ-SLO変更は契約変更と見なされます。

移行と非推奨

1.deprecateを宣言する：アイテムにマークを付け、sunset termとalternativeを指定します。
2.互換性の期間を維持して下さい：二重ライト/二重emit、橋、アダプター。
3.テレメトリーを収集する：他に誰が古いものを使用していますか？
4.コミュニケーション：郵送物、解放のノート、テストスタンド。
5.削除：ウィンドウの有効期限が切れた後-固定リリースでの削除。

変更の例

REST

それは：

json
{ "id":"p1", "status":"authorized" }

（添加物、安全）になりました：

json
{ "id":"p1", "status":"authorized", "risk_score": 0. 12 }

未知のフィールドを無視するクライアントは壊れません。

Protobuf

proto message Payment {
string id = 1;
string status = 2; // don't change tag numbers optional double risk_score = 3; // additive
}

イベント

支払いだよ。承認されました。v1'（コア）+'支払い。豊かになりました。v1'（エンリッチメント）。クリティカルパスの消費者はコアを読み取り、濃縮に依存しません。

アンチパターン

Swagger-wash：正式には仕様がありますが、サービスの動作はそれと対立しています。
ステルスによる破損：新しいバージョンと移行ウィンドウなしでタイプ/ステータス/フォーマットを変更しました。
公開契約としてのRaw CDCイベント：漏洩したDBスキーム、進化の不可能。
ハードクライアント：不明なフィールド/値でドロップします。寛容な読者がいない。
protobufタグの再利用：静かなデータ破損。
「非契約」としてのレイテンシ：p95は予期せず延長されました-消費者はタイムアウトで分解します。

互換性チェックリスト（マージ前）

変更は添加物（またはメジャーバージョンが用意されている）です。
渡されたLinters/diffチェック、互換性ルールは緑色です。
エラー/コード/ステータスはセマンティクスを変更しませんでした。
古い値を禁止せずに拡張された列挙。クライアント-寛容。
MGCの境界は変更されていません。
サンプル/ドキュメント/SDKを更新しました。
メジャー-デュアルライト/デュアルエミットプラン、日没日、comm-plan。
テストCDC/Golden/E2E合格しました。

よくあるご質問

前方互換性と後方互換性はどのように異なりますか？
後方-新しいサーバーは古いクライアントを壊すことはありません。Forward-新しいクライアントは古いサーバーを壊すことはありません（寛容なリーダーと端正なデフォルトを介して）。

あなたはいつ'/v2'をしますか？
不変量/セマンティクスが変化すると、フィールド/メソッドが削除され、新しいセキュリティモデルが必要になります。新しい行を開始する方が簡単で正直です。

Schema Registry/Lintersなしで生活できますか？
理論的には-はい、実際には-これらは頻繁な回帰と「隠された」故障です。自動化は支払います。

Enumは拡張できますか？
はい、クライアントが未知の値（フォールバック/無視）を正しく処理する場合。そうでなければ-メジャー。

合計

契約の互換性はルール+規律+自動化です。付加的に設計して下さい、版の破損の変更は、許容の読者を適用しましたり、自動的にdiffおよびCDCを点検しましたり、非推奨を計画します。これにより、APIは迅速に進化し、統合は安定した状態を維持できます。