歴史: モノリシックアーキテクチャでは、APIの変更は統合テストフェーズを通じて管理可能でした。しかし、マイクロサービスの採用により、サービス依存のファンアウトが「バージョニング地獄」を生み出し、単一の破損変更が数十の下流消費者に渡って障害を引き起こす可能性がありました。これにより、手動のOpenAPIレビューから、自動化された契約主導の検証ゲートへの移行が必要になりました。
問題: 従来のテストはAPIが単独で機能することを確認しますが、リクエスト/レスポンススキーマの変更が既存の消費者との暗黙の契約に違反するかどうかを検出することはできません。手動の仕様レビューはエラーが発生しやすく、数百の相互依存サービスにスケールすることができず、使用中の非推奨フィールドが削除されることで生じる本番事故につながります。
解決策: OpenAPIの差分分析と消費者主導の契約テストを統合した多層の検証パイプラインを実装します。OpticやSwagger Diffなどのツールを利用して、変更を破壊的（フィールドの削除、型の変更）または非破壊的（オプションの追加）に分類します。Pactを統合して、プロバイダーの変更が記録された消費者の期待に合致することを確認します。パイプラインが検出された変更の重大度に基づいて必要なバージョンの増分を計算し、増分が不十分な場合はデプロイを制限するセマンティックバージョニングの自動化を強制します。
validate_api_compatibility: stage: test script: - optic diff openapi.yaml --base main --severity breaking - pact-verifier --provider-app-version $CI_COMMIT_SHA --publish-verification-results - python scripts/check_semver.py --schema-diff-report optic-report.json rules: - if: $CI_PIPELINE_SOURCE == "merge_request_event"
私たちのチームは、12の内部マイクロサービスと3つの外部銀行パートナーにサービスを提供するペイメントゲートウェイAPIを維持していました。3D Secure 2.0認証フィールドを追加するためのルーチン強化の間に、開発者は非推奨のtransactionReference文字列フィールドを削除し、オブジェクト構造に置き換えました。
問題の説明: 変更はユニットテストと統合テストに合格しましたが、新しい構造がデータを正しく処理しました。しかし、3つのレガシー会計マイクロサービスは今もフラットな文字列フィールドを期待していました。手動のOpenAPIレビューはこの構造変更の破壊的性質を見落としました。デプロイ時に、調整ジョブがデシリアライズエラーで失敗し、4時間のダウンタイムを引き起こしました。
検討した別の解決策:
チェックリストを用いた手動のピアレビュー: すべてのOpenAPI変更を破壊的変更チェックリストを使用して、上級エンジニアにレビューさせる。このアプローチは人間の警戒心に依存しますが、圧力下では根本的に信頼できず、迅速なデプロイメントサイクルに対応しきれず、隠れた消費者の依存関係を考慮できません。
自動JSONスキーマ比較: 構造のいかなる違いもエラーとしてフラグを立てる基本的なdiffツールを実装します。これにより迅速なフィードバックが得られますが、追加的な変更（新しいオプションフィールド）を違反と見なすことにより過剰な偽陽性を生成し、チームは面倒な例外リストを維持し、最終的にはアラート疲労のために警告を無視することになります。
セマンティックバージョニングゲートを持つ消費者契約テスト: Pactを導入して消費者主導の契約を、OpenAPI差分分析のためのOptic CLIと組み合わせます。これにより、変更が実際に記録された消費者の相互作用に対して検証され、真に破壊的な変更のみが失敗を引き起こすことを保証します。自動的にセマンティックバージョンのバンプを提案し、非推奨のタイムラインを強制します。欠点は、消費者チームをオンボードするための初期投資と契約アーティファクトの保存オーバーヘッドが必要であることです。
選択した解決策とその理由: 私たちは、マイクロサービスアーキテクチャの自律的なデプロイメントの必要性に合わせて消費者契約テストを選択したことで、連鎖的な障害を防ぎました。手動レビューとは異なり、水平方向にスケールします。基本的なdiffツールとは異なり、セマンティックな影響を理解します。私たちは、初めは重要なサービスパスのみに契約テストを義務付けることで、オンボーディングコストを受け入れました。
結果: 破壊的変更はその後8ヶ月間の本番リリースから排除されました。デプロイメントの頻度は隔週から毎日へと増加し、チームは自動化されたゲートを信頼するようになりました。同じリファクタリングが後に試みられたとき、Pactの検証はプルリクエストで即座に失敗し、レガシーサービスとの互換性がないことを強調しました。
REST APIの検証における構文的破壊的変更とセマンティック破壊的変更をどのように区別しますか？
構文的変更は、フィールドの削除や型の変更など、OpenAPIスキーマの差分を介して検出可能な構造的変更を含みます。セマンティック変更は構造を保持しますが、動作を変更します。たとえば、オプションパラメータのデフォルト値の変更や返される配列のソート順の変更などです。純粋なスキーマ検証はセマンティックな破壊を見逃し、契約テストやシャドウトラフィック比較による行動テストが必要です。
拡張-契約パターンとは何ですか、そして自動化はそれをどのように強制すべきですか？
拡張-契約パターンは、新しい機能を古いものと並行して追加する（拡張）、消費者を移行させた後に古いコードを削除する（契約）ことを要求されます。自動化は、フィールドの非推奨メタデータを追跡し、非推奨のフィールドが早期に削除された場合にビルドを失敗させる必要があります。さらに、システムは、除外される前に非推奨エンドポイントへのトラフィックがゼロであることを確認するためにテレメトリーを監視すべきです。これにより、単なるコードレベルの互換性ではなく、実際の消費者の準備が整っていることが保証されます。
消費者が外部第三者であり、あなたの契約テストパイプラインに参加できない場合、APIの互換性をどのように検証しますか？
Pactの双方向契約が不可能な外部消費者については、トラフィックシャドウイングとVCRテストを使用して合成消費者シミュレーションを実装します。生産パターンを記録して代表的なモックを作成し、これを新しいAPIバージョンに対して再生します。自動ロールバックトリガーを持つカナリアデプロイと組み合わせ、複数の四半期にわたる必須の非推奨通知を持つ公共APIに対する厳格なLTSポリシーを維持します。