Le bug qui m'a appris à arrêter de differrer JSON comme texte m'a coûté la majeure partie d'un week-end Un webhook de paiement sur une course Laravel SaaS I a commencé à échouer silencieusement après un fournisseur & quot ; non-breaking" ; Mise à jour de l'API - leurs mots, du journal des modifications J'ai retiré une charge utile avant la mise à jour de nos journaux, j'en ai saisi une nouvelle et j'ai jeté les deux dans une diff de texte régulière Chaque ligne s'est allumée Le fournisseur avait changé son sérialiseur, qui réorganisait chaque clé par ordre alphabétique et changeait l'indent de quatre espaces à deux. Six cents lignes changées, et quelque part là, et une différence réelle. J'ai lu cette différence deux fois avant de diff : j'ai trouvé amount avait changé depuis le numéro 1099 à la chaîne "1099". Mêmes personnages à l'écran. Différents types. Notre comparaison stricte l'a rejeté, la file d'attente l'a reproduit dans le sol et le texte diff avait enterré le seul changement significatif sous 599 cosmétiques.
That' ; est le problème fondamental : JSON est un format de données, mais une différence de texte le traite comme de la prose. Ordre clé, espace, indentation, lignes nouvelles traînantes - rien de tout cela ne signifie rien pour un analyseur JSON, et tout cela apparaît comme des changements dans une comparaison basée sur des lignes. Par RFC 8259, un objet JSON est un non ordonné Collection de paires nom/valeur. Deux documents peuvent être différents pour octets et sémantiquement identiques. Un outil qui compare ligne par ligne JSON répond à la mauvaise question.
un Outil de diff JSON répond à la bonne. Il analyse les deux documents dans les arbres et compare les valeurs: cette clé a été ajoutée, cette clé a été supprimée, cette valeur est passée de X à Y, et - celle qui a sauvé mon week-end, si elle existait alors dans l'onglet de mon navigateur - cette valeur a changé taper à la. Lorsque j'ai construit le Diff Checker pour Toolz.dev, la détection de changement de type était la première fonctionnalité de la liste, car c'est la classe de changement que les diffs de texte sont structurellement incapables de faire surface et qui cassent le plus souvent les systèmes réels.
Ce guide couvre le fonctionnement de la comparaison structurelle, quand l'ordre des tableaux devrait et devrait & #39 ; cela compte, et les flux de travail de débogage - régressions d'API, dérive de configuration, audits de manifestes de packages - où une différence JSON se paie chaque semaine.
tl;dr : Collez deux documents JSON dans le Vérificateur de différentiel JSON Toolz.dev Et obtenez une comparaison structurelle : des clés ajoutées, supprimées et modifiées avec des chemins exacts comme
features.rateLimitouusers[3].email- plus un signalement séparé lorsqu'une valeur change taper à la (le3000→"3000"bogue). L'ordre et la mise en forme des clés ne produisent jamais de faux positifs. Tout fonctionne dans votre navigateur, rien n'est téléchargé. associez-le à la Formateur JSON Pour nettoyer les documents en premier et le Outil de diff de texte Pour le contenu où les lignes sont réellement importantes.
Qu'est-ce que cela signifie structurellement différer ?
Une diff structurelle analyse les deux documents dans leurs arbres de données réels et les rassemble, clé par clé, élément par élément À chaque nœud, elle demande : cette clé existe-t-elle des deux côtés ? les valeurs sont-elles du même type ? Sont-elles égales ? La sortie est & #39 ; t " ; ligne 14 changée" ; - it & #39 ; est une liste de faits sur vos données :
versionchangé de"1.4.0"à"1.5.0"features.metricsa été ajouté avec valeurtrueportType modifié d'un numéro à une autretags[2]a été ajouté avec valeur"monitored"
Chaque différence porte son chemin complet JSON, donc dans un document profondément imbriqué, vous savez exactement où chercher. users[12].address.postalCode Vous indique quel utilisateur, quel champ, aucun défilement requis.
Le contraste avec un diff de texte est le plus frappant sur les documents du monde réel. prendre un package.json régénéré par une version différente de npm, une réponse API après que l'équipe backend ait mis à niveau son sérialiseur, ou un fichier de configuration exécuté par un formateur Diff texte : des centaines de lignes modifiées Diff structurelle : les trois changements qui se sont réellement produits, ou la réponse honnête qu'il n'y en a pas - " ; structurellement identique" ; - qui est elle-même précieuse Confirmant qu'un refactor risqué est produit nul Les changements de données sont la moitié de la raison pour laquelle je parviens à cet outil.
There' ;s a place for line diffs, to be clear Prose, code, HTML, tout ce qui est où la disposition physique porte du sens - that' ;s Diff de texte territoire. Mais la disposition de JSON n'a aucune signification par spécification, et une comparaison qui prétend, autrement, génère du bruit que vous devez ensuite filtrer avec vos yeux.
Pourquoi les changements de type méritent-ils leur propre catégorie ?
Parce qu'ils sont invisibles dans toutes les autres vues des données, et qu'ils cassent les choses qui sont misérables pour déboguer.
1099 et "1099" restituer de manière identique dans un fichier journal, un terminal et la plupart des diff de texte - les guillemets sont faciles à manquer à 2 heures du matin. Mais pour tout consommateur dactylographié, ce sont des valeurs différentes. JavaScript' ; s === rejette la comparaison. Un schéma JSON déclarant "type": "integer" Échec de la validation. un service de rendez-vous sans marquage dans un int64 renvoie une erreur ; un désérialiseur Jackson strict dans Java lance. PHP est célèbre pour pardonner avec des comparaisons lâches, mais dès que vous activez des types stricts - ce que devrait faire chaque base de code moderne de Laravel - "1099" Cesse d'être de l'argent et commence à être une exception.
La partie la plus méchante est alors que Ces changements viennent de. Presque jamais d'un développeur qui édite délibérément une valeur. Ils proviennent de swaps de sérialiseur, de mises à niveau ORM, une colonne de base de données migrant à partir de INT à VARCHAR, une couche de mise en cache qui string des nombres, ou une passerelle d'API bien intentionnée "normalisant" charge utile. Personne n'écrit une entrée de journal des modifications pour eux, car personne ne sait qu'ils se sont produits.
Alors le Vérificateur de différentiel JSON signale les changements de type comme leur propre catégorie - ! dans le rapport copiable, distinct des changements de valeur ordinaires - avec les anciens et les nouveaux types épelés Lorsque vous et n°39 ; regardez un résumé qui dit 0 added, 0 removed, 0 changed, 1 type changed, vous savez précisément quel genre de bug que vous chassez avant d'avoir lu un seul chemin.
Comment comparez-vous deux fichiers JSON avec l'outil ?
Étape 1 : Collez les deux documents
JSON d'origine (ou bien connu) va dans le panneau de gauche, mis à jour (ou suspect) JSON à droite. La convention n'a d'importance que pour la lecture de la sortie : "ajoute" signifie présent à droite mais pas à gauche, "supprimé" signifie l'inverse. Si vous comparez un environnement de travail à un environnement de travail cassé, mettez le travail à gauche et le diff se lit comme "ce qui a changé".
Il y a & #39 ; est un bouton Charger un échantillon qui remplit les deux panneaux avec une petite configuration de service exerçant chaque type de différence - changement de valeur, ajout, changement de type, croissance du tableau - ce qui est le moyen le plus rapide d'apprendre comment se lit la sortie.
Étape 2 : Décidez si la commande de tableau est importante
C'est la seule option à laquelle vous devez penser, et la bonne réponse dépend de ce que vos tableaux hargneux- plus sur ce ci-dessous La valeur par défaut est sensible à l'ordre, ce qui correspond à la spécification JSON. Tick " ; Ignorez l'ordre et le devis du tableau ; lorsque vos tableaux sont sémantiquement définis.
Étape 3 : Comparez
Les deux documents sont validés avant que quoi que ce soit ne soit comparé Si l'un ou l'autre côté a une erreur de syntaxe - virgule de fin, guillemets simples, clé non citée, les suspects habituels - vous obtenez le message exact parser' ; s et, surtout, De quel côté ça vient de. Pas de défaillance silencieuse, pas de comparaison des ordures à moitié analysées. Si vous n'êtes pas sûr que votre JSON est valide, exécutez-le via le Formateur JSON Premièrement, il valide et s'imprime en une seule étape.
Étape 4 : Lisez le résumé, puis le tableau
La ligne de résumé vous donne des comptes par catégorie - ajoutée, supprimée, modifiée, type modifié - ce qui est souvent tout ce dont vous avez besoin. " ; 47 ajouté, 0 supprimé, 0 modifié" ; après une version API, bump signifie de nouveaux champs uniquement : sûr. " ; 0 ajouté, 3 supprimé" ; signifie que les champs dont vos consommateurs pourraient dépendre viennent de disparaître : non sûr. Le tableau ci-dessous répertorie chaque différence avec son chemin, son ancienne valeur et sa nouvelle valeur, tronqués pour plus de lisibilité sur de longues valeurs.
Étape 5 : Copiez le rapport
Le bouton Copier le rapport produit un résumé en texte brut avec + / - / ~ / ! marqueurs et chemins complets - conçus pour coller directement dans un commentaire de demande d'extraction, un fil incident Slack ou un ticket. " ; Ici et n°39 ; c'est exactement ce qui a changé entre la configuration et la configuration de production ; avec reçus, en un clic.
Quand devez-vous ignorer l'ordre du tableau ?
Les tableaux JSON sont classés par spécification - [1, 2] et [2, 1] sont des documents différents, et la comparaison par défaut respecte cela. Mais la spécification décrit le conteneur, et non votre intention, et dans la pratique, les tableaux sont utilisés de deux manières différentes :
Tableaux comme séquences, où position signifie : chaînes middleware qui s'exécutent dans l'ordre, listes de migration, classements triés, résultats paginés La réorganisation de ceux-ci est un vrai changement - une pile middleware qui s'exécute auth après handle est une application différente (et probablement cassée). Gardez la sensibilité des commandes.
Tableaux en tant que jeux, où la position est un accident : listes de balises, affectations de rôle, drapeaux de fonctionnalité, ID renvoyés par une requête de base de données sans ORDER BY. Postgres est entièrement dans son droit de retourner les mêmes lignes dans un ordre différent sur différentes courses, et si votre diff s'allume à cause de cela, ce & #39 ; s bruit. C'est ce que le " ; Ignore array order" ; option est pour - les éléments sont appariés quelle que soit la position, donc ["admin", "editor"] égaux ["editor", "admin"].
Ma règle d'or à partir d'années de comparaison des charges utiles de l'API : si le backend applique un tri explicite, traitez le tableau comme une séquence ; si ce n'est pas le cas, c'est un ensemble que les auteurs l'aient réalisé ou non, et une comparaison insensible aux commandes vous dit la vérité sur les données.
Diff structurel vs texte Diff vs Inspection manuelle
| Diff structural JSON | Texte/ligne différentiel | le regarder | |
|---|---|---|---|
| Clés réorganisées | Aucune différence signalée | Chaque ligne déplacée marquée | Changements faciles à manquer |
| Espace blanc reformaté | Aucune différence signalée | Tout signalé | N/A |
Changement de type (1 → "1") |
Marqué comme changement de type | Deux caractères dans une mer de lignes | Presque invisible |
| Changer de lieu imbriqué | Chemin exact : a.b[2].c |
Numéro de ligne dans formaté texte | Traversée manuelle |
| Réorganisation du tableau (intentionnelle) | Marqué (ou ignoré, votre choix) | médiocre | Dépend de la taille du tableau |
| le mieux pour | JSON, charges utiles API, configurations | Code, prose, balisage | Documents à deux lignes |
| Mode de panne | Aucun sur JSON valide | Les faux positifs enterrent les changements réels | fatigue humaine |
Le résumé honnête : les diffs de texte sont & #39 ; t faux, ils & #39 ; répondent à une question différente - " ; les octets ont-ils changé ?" ; Pour JSON, vous voulez presque toujours " ; a-t-il répondu données Changez ?", et ces questions ont des réponses différentes, étonnamment.
Quels sont les flux de travail réels pour un diff JSON ?
Régression des API de débogage
Le workflow de mon histoire de webhook, maintenant systématisé : capturez une charge utile d'avant le changement (logs, un luminaire enregistré, votre suite de test' ; s snapshot) et une d'après Panneau gauche, panneau droit, Comparer La diff vous indique en quelques secondes ce que le prestataire' ; s changelog a fait' ; t - quels champs ont bougé, lesquels ont changé de type, qui ont discrètement disparu Je fais cela chaque fois qu'une API tierce annonce une bosse de version, des avant L'ancienne version s'éteint et classez le rapport dans le ticket de mise à niveau.
Attraper la dérive de la configuration
Travaux de mise en scène, production n°39 ; t, et les deux étaient " ; déployés à partir de la même configuration." ; Étaient-ils ? Exporter les deux - environnement JSON, a docker inspect sortie, un configmap de Kubernetes est vidé avec -o json- et diff les. La dérive de configuration est presque toujours d'une ou deux touches, et la colonne de chemin vous y emmène directement. Cela bat diff <(jq -S . a.json) <(jq -S . b.json) dans un terminal car il capture également des changements de type, qui jq-Les diffs de texte normalisés rendent presque de manière invisible.
Examen des modifications apportées au fichier de verrouillage et au manifeste
un package.json ou composer.json cela a été mutilé par des fusions contradictoires ou par une spécification OpenAPI générée après une mise à niveau du framework : la différence structurelle vous montre la dépendance change sans le bruit du formatage régénéré. Pour le travail du plugin WordPress - WP Adminify envoie les paramètres sous forme de JSON - je diff le schéma de paramètres exporté entre les versions pour m'assurer qu'un refactor n'a pas été utilisé et n°39 ; ne supprimez pas une clé dont dépendent des milliers d'installations. Une suppression accidentelle apparaît comme un - Line; dans un texte différent d'une exportation de paramètres de 4 000 lignes, il apparaît comme rien du tout.
Vérification des migrations de données
Avant : exporter un enregistrement représentatif en tant que JSON. Après la migration : exportez-le à nouveau. Le diff doit montrer exactement les changements que la migration a voulues et pas d'autre. "Structurement identique" sur un record qui n'aurait pas dû être touché est le test de régression le moins cher que vous aurez jamais effectué. Cela s'accorde bien avec la conversion des exportations tabulaires via CSV à JSON Lorsque les données sortent de la base de données en tant que CSV.
Comparaison des réponses environnementales
Appuyez sur le même point de terminaison dans deux environnements, diff les réponses. Les champs présents dans le développement mais manquants dans la production signifient généralement un indicateur de fonctionnalité, un déploiement obsolète ou une variable d'environnement qui n'a jamais été définie. Le nombre de résumés à lui seul est souvent diagnostiquer.
Pourquoi le traitement côté client est-il plus important pour cet outil que la plupart des autres ?
Pensez à ce que vous collez dans un diff JSON : réponses API avec les e-mails des clients, fichiers de configuration avec des noms d'hôtes internes, charges utiles de webhook avec métadonnées de paiement, exportations de bases de données. Ce sont exactement les données qui ne doivent pas fuir, collées exactement au moment - à mi-incident - où personne n'audit quel outil en ligne vient de les recevoir.
le Vérificateur de différentiel Toolz.dev analyse et compare entièrement dans votre navigateur Aucune requête ne transporte vos documents nulle part ; l'outil fonctionne hors ligne une fois la page chargée, ce que vous pouvez vérifier en coupant votre réseau et en comparant à nouveau Ceci est' ; t une fonctionnalité premium ou une promesse de stratégie qui pourrait changer - it' ; s l'architecture La logique de comparaison est du JavaScript pur fonctionnant sur deux arbres analysés en mémoire Il n'y a pas de composant serveur à qui envoyer des données.
Le même argument de confidentialité s'applique à l'ensemble de la boîte à outils - it' ; c'est la raison pour laquelle le Boîte à outils pour développeur sur Toolz.dev est construit en premier par navigateur - mais les outils de comparaison sont là où il et n°39 ; est le plus aigu, car comparer deux Les documents de production doublent l'exposition d'un collage.
Quelle taille de document pouvez-vous comparer ?
La comparaison visite chaque nœud des deux arbres une fois, de sorte que le travail évolue linéairement avec la taille du document. En pratique : des documents de centaines de kilo-octets comparent instantanément ; un faible chiffre des mégaoctets se termine bien en moins d'une seconde sur tout ce qui ressemble à un ordinateur portable moderne ; des dizaines de mégaoctets fonctionneront mais vous le sentirez, car le navigateur doit analyser les deux documents et contenir les deux arbres en même temps.
Deux conseils pratiques pour les charges utiles très importantes Tout d'abord, si vous ne vous souciez que d'une partie du document, comparez juste ce sous-arbre - collez response.data.items des deux côtés plutôt que l'enveloppe complète. Deuxièmement, si le diff produit des milliers d'entrées, c'est généralement un signe qu'un côté est différent forme (un tableau enveloppé dans un objet, un niveau d'imbrication supplémentaire) - vérifiez les premiers chemins avant de faire défiler ; ils et n°39 ; vous diront si vous et n°39 ; envisagez un changement structurel en cascade ou des milliers de véritables.
FAQ
Comment comparer deux fichiers JSON en ligne ?
Ouvrez le Vérificateur de différentiel JSON« Coller un document dans le panneau de gauche et l'autre dans le panneau de droite, et cliquez sur Comparer » Vous obtenez une liste catégorisée de chaque valeur ajoutée, supprimée, modifiée et modifiée par type avec son chemin JSON exact Les deux documents sont traités entièrement dans votre navigateur - rien n'est téléchargé sur aucun serveur.
Pourquoi un diff textuel affiche-t-il tant de changements lorsque mes données JSON sont les mêmes ?
Parce que les diffs de texte comparent les lignes et JSON permet d'écrire les mêmes données de plusieurs manières. Les clés réorganisées, l'indentation différente et les espaces blancs changent tous le texte sans changer les données. Un différentiel structurel analyse les deux documents en premier et compare les valeurs réelles, de sorte que les différences de formatage ne produisent aucun changement signalé.
L'ordre des clés dans un objet JSON est-il important ?
non RFC 8259 définit un objet JSON comme une collection non ordonnée de paires nom/valeur, donc {"a":1,"b":2} et {"b":2,"a":1} sont le même objet Le vérificateur de différences compare les objets par nom de clé et ne signale jamais la réorganisation comme un changement L'ordre des éléments de tableau, en revanche, est significatif par défaut - les tableaux sont ordonnés dans la spécification.
Quand dois-je utiliser l'option "Ignorer le tableau" ?
Utilisez-le lorsque vos tableaux sont sémantiquement des ensembles plutôt que des séquences - listes de balises, collections de rôles, ID d'une requête de base de données non triée Avec l'option sur, [1,2,3] et [3,1,2] comparer comme égal. Laissez-le lorsque la position a un sens, comme les chaînes de middleware ordonnées, les résultats classés ou les listes paginées.
Qu'est-ce qu'un changement de type et pourquoi est-il signalé séparément ?
Un changement de type se produit lorsqu'une valeur & #39 ; s Le type JSON diffère d'un document à l'autre même s'il se présente de la même manière - le nombre 3000 devenir la ficelle "3000" est le cas classique. Il est signalé séparément car il casse les consommateurs stricts, la validation de schéma et les contrôles d'égalité stricts tout en étant presque invisibles dans les diffs et les journaux de texte. C'est l'une des causes les plus courantes de régressions d'intégration d'API.
Puis-je partager le résultat de la comparaison avec mon équipe ?
Oui. Le bouton Copier le rapport génère un rapport de Diff en texte brut avec + (ajouté), - (supprimé), ~ (modifié), et ! (Type modifié) Marqueurs et chemins JSON complets pour chaque différence. Il est formaté pour coller proprement dans les commentaires de demande d'extraction, les threads de ralentissement et les suivis de problèmes.
Est-il sûr de coller les réponses de l'API de production dans l'outil ?
Oui. L'analyse et la comparaison s'exécutent entièrement en JavaScript dans votre navigateur : aucune demande réseau n'est effectuée avec vos données, rien n'est enregistré ou stocké et l'outil continue de fonctionner hors ligne. Cela le rend sûr pour les charges utiles contenant des données client, des noms d'hôte internes ou des informations d'identification, bien que la rédaction de secrets avant de partager le dénoncer est toujours sur vous.
Que se passe-t-il si l'un de mes documents n'est pas valide JSON ?
L'outil valide les deux côtés avant de comparer et rapporte le message d'erreur exact parser' ; ainsi que de quel côté il vient - gauche ou droite. Les coupables courants sont les virgules traînantes, les guillemets simples au lieu du double et les touches non citées. Résolvez le problème signalé ou exécutez le document via le Formateur JSON Pour localiser le problème, puis comparez à nouveau.
La comparaison structurelle est l'un de ces outils qui modifie les bogues que vous pouvez même examiner. Les diffs textuels répondent à " ; les octets ont-ils changé ?" ; pour JSON, la question qui compte est " ; les données ont-elles changé ?" ; - et pour les charges utiles, les config et les manifestes de l'API qui exécutent vos systèmes, le Vérificateur de différentiel JSON y répond en quelques secondes, dans votre navigateur, vos données ne quittant jamais votre machine Plus de workflows JSON - formatage, validation, conversion - en direct dans le Guide des outils de codage.
