La requête pull avait 240 lignes modifiées et j'avais touché exactement deux valeurs C'était le moment où je prenais au sérieux le tri des clés JSON Un coéquipier avait fait passer un fichier de configuration à travers un formateur qui réorganisait ses clés, j'avais édité deux de ces valeurs à la main, et la diff résultante était un mur illisible de rouge et de vert où 238 des lignes étaient des clés qui avaient simplement bougé Mon critique, naturellement, m'a demandé de le refaire Les vrais changements étaient invisibles à l'intérieur du bruit.
Je dirige [Toolz.dev] (/et construis aussi des projets Laravel et WordPress, ce qui signifie que je vis à l'intérieur package.json, composer.json, tsconfig.json[TRADUCTION], catalogues de traduction, et cent autres fichiers JSON qui sont engagés dans le contrôle de version Un fichier JSON avec un ordre de clé imprévisible est une petite taxe récurrente sur chacun d'entre eux Le tri des clés dans un ordre alphabétique stable est la solution, et c'est l'un de ces changements qui semble cosmétique jusqu'à la première fois qu'il vous épargne un avis de code gaspillé Ce guide couvre quand trier les clés JSON, quand ne pas le faire, et comment le faire sans rien casser.
tl;dr : Un trieur JSON réordonne les clés d'un objet' ; s dans l'ordre alphabétique et re-sérialise le résultat L'ordre des clés ne change pas ce que JSON signifie, car les objets ne sont pas ordonnés par la norme JSON, mais un ordre cohérent rend les fichiers lisibles et produit des diff de contrôle de version épurées qui affichent uniquement les valeurs modifiées. Trier de manière récursive pour atteindre les objets imbriqués, conserver l'ordre des tableaux par défaut car les tableaux sont ordonnés et choisir une sortie ascendante ou descendante, jolie ou minifiée. Le Trieur JSON fonctionne entièrement dans votre navigateur.
Qu'est-ce qu'un trieur JSON ?
Un trieur JSON prend un objet JSON et réorganise ses touches par ordre alphabétique, puis réécrit l'objet Les valeurs sont intactes Seule la séquence dans laquelle les touches apparaissent change, et c'est sûr car RFC 8259 définit un objet comme une collection non ordonnée : la réorganisation des clés ne peut pas modifier ce que signifie le document. Donc {"name":"toolz","author":"Liton"} se transforme {"author":"Liton","name":"toolz"}. Par défaut, le tri est récursif, ce qui signifie que les clés à l'intérieur de chaque objet imbriqué sont également triées, jusqu'au niveau le plus profond.
C'est toute l'opération, et sa simplicité est le point Vous ne transformez pas des données, ne validez pas un schéma, ou ne convertissez pas un format Vous imposez un ordre prévisible sur quelque chose qui avait un arbitraire Tous les autres avantages, lisibilité, comparabilité, différences propres, découle de cet ordre prévisible unique.
Le tri des clés change-t-il ce que signifie mon JSON ?
Non, et c'est le fait qui rend le tri sûr Dans la norme JSON, ECMA-404, un objet est défini comme une collection non ordonnée de paires de noms et de valeurs La spécification est explicite que l'ordre de ces paires n'est pas significatif Tout analyseur conforme lit {"a":1,"b":2} et {"b":2,"a":1} comme exactement les mêmes données Quand votre programme fait config.timeout ou data["name"]« , il recherche la clé par son nom ; peu importe où dans l'objet cette clé a été écrite. ».
Il y a une mise en garde qui mérite d'être énoncée clairement, parce que quelqu'un demande toujours Un nombre infime de systèmes abusent des objets JSON comme s'ils avaient été commandés, en se fiant à l'ordre d'insertion pour l'affichage ou le traitement C'est une mauvaise utilisation du format plutôt qu'une propriété de celui-ci, mais si vous alimentez un système que vous ne contrôlez pas, testez avant de commettre un fichier trié dans un pipeline vous ne pouvez pas inspecter Pour l'écrasante majorité des JSON du monde réel, config des fichiers, des charges utiles d'API, des fichiers de verrouillage, des catalogues de traduction, le tri des clés est un changement purement présentationnel avec un effet zéro sur le sens.
Les tableaux sont le cas inverse, et la distinction importe Un tableau JSON est ordonné par définition, et son ordre porte fréquemment un sens : une séquence d'étapes, une liste classée, un ensemble de coordonnées où la position un est la longitude et la position deux est la latitude La réorganisation d'un tableau peut changer silencieusement ce que disent les données C'est pourquoi cet outil préserve l'ordre des tableaux par défaut et ne trie les tableaux que lorsque vous le lui demandez explicitement, et même alors seulement pour les tableaux dont les éléments sont toutes des chaînes ou tous les nombres.
Pourquoi trier les clés JSON ?
La raison principale est les différences nettes, et c'est celle qui a changé ma façon de travailler Les outils de contrôle de version comparent les fichiers ligne par ligne Lorsque deux fichiers qui représentent les mêmes données écrivent leurs clés dans des ordres différents, le diff est plein de clés qui ont bougé plutôt que de valeurs qui ont changé Adoptez une règle selon laquelle chaque fichier JSON est écrit avec des clés triées, et le problème disparaît : deux versions du fichier diffèrent uniquement là où une valeur diffère réellement, donc un critique voit le changement réel immédiatement C'est exactement pourquoi de nombreux linters et formateurs offrent une option de type sortes, et pourquoi des outils comme jq expédiez un drapeau de touches de tri.
La deuxième raison est la lisibilité humaine Lorsque vous scannez un fichier de configuration volumineux à la recherche d'un paramètre spécifique, l'ordre alphabétique vous indique où chercher Vous ne lisez pas l'intégralité du fichier ; vous sautez à peu près à l'endroit où la clé devrait être, comme vous le feriez dans un dictionnaire Sur un fichier à quatre-vingts touches, c'est la différence entre une recherche de deux secondes et une analyse complète.
La troisième raison est la comparabilité entre les fichiers Si votre projet a dix fichiers JSON qui devraient tous partager une structure commune, les trier de la même manière rend trivial de regarder s'il manque une clé ou si une autre. Les divergences s'alignent les unes à côté des autres au lieu de se cacher dans des positions différentes.
La quatrième raison est la canonisation Certains workflows ont besoin d'une représentation stable et déterministe d'une valeur JSON, par exemple pour la hacher, la mettre en cache ou comparer deux charges utiles pour l'égalité quelle que soit la façon dont elles ont été sérialisées Le tri des clés est un pas vers une forme canonique, bien qu'un JSON canonique complet normalise également le formatage des espaces et des nombres.
Comment utiliser le JSON Sorter ?
Collez votre JSON dans la zone de saisie sur le Trieur JSON(en anglais), ou chargez l'échantillon pour voir la forme de la sortie L'entrée doit être valide JSON Si ce n'est pas le cas, l'outil signale l'erreur d'analyse avec sa position afin que vous puissiez fixer une virgule parasite ou un support non fermé avant le tri.
Choisissez ensuite comment s'exécute le tri Choisissez ascendant, qui est de A à Z, ou descendant pour Z à A. Décidez s'il faut plier le cas, qui est activé par défaut pour que Name, name, et NAME asseyez-vous ensemble plutôt que d'être séparés parce que les lettres majuscules trient avant les minuscules dans l'ordre brut des caractères Choisissez s'il faut descendre dans des objets imbriqués, ce que vous voulez presque toujours, ou pour trier uniquement le niveau supérieur Si vous voulez des tableaux de chaînes ou de chiffres ordonnés également, activez le tri des tableaux ; les tableaux mixtes et les tableaux d'objets sont toujours laissés tels quels.
Enfin, choisissez votre style de sortie Jolie impression avec une indentation à deux espaces, quatre espaces ou tabulation pour un fichier lisible que vous allez valider, ou minifiez sur une seule ligne pour la plus petite charge utile pour le stockage ou le transport Exécutez le tri, puis copiez le résultat ou téléchargez-le Le nombre de touches vous indique combien de touches ont été réorganisées, ce qui est une vérification rapide de la santé mentale que l'outil a vu la structure à laquelle vous vous attendiez.
Ascendant, descendant, récursif : quels paramètres est-ce que je veux ?
La plupart du temps les valeurs par défaut sont ce que vous voulez : ascendantes, récursives, insensibles à la casse, jolies imprimées avec deux espaces Cela produit le fichier lisible et adapté aux différences qui motive le tri en premier lieu Les autres paramètres existent pour des situations spécifiques, et le tableau ci-dessous est la façon dont je décide.
| Réglage | Défaut | Quand le changer |
|---|---|---|
| Ordre | Ascendant (A à Z) | Descendre est rare ; utile lorsque vous souhaitez les clés les plus récentes ou les plus prioritaires, nommées pour trier en dernier, en haut |
| Recursif | Sur | Éteignez uniquement lorsque vous souhaitez réorganiser les sections de niveau supérieur, mais conservez l'ordre réglé à la main à l'intérieur de chacune d'elles |
| Ignorer l'affaire | Sur | Éteignez-vous lorsque vous avez besoin d'un ordre strict des points de code, par exemple pour faire correspondre un autre outil qui trie la casse de manière sensible |
| Triez les tableaux | Off | Activez-vous pour les tableaux qui sont des ensembles véritablement non ordonnés, comme une liste de balises ou des valeurs autorisées |
| Jolie impression | Sur | Éteignez pour minifier pour le transport ou le stockage |
Le seul paramètre que les gens utilisent à mauvais escient est le tri de tableaux Allumez-le uniquement lorsque vous êtes certain qu'un tableau représente un ensemble non ordonné Une liste de balises, un ensemble d'extensions de fichiers autorisées ou un sac d'indicateurs de fonctionnalités est sûr à trier Une liste d'étapes de pipeline, une table d'itinéraire, ou tout ce où la position implique une séquence ne l'est pas Quand dans le doute, laissez les tableaux seuls, parce que l'outil' ; la valeur par défaut de préserver l'ordre ne peut jamais corrompre vos données, tout en triant le mauvais tableau silencieusement peut.
Comment cela s'adapte-t-il aux autres outils JSON ?
Le tri est généralement une étape dans une petite chaîne Lorsque JSON arrive minifié et illisible à partir d'une API, je l'exécute via le Formateur JSON d'abord pour l'indenter et le valider, puis trier les clés pour le rendre scannable Lorsque je prépare une charge utile pour le transport après tri, le Minificateur JSON le réduit à une seule ligne, et comme les clés sont déjà triées, deux charges utiles minifiées qui représentent les mêmes données sortent identiques octet par octet, ce qui est pratique pour la mise en cache et la comparaison.
Pour les travaux de structure plutôt que de présentation, le Aplatisseur JSON transforme les objets imbriqués en touches pointillées et retour, ce qui se marie naturellement avec le tri lorsque vous vous disputez la configuration en variables d'environnement Et lorsque vous avez besoin des données dans un autre format entièrement, le Convertisseur JSON en YAML est le prochain arrêt ; le tri des clés avant la conversion vous donne un fichier YAML avec un ordre de champ prévisible et lisible également Si vous voulez une vue d'ensemble de la façon dont celles-ci s'emboîtent, j'ai présenté ma configuration complète dans le Guide d'outils pour les développeurs Web« Et les mécanismes plus profonds du formatage vivent dans le » Guide de formatage JSON.
Un exemple réel : apprivoiser un paquet.json diff
Permettez-moi de parcourir la situation exacte qui a déclenché cet article, car il montre pourquoi les choix de réglage comptent J'avais un package.json où le dependencies le bloc avait été écrit dans l'ordre d'installation, à peu près l'ordre dans lequel les packages avaient été ajoutés sur deux ans. Un nouveau membre de l'équipe a exécuté son format d'enregistrement editor' ; qui triait les clés de dépendance et les engageait parallèlement à un véritable changement : regrouper un package de la version 4 à la version 5.
Le diff était un désastre Chaque dépendance en dessous de celle cognée semblait avoir bougé, parce que le tri avait changé leurs positions, donc le critique a vu trente lignes changées pour ce qui était une mise à niveau d'une ligne Le correctif n'était pas de discuter de qui l'éditeur avait raison Le correctif était de trier le fichier une fois, de valider ce tri comme son propre changement séparé avec un message comme " ; trier les clés.json," ; et ensuite faire le bump de version au-dessus de l'ordre maintenant stable Après cela, chaque changement de dépendance futur a produit une différence nette d'une ligne ou deux lignes, parce que le fichier était déjà dans l'ordre tout le monde et #39 ; les outils voulaient le mettre.
C'est le modèle que je suis maintenant pour tout JSON qui vit dans le contrôle de version Trier-le une fois dans un commit dédié, puis le garder trié Le Trieur JSON avec ses valeurs par défaut, ascendantes et récursives, produit exactement l'ordre dans lequel Prettier' ; son option de tri et jq --sort-keys produisez, donc le fichier reste stable, quel que soit l'outil qu'un coéquipier exécute. La seule chose que je vérifie en premier concerne les tableaux : package.json n'a pas de tableaux significatifs à craindre, mais un fichier avec un tableau ordonné comme une liste d'étapes de construction nécessite un tri du tableau interrompu, ce qui est la valeur par défaut, donc la séquence survit.
Quels outils et formats trient les clés JSON ?
Le tri des clés JSON est un besoin suffisamment courant pour qu'il apparaisse dans tout l'écosystème, ce qui est un bon signe que la pratique est saine plutôt qu'une bizarrerie personnelle. Le processeur de ligne de commande jq a un --sort-keys drapeau, souvent écrit -S[TRADUCTION], cela trie les clés de chaque objet de sa sortie Le formateur de code Prettier peut trier les clés dans JSON par sa configuration De nombreux linters offrent une règle de type tri (trid-keys) qui signale les objets non triés dans le code source Les bibliothèques standard de langage exposent la même capacité, par exemple Python' ; s json.dumps accepte un sort_keys=True argument qui produit une sortie canonique et triée.
Ce qu'un trieur basé sur un navigateur ajoute, c'est le cas rapide et sans configuration Lorsque vous avez un blob de JSON à partir d'une réponse API, d'une ligne de journal ou d'un message Slack, et que vous voulez juste le lire dans un ordre sain dès maintenant, ouvrir une page et coller est plus rapide que de câbler un formateur ou de tomber dans un shell C'est la même raison pour laquelle un formateur coller-aller existe aux côtés des plugins de l'éditeur : l'outil répond au besoin ad hoc que le pipeline configuré ne couvre pas.
Mon JSON est-il privé ?
Oui. Le JSON est analysé, trié et re-sérialisé entièrement dans votre navigateur à l'aide de JavaScript Rien n'est téléchargé sur un serveur, enregistré ou stocké n'importe où Ce n'est pas un détail mineur pour JSON en particulier, car JSON est l'endroit où vivent les secrets : réponses API transportant des jetons, fichiers de configuration avec chaînes de connexion, charges utiles contenant des enregistrements client. Le collage de tout cela dans un outil qui l'expédie sur un serveur est un risque réel, et c'est exactement le risque que cet outil est conçu pour éviter.
Vous pouvez vérifier la réclamation de la même manière que je le ferais. Ouvrez l'onglet réseau dans votre navigateur' ; les outils de développement et regardez-le pendant que vous triez ; aucune requête ne quitte la page Ou déconnectez-vous d'Internet et continuez à trier, car une fois la page chargée, l'outil fonctionne sans aucune connexion. Le traitement côté client est la valeur par défaut pour tout ce que je crée, et si vous vous souciez de l'argument plus large en faveur de celui-ci, le Guide de confidentialité des données fait le cas dans son intégralité.
Questions fréquentes
Qu'est-ce que cela signifie pour trier les clés JSON ?
Le tri des touches JSON réordonne les paires nom-valeur d'un objet dans l'ordre alphabétique sans changer aucune valeur L'objet {" ; name" ; :" ;toolz" ;," ;author" ; :" ; Liton" ;} devient {" ;author" ; :" ;Liton" ;," ;toolz" ;}. Seul l'ordre des touches change, de sorte que les données que représente le document restent exactement les mêmes.
Le tri des clés change-t-il ce que signifie mon JSON ?
non . Dans le standard JSON, ECMA-404, un objet est un ensemble non ordonné de paires nom-valeur, donc réorganiser ses clés ne change pas de sens. Tout analyseur conforme lit les versions triées et non triées comme les mêmes données. L'ordre n'est important que pour la lisibilité humaine et pour la production de diffstables.
Les objets imbriqués sont-ils également triés ?
Oui, par défaut. Le tri récursif est activé, de sorte que les clés de chaque objet à l'intérieur du document sont triées, à chaque niveau d'imbrication. Vous pouvez désactiver la récursivité pour trier uniquement les clés de niveau supérieur et laisser des objets imbriqués dans leur ordre d'origine.
La trieuse réorganise-t-elle les tableaux ?
pas par défaut. Les tableaux sont classés par définition et leur réorganisation peut changer de sens, de sorte que l'outil conserve l'ordre des tableaux. Il existe une option pour trier les tableaux dont les éléments sont toutes des chaînes ou tous les nombres lorsque vous le souhaitez, les tableaux qui mélangent les types ou qui contiennent des objets sont toujours laissés tels quels.
Pourquoi trier les clés JSON ?
La raison la plus courante est la stabilité des différences : lorsque chaque fichier écrit ses clés dans le même ordre alphabétique, les différences de contrôle de version ne mettent en évidence que les valeurs qui ont changé plutôt que les clés qui se sont déplacées. Le tri rend également les fichiers de configuration volumineux et les réponses des API beaucoup plus faciles à analyser et à comparer à l'œil.
Comment fonctionne le tri insensible aux casses de la casse ?
Avec le tri non sensible à la casse, les clés sont comparées comme si elles étaient minuscules, donc le nom, le nom et le nom sont regroupés les unes à côté des autres au lieu d'être séparés car les lettres majuscules sont triées avant les minuscules dans l'ordre des caractères bruts. Désactivez-le pour trier strictement par point de code de caractère.
Puis-je minimiser le JSON trié ?
Oui. Choisissez la sortie minifiée pour obtenir le JSON trié sur une seule ligne sans espace blanc supplémentaire, qui est la plus petite forme de stockage ou de transport. Pour un fichier lisible, choisissez plutôt la sortie Pretty avec deux espaces, quatre espaces ou des onglets.
Mon JSON est-il téléchargé quelque part ?
non . Le JSON est analysé et trié par JavaScript dans votre navigateur et n'est jamais transmis, enregistré ou enregistré. Vous pouvez vérifier cela en regardant l'onglet Réseau lors du tri ou en déconnectant, l'outil continue de fonctionner sans connexion.
Écrit par Liton, constructeur de [Toolz.dev](/. Je crée des outils de développement basés sur un navigateur et j'écris sur le travail avec JSON, Laravel et le Web.
