Bonnes pratiques de formatage JSON : lisible, valide et efficace
Réponse rapide
Utilisez une indentation à 2 espaces pour JSON lisible par l'homme, sans virgules finales, des clés entre guillemets doubles et un ordre de clé cohérent (alphabétique ou significatif pour le domaine). Réduisez JSON pour le transport de production et joli-print pour le développement. Utilisez notre formateur gratuit JSON pour basculer instantanément entre les deux.
Introduction
Les choix de formatage JSON affectent la lisibilité, la taille du fichier et la vitesse de débogage. Bien que la syntaxe JSON soit strictement définie par la RFC 8259, la façon dont vous indentez, commandez les clés et gérez les espaces est une question de convention. Ce guide explique les meilleures pratiques largement adoptées afin que votre JSON soit cohérent entre les équipes, facile à déboguer et efficace sur le réseau.
Pas à pas
-
Choisissez une largeur d'indentation
2 espaces est la convention la plus courante (Prettier, ESLint, Google JSON Style Guide). 4 espaces sont acceptables pour les configurations profondément imbriquées. Les onglets sont déconseillés car le rendu varie selon les éditeurs. Choisissez-en un et appliquez-le à l’ensemble du projet.
-
Commandez les clés de manière cohérente
Soit trier les clés par ordre alphabétique pour une sortie déterministe (utile pour la mise en cache et les différences), soit les regrouper par signification de domaine (identifiant d'abord, puis attributs, puis relations). Évitez l’ordre aléatoire des clés : cela rend les différences bruyantes et interrompt les tests d’instantanés.
-
Minify pour le transport de production
Minified JSON supprime tous les espaces non essentiels, réduisant ainsi la taille de la charge utile de 10 à 0 %. Servez JSON minifié à partir de APIs en production et conservez JSON joliment imprimé pour le développement local et le débogage uniquement.
-
Validez avant d'envoyer
Exécutez toujours JSON via un validateur avant de l'envoyer vers un API ou d'écrire dans un fichier de configuration. Une seule virgule de fin ou une clé sans guillemets entraînera le lancement et la rupture du consommateur par JSON.parse().
-
Utilisez un formateur pour changer de mode
Collez votre JSON dans le formateur JSON pour l'embellir pour la lecture ou le réduire pour le transport. L'outil valide la syntaxe et signale l'emplacement exact de toute erreur, ce qui permet de gagner du temps de débogage.
Exemples
Joli imprimé (retrait de 2 espaces)
Saisir: {"id":1,"name":"Alice","active":true}
Sortir: {
"id": 1,
"name": "Alice",
"active": true
}
Minifié pour la production
Saisir: {
"id": 1,
"name": "Alice"
}
Sortir: {"id":1,"name":"Alice"}
Clés classées par ordre alphabétique
Saisir: {"zebra":1,"apple":2,"mango":3}
Sortir: {"apple":2,"mango":3,"zebra":1}
Problèmes courants
- Virgules de fin : {"a":1,} n'est pas valide JSON. La plupart des formateurs les suppriment, mais les analyseurs stricts comme JSON.parse() rejetteront l'entrée.
- Guillemets simples et clés sans guillemets : {'a':1} et {a:1} sont des JavaScript valides mais non valides JSON. Utilisez toujours des guillemets doubles pour les clés et les valeurs de chaîne.
- Commentaires dans JSON : la norme JSON n'autorise pas les commentaires // ou /* */. Utilisez JSONC, JSON5 ou un fichier de schéma distinct si vous avez besoin d'une documentation en ligne.
- Indentation mixte : le mélange de tabulations et d'espaces interrompt les outils de comparaison et peut provoquer des erreurs de charpie d'"indentation incohérente". Normalisez avec un formateur avant de vous engager.
Conseils
- Configurez votre éditeur pour formater JSON lors de l'enregistrement avec une indentation de 2 espaces - cela évite les débats de style lors de la révision du code.
- Pour les réponses API, définissez Content-Type : application/json ; charset=utf-8 et servez JSON minifié avec compression gzip/Brotli pour une efficacité maximale.
- Utilisez un ordre déterministe des clés (par exemple, alphabétique) lorsque JSON est haché ou comparé dans des tests d'instantanés : un ordre aléatoire provoque des échecs faussement positifs.
- Lors du débogage d'une grande charge utile JSON, imprimez-la d'abord, puis utilisez regex ou jq pour extraire le sous-arbre concerné au lieu de l'analyser visuellement.