Le bug qui m'a appris à ne pas différer JSON car le texte m'a coûté la majeure partie d'un week-end. Un webhook de paiement sur un SaaS de Laravel que je lance a commencé à échouer en silence après une mise à jour de l'API "non-rupture" de fournisseur - leurs mots, à partir du changement de journal. J'ai retiré une charge utile avant la mise à jour de nos journaux, j'en ai pris une nouvelle et j'ai jeté les deux dans un texto régulier. Chaque ligne s'est allumée. Le fournisseur avait changé de sérialiste, qui a réorganisé chaque clé par ordre alphabétique et changé l'indentation de quatre espaces à deux. Six cents lignes changées, et quelque part là-dedans, une vraie différence. J'ai lu ce diff de haut en bas deux fois avant de le trouver: 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.
C'est le problème fondamental : JSON est un format de données, mais un diff de texte le traite comme de la prose. Ordre clé, espace blanc, indentation, nouvelles lignes de suivi - rien de tout cela ne signifie quoi que ce soit pour un analyseur JSON, et tout cela apparaît sous forme de changements dans une comparaison basée sur la ligne. selon 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 enregistré mon week-end, si elle avait existé dans l'onglet de mon navigateur, puis 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 explique comment fonctionne la comparaison structurelle, lorsque la commande de tableau doit et ne devrait pas avoir d'importance, et les flux de travail de débogage - régressions d'API, dérive de configuration, audits de package-manifeste - où un diff JSON se rentabilise 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 le marquage 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 ?
Un différentiel structurel analyse les deux documents dans leurs arbres de données réels et les accompagne, clé par clé, élément par élément. À chaque nœud, il demande : cette clé existe-t-elle des deux côtés ? Les valeurs sont-elles du même type ? Sont-ils égaux ? La sortie n'est pas "Ligne 14 modifiée" - c'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 d'API après que l'équipe de backend ait mis à niveau son sérialiseur ou un fichier de configuration exécuté via un formateur. Diff de texte : centaines de lignes modifiées. Diff structurel : 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 lui-même précieux. Confirmant qu'un refactoring risqué produit nul Les changements de données sont la moitié de la raison pour laquelle je parviens à cet outil.
Il y a une place pour les diffs de ligne, pour être clair. Prose, code, HTML, tout ce qui porte un sens à la disposition physique, c'est-à-dire 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" Rendu de manière identique dans un fichier journal, un terminal et la plupart des diffs de texte - les guillemets sont faciles à manquer à 2 heures du matin. Mais pour tout consommateur typé, il s'agit de valeurs différentes. === 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 strict de Jackson dans Java Throws. PHP est réputée pardonner avec une comparaison lâche, mais au moment où vous activez les types stricts, ce que chaque base de code Laravel moderne devrait - "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 Les types de rapports sont modifiés comme leur propre catégorie — ! Dans le rapport copiable, distinct des changements de valeur ordinaires, avec les anciens et les nouveaux types énoncés. Lorsque vous 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 existe un exemple de bouton de chargement 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 - qui est le moyen le plus rapide d'apprendre comment la sortie se lit.
É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 d'informations à ce sujet ci-dessous. La valeur par défaut est sensible à l'ordre, qui correspond à la spécification JSON. Cochez "Ignorer la commande de tableau" lorsque vos tableaux sont définis de manière sémantique.
Étape 3 : Comparez
Les deux documents sont validés avant que quoi que ce soit soit comparé. Si une erreur de syntaxe est associée à une erreur de syntaxe - virgule à la fin, guillemets simples, clé non indiquée, les suspects habituels - vous obtenez le message exact de l'analyseur 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, suppression, modification, type modifié) qui est souvent tout ce dont vous avez besoin. "47 Ajoutés, 0 supprimé, 0 modifié" après une version de la version API signifie uniquement de nouveaux champs : sans danger. "0 ajouté, 3 champs supprimés signifie que les consommateurs peuvent dépendre de leur juste valeur : pas sûr. Le tableau ci-dessous répertorie chaque différence avec son chemin, son ancienne valeur et sa nouvelle valeur, tronquée pour la lisibilité sur des valeurs longues.
É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 d'incident Slack ou un ticket. "Voici exactement ce qui a changé entre la mise en scène et la configuration de la production" avec les reçus, en un clic.
Quand devez-vous ignorer l'ordre du tableau ?
Les tableaux JSON sont classés par spécifications : [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ù la position signifie : les chaînes de middleware qui s'exécutent dans l'ordre, les listes de migration, les classements triés, les résultats paginés. Réorganiser ces modifications est un véritable 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 a entièrement le droit de retourner les mêmes lignes dans un ordre différent sur des courses différentes, et si votre diff s'allume à cause de cela, c'est du bruit. C'est à cela que sert l'option "Ignorer le tableau" - les éléments sont adapté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 ne sont pas faux, ils répondent à une autre question – "Les octets ont-ils changé ?" Pour JSON, vous voulez presque toujours "le fait de la 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 flux de travail de My Webhook Story, désormais systématisé : capturez une charge utile d'avant le changement (logs, un luminaire enregistré, instantané de votre suite de tests) et un après. Panneau de gauche, panneau de droite, comparer. Le diff vous indique en quelques secondes ce que le journal des modifications du fournisseur n'a pas fait - quels champs ont déménagé, qui a changé de type, qui a discrètement disparu. Je le fais à chaque fois qu'une API tierce annonce une version bosse, avant L'ancienne version s'éteint et classez le rapport dans le ticket de mise à niveau.
Attraper la dérive de la configuration
Les travaux de mise en scène, la production n'est pas "T", et les deux étaient "déployés 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 les differ. Config Drift est presque toujours une ou deux clés, et la colonne de chemin vous emmène directement là-bas. 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 en conflit ou une spécification OpenAPI générée après une mise à niveau du cadre : structure diff vous montre les modifications de dépendance sans le bruit de la mise en forme régénérée. Pour le travail du plugin WordPress - WP Adminify Ships as JSON - Je diff le schéma des paramètres exportés entre les versions pour s'assurer qu'un refactor n'a pas déposé une clé dont dépendent des milliers d'installations. Un retrait accidentel 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 des e-mails des clients, des fichiers de configuration avec des noms d'hôte internes, des charges utiles de webhook avec des métadonnées de paiement, des exportations de base de données. Ce sont exactement les données qui ne doivent pas fuir, collées exactement au moment - au milieu d'incidents - lorsque personne n'audit quel outil en ligne vient de le recevoir.
le Vérificateur de différentiel toolz.dev analyse et compare entièrement dans votre navigateur. Aucune demande ne transporte vos documents n'importe où ; 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. Ce n'est pas une fonctionnalité premium ou une promesse politique qui pourrait changer - c'est l'architecture. La logique de comparaison est pure Javascript fonctionnant sur deux arbres analysés en mémoire. Il n'y a pas de composant de serveur auquel envoyer des données.
Le même argument de confidentialité s'applique à l'ensemble de la boîte à outils - c'est la raison pour laquelle le Boîte à outils pour développeur sur Toolz.dev est construit en premier, mais les outils de diff sont là où ils sont les plus aigus, car la comparaison 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 très grosses charges utiles. Tout d'abord, si vous ne vous souciez qu'une partie du document, comparez uniquement ce sous-arborescence — Coller 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 vous diront si vous envisagez un changement structurel en cascade ou des milliers d'authentiques.
FAQ
Comment comparer deux fichiers JSON en ligne ?
Ouvrez le Vérificateur de différentiel JSON, collez un document dans le panneau de gauche et l'autre dans la droite, puis cliquez sur Comparer. Vous obtenez une liste catégorisée de chaque valeur ajoutée, supprimée, modifiée et modifiée avec son chemin JSON exact. Les deux documents sont entièrement traités dans votre navigateur. Rien n'est téléchargé sur un 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érentiel compare les objets par nom de clé et ne signale jamais de réorganisation comme un changement. Par défaut, l'ordre des éléments de tableau est significatif par défaut : les tableaux sont classés dans la spécification.
Quand dois-je utiliser l'option "Ignorer le tableau" ?
Utilisez-le lorsque vos tableaux sont définis de manière sémantique 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 est celui lorsqu'une valeur JSON est différente entre les documents, même si elle est similaire, 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 sont entièrement exécutées en JavaScript dans votre navigateur. Aucune requête réseau n'est effectuée avec vos données, rien n'est enregistré ou stocké, et l'outil continue de fonctionner hors connexion. Cela rend sûr les charges utiles contenant des données client, des noms d'hôte internes ou des informations d'identification, tout en rédigeant les 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 de l'analyseur avec de quel côté il provenait - à gauche ou à droite. Les coupables courants sont des virgules de fin, des guillemets simples au lieu de clés doubles et non cotées. Résolution du 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 de texte 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 configurations et les manifestes de l'API qui exécutent vos systèmes, le Vérificateur de différentiel JSON Réponds-y en quelques secondes, dans votre navigateur, avec vos données qui ne quittent jamais votre machine. Plus de workflows JSON — formatage, validation, conversion — en direct dans le Guide des outils de codage.
