Après la mise à niveau de l'API de la v1 vers la v2 : quels champs sont nouveaux dans la réponse JSON ? Y a-t-il des changements importants ? Avec 500 lignes de réponse et une comparaison ligne par ligne, il est facile de manquer des changements profonds dans les objets imbriqués.
Destiné aux ingénieurs front-end, back-end et tests, cet article explique les principes de JSON Diff, les cas d'utilisation, un flux de travail en 5 étapes et les pièges tels que l'ordre des tableaux et la précision de la virgule flottante. Vous pouvez ensuite utiliser la fonction diff de JSON Toolbox pour effectuer un audit complet des modifications d'API localement dans le navigateur, sans téléchargement.
Pourquoi JSON Diff est obligatoire après les mises à niveau de l'API
Dans les microservices et la séparation frontend/backend, le contrat API constitue la base de la collaboration. Une mise à niveau apparemment « rétrocompatible » peut supprimer silencieusement des champs, modifier les structures de tableaux ou convertir des chaînes en nombres – les clients ne le remarquent qu'en production.
De la vie quotidienne : une API de liste d'utilisateurs v2 a modifié pagination.total de nombre en chaîne - les anciens clients mobiles tombaient en panne avec un écran blanc. Si vous aviez comparé les exemples de réponses v1/v2 avec JSON Diff avant la publication, le changement de type aurait été marqué en quelques secondes.
Qu'est-ce que JSON Diff
JSON Diff compare deux documents JSON de manière structurée et met en évidence les champs ajoutés, supprimés et modifiés. Contrairement à Text-Diff, il comprend la hiérarchie JSON et ignore les différences pures d'indentation/saut de ligne.
Différence fondamentale avec la différence de texte
| Dimension de comparaison | Différence JSON | Différence de texte (par exemple, git diff) |
|---|---|---|
| Comprendre la structure JSON | ✅ Comparaison par chemin de terrain | ❌ Comparaison de lignes |
| Ignorer les espaces | ✅ Par structure | ⚠️ Autre formatage = bruit |
| Champs imbriqués | ✅ Chemin comme $.user.email | ⚠️ Rechercher manuellement dans la hiérarchie |
| Révision des API | ✅ Recommandé | ⚠️ Formatage requis en premier |
Lire les résultats des différences
- Vert / ajouté : Champ uniquement dans le bon JSON
- Rouge / supprimé : Champ uniquement dans le JSON de gauche
- Jaune / modifié : même chemin, valeur différente
- Pas d'accent : structure identique
À qui JSON Diff convient-il
| rôle | Scénario typique | Pour utiliser |
|---|---|---|
| L'extrémité avant | Réponse API simulée ou réelle lors du débogage | Champs manquants ou modifications de type anticipées |
| Back-end | Réponse avant/après la version de l'API | Changelog, moins de versions de rupture |
| test | réponse de base par rapport à la réponse actuelle dans la régression | Identifiez les erreurs d’assertion plus rapidement |
| DevOps/SRE | Configuration avant/après le déploiement (par exemple K8s ConfigMap JSON) | Confirmer le contenu de la version |
Cas d'utilisation typiques
- Régression de la version de l'API : structure de réponse v1 vs v2
- Audit de configuration : JSON avant et après le déploiement
- ETL/Migration : sortie du script par rapport aux attentes
- Révision du code : parcourir rapidement les gros appareils JSON
Pratique : 5 étapes pour examiner les modifications de l'API
Workflow avec l'outil JSON Toolbox Diff — localement dans le navigateur, également pour des exemples internes (jeton, supprimer les mots de passe au préalable).
- Enregistrer l'ancienne réponse : exemple de la v1 ou de la documentation sous baseline.json
- Obtenez une nouvelle réponse : API v2 ou données fictives mises à jour
- Formatage facultatif : formatez correctement les deux côtés, en évitant le bruit des espaces
- Exécuter diff : Insérez les deux JSON gauche/droite, « Démarrer la comparaison »
- Documenter les différences : vérifier les points marqués dans CHANGELOG ou les tests
Exemple : deux réponses de l'API utilisateur
JSON A (v1, ancien) :
__PRÉSERVE_CODE_0__JSON B (v2, nouveau) :
__PRÉSERVE_CODE_1__Les différences : âge 30 → 31 ; le contenu des balises a été modifié ; profile.city Shanghai → Pékin ; actif nouveau. Si cela manque dans la note de version, il existe un risque de problèmes de compatibilité client.
Conseils et pièges typiques
Formatez d’abord, puis comparez
Une page réduite, l'autre multiligne - la différence de texte crée du bruit. Formatez les deux, puis ne considérez que les changements sémantiques.
Ordre du tableau ≠ changement de contenu
Même contenu, ordre différent — JSON Diff peut afficher de nombreux changements. Clarifier les affaires : le tableau est-il ordonné (chronologie) ou simplement un ensemble ?
Virgule flottante et types
- 1,0 contre 1 000 peut compter comme un changement – normaliser si nécessaire
- Chaîne "123" contre le numéro 123 – différents types, brisant souvent le changement
- champ nul ou manquant - sémantique différente, diff sépare les deux
Supprimer les données sensibles
Avant de comparer, remplacez le jeton d'accès, le mot de passe et les identifiants par des espaces réservés (par exemple "***"). JSON Toolbox fonctionne uniquement en front-end – la suppression reste une bonne pratique.
JSON Diff par rapport à d'autres méthodes
| méthode | vitesse | Reconnaître les chemins de champ | Gros JSON | Effort d'apprentissage |
|---|---|---|---|---|
| Outil de comparaison JSON | Rapide (secondes) | ✅ | ✅ Recommandé | Petite quantité |
| Comparaison manuelle | Lent, inégal | ❌ | ❌ Lourd à partir de ~100 lignes | Petite quantité |
| git diff (texte) | Rapide | ⚠️ Après le formatage | ⚠️ Beaucoup de bruit | Petite quantité |
| Tests automatisés | Automatiquement dans CI | ✅ | ✅ | Moyen (tests d'écriture) |
| Schéma JSON | Rapide | ✅Structure uniquement | ✅ | Moyens (maintenir le schéma) |
Meilleure pratique : dans Dev JSON Diff pour des examens rapides → différences importantes dans les tests automatisés → avant les versions majeures, schéma JSON pour la structure. Complétez-vous les uns les autres, ne vous remplacez pas.
Questions fréquemment posées (FAQ)
JSON Diff reconnaît-il l'ordre des tableaux ?
Oui. Les changements de commande sont marqués comme des modifications. Pour les tableaux non ordonnés, évaluez manuellement si cela est fonctionnellement pertinent.
Que montre la différence pour des JSON identiques ?
Notez « Les deux JSON sont identiques » – pas de mise en surbrillance.
Quelle est la taille des fichiers pris en charge par JSON Diff ?
Localement dans le navigateur. Au-dessus de 2 Mo, il peut bégayer, au-dessus de 10 Mo, il peut être divisé ou CLI (jq, jsondiffpatch).
Les données sont-elles téléchargées sur un serveur ?
Architecture frontend pure – Diff complètement dans le navigateur, même pour les exemples d'API internes.
Pouvez-vous exporter les résultats des différences ?
Actuellement mis en évidence dans la page. Pour l'archive : copiez la capture d'écran ou les différences dans CHANGELOG.
Différence JSON Diff et schéma JSON ?
Diff compare deux JSON entre eux ; Le schéma vérifie la structure prédéfinie. Combinez les deux avant la sortie.
Conclusion et prochaines étapes
Après une mise à niveau d'API, une migration de configuration ou une synchronisation de données, JSON Diff est l'un des moyens les plus efficaces contre les modifications avec rupture « silencieuses ». Points clés : format → vérifier les marquages colorés → enregistrer dans le changelog ou les tests.
Frontend/Test : enregistrez la ligne de base pendant le débogage, immédiatement après la mise à niveau du Diff. Backend : nécessite une capture d'écran des différences v1/v2 comme porte de sortie dans les modèles PR.