API を v1 から v2 にアップグレードした後: JSON 応答に新しいフィールドは何ですか?重大な変更はありますか? 500 行の応答と行ごとの比較により、ネストされたオブジェクトの奥深くにある変更を見逃しがちです。
フロントエンド、バックエンド、テスト エンジニアを対象としたこの記事では、JSON Diff の原則、使用例、5 ステップのワークフロー、配列の順序や浮動小数点精度などの落とし穴について説明します。その後、JSON Toolbox の diff 関数を使用して、アップロードせずにブラウザーでローカルに完全な API 変更監査を実行できます。
API アップグレード後に JSON Diff が必須となる理由
マイクロサービスとフロントエンド/バックエンドの分離では、API コントラクトがコラボレーションの基礎となります。一見「下位互換性がある」アップグレードでは、フィールドの削除、配列構造の変更、文字列から数値への変換がサイレントに実行される可能性があります。クライアントは運用環境でのみこれに気づきます。
日常生活から: ユーザー リスト API v2 は、pagination.total を数値から文字列に変更しました。古いモバイル クライアントは白い画面でクラッシュしました。リリース前に v1/v2 のサンプル応答を JSON Diff と比較していれば、タイプの変更は数秒でマークされていたでしょう。
JSON 差分とは何ですか
JSON Diff は、2 つの JSON ドキュメントを構造化された方法で比較し、追加、削除、および変更されたフィールドを強調表示します。 Text-Diff とは異なり、JSON 階層を理解し、純粋なインデント/改行の違いを無視します。
テキストの差分との主な違い
| 比較次元 | JSON の差分 | テキストの差分 (例: git diff) |
|---|---|---|
| JSON 構造を理解する | ✅ フィールドパスによる比較 | ❌ ライン比較 |
| 空白を無視する | ✅ 構造別 | ⚠️ その他のフォーマット = ノイズ |
| 入れ子になったフィールド | ✅ $.user.email のようなパス | ⚠️ 階層を手動で検索する |
| APIレビュー | ✅ おすすめ | ⚠️最初にフォーマットが必要です |
差分結果の読み取り
- 緑色 / 追加: 右側の JSON のみのフィールド
- 赤 / 削除済み: 左側の JSON のみのフィールド
- 黄色 / 変更済み: 同じパス、異なる値
- 強調なし: 構造は同一
JSON Diff が適している人
| 役割 | 典型的なシナリオ | 使用するには |
|---|---|---|
| フロントエンド | デバッグ時のモック API 応答と実際の API 応答 | フィールドが欠落しているか、タイプが早期に変更されます |
| バックエンド | APIバージョン前後のレスポンス | 変更履歴、重大リリースの減少 |
| テスト | 回帰におけるベースラインと現在の応答 | アサートエラーをより迅速に特定する |
| DevOps/SRE | デプロイ前/後の構成 (例: K8s ConfigMap JSON) | リリース内容を確認する |
典型的な使用例
- API バージョンの回帰: v1 と v2 の応答構造
- 構成監査: デプロイメント前後の JSON
- ETL/移行: スクリプト出力と期待値
- コードレビュー: 大きな JSON フィクスチャを素早くスキミングする
実践: API 変更レビューへの 5 つのステップ
JSON Toolbox Diff ツールを使用したワークフロー — ブラウザー内でローカルに、内部サンプル用にも (トークン、事前にパスワードを削除)。
- 古い回答を保存: v1 の例またはドキュメントを Baseline.json として保存
- 新しい答えを得る: v2 API または更新されたモックデータ
- オプションの書式設定: 空白ノイズを避けて、両面を適切に書式設定します。
- diff を実行: 両方の JSON を左右に挿入し、「比較を開始」
- 文書の相違点: CHANGELOG またはテストでマークされた点を確認してください
例: 2 つのユーザー API 応答
JSON A (v1、古い):
{
"name": "Alice",
"age": 30,
"tags": ["dev", "json"],
"profile": {
"city": "Shanghai",
"level": "senior"
}
}JSON B (v2、新規):
{
"name": "Alice",
"age": 31,
"tags": ["dev", "tools"],
"active": true,
"profile": {
"city": "Beijing",
"level": "senior"
}
}相違点: 年齢 30 → 31;タグの内容が変更されました。プロフィール.都市 上海 → 北京;アクティブな新しい。これがリリース ノートに記載されていない場合、クライアントの互換性の問題が発生するリスクがあります。
ヒントと典型的な落とし穴
まずフォーマットしてから比較する
一方のページは縮小され、もう一方のページは複数行になります。テキストの差分によりノイズが発生します。両方をフォーマットしてから、セマンティックな変更のみを考慮してください。
配列の順序 ≠ 内容の変更
同じコンテンツ、異なる順序 — JSON Diff は多くの変更を示すことができます。ビジネスを明確にする: 配列は順序付けされたもの (タイムライン) ですか、それとも単なるセットですか?
浮動小数点とその型
- 1.0 対 1,000 は変化としてカウントできます - 必要に応じて正規化します
- 文字列「123」対 123 番 – さまざまなタイプ、多くの場合破壊的な変更
- null と欠落フィールド — 異なるセマンティクス、diff は両方を分離します
機密データを削除する
比較する前に、access_token、password、ID をプレースホルダー (例: "***") に置き換えます。 JSON Toolbox は純粋にフロントエンドで実行されます。削除することは引き続き推奨事項です。
他のメソッドとの JSON の差分
| 方法 | スピード | フィールドパスを認識する | 大きなJSON | 学習努力 |
|---|---|---|---|---|
| JSON 差分ツール | 速い (秒) | ✅ | ✅ おすすめ | 少量 |
| 手動比較 | 遅い、まだら模様 | ❌ | ❌ 最大 100 行から重い | 少量 |
| git diff (テキスト) | 速い | ⚠️フォーマット後 | ⚠️騒音が多い | 少量 |
| 自動テスト | CI で自動的に | ✅ | ✅ | 中（筆記テスト） |
| JSONスキーマ | 速い | ✅ 構造のみ | ✅ | 手段（スキーマの維持） |
ベスト プラクティス: 簡単なレビューのための開発時 JSON Diff → 自動テストでの重要な違い → メジャー リリース前に構造用の JSON スキーマ。お互いを置き換えるのではなく、補い合います。
よくある質問（FAQ）
JSON Diff は配列の順序を認識しますか?
はい。注文の変更は変更としてマークされます。順序付けされていない配列の場合は、機能的に関連しているかどうかを手動で評価します。
同一の JSON の差分は何を示していますか?
「両方の JSON は同一である」ことに注意してください - 強調表示はありません。
JSON Diff はどのくらいの大きさのファイルをサポートしますか?
ブラウザでローカルに。 2 MB を超えると途切れる可能性があり、10 MB を超えると分割または CLI (jq、jsondiffpatch) が発生する可能性があります。
データはサーバーにアップロードされますか?
いいえ。純粋なフロントエンド アーキテクチャ — 内部 API サンプルであっても、ブラウザ内で完全に Diff します。
差分結果をエクスポートできますか?
現在ページ内でハイライト表示されています。アーカイブの場合: スクリーンショットまたは差分を CHANGELOG にコピーします。
JSON Diff と JSON スキーマの違いは何ですか?
Diff は 2 つの JSON を相互に比較します。事前定義された構造に対してスキーマがチェックされます。リリース前に両方を組み合わせてください。
結論と次のステップ
API のアップグレード、構成の移行、またはデータの同期後、JSON Diff は、「サイレント」破壊的変更に対する最も効率的な手段の 1 つです。重要なポイント: フォーマット → 色付きのマーキングを確認 → 変更ログまたはテストに記録します。
フロントエンド/テスト: デバッグ中、アップグレード直後にベースラインを保存します。バックエンド: PR テンプレートのリリース ゲートとして v1/v2 の差分スクリーンショットが必要です。