Best practice di formattazione JSON: leggibile, valido ed efficiente
Risposta rapida
Utilizza il rientro di 2 spazi per JSON leggibile dall'uomo, nessuna virgola finale, chiavi tra virgolette doppie e un ordinamento delle chiavi coerente (alfabetico o significativo per il dominio). Minimizza JSON per il trasporto di produzione e Pretty-Print per lo sviluppo. Utilizza il nostro formattatore JSON gratuito per passare istantaneamente da uno all'altro.
Introduzione
Le scelte di formattazione di JSON influiscono sulla leggibilità, sulla dimensione del file e sulla velocità di debug. Sebbene la sintassi JSON sia definita rigorosamente dalla RFC 8259, il modo in cui si rientra, si ordinano le chiavi e si gestiscono gli spazi bianchi è una questione di convenzione. Questa guida spiega le best practice ampiamente adottate in modo che il tuo JSON sia coerente tra i team, facile da eseguire il debug ed efficiente in rete.
Passo dopo passo
-
Scegli una larghezza di rientro
2 spazi è la convenzione più comune (Prettier, ESLint, Google JSON Style Guide). 4 spazi sono accettabili per configurazioni profondamente annidate. Le schede sono sconsigliate perché il rendering varia a seconda degli editor. Scegline uno e applicalo a tutto il progetto.
-
Ordina le chiavi in modo coerente
Ordina le chiavi in ordine alfabetico per un output deterministico (utile per la memorizzazione nella cache e le differenze) o raggruppale per significato del dominio (prima id, quindi attributi, quindi relazioni). Evita l'ordine casuale delle chiavi: rende le differenze rumorose e interrompe i test degli snapshot.
-
Minimizza per il trasporto di produzione
Il JSON ridotto rimuove tutti gli spazi non essenziali, riducendo le dimensioni del carico utile del 10—0%. Servi JSON minimizzato da APIs in produzione e mantieni JSON piuttosto stampato solo per lo sviluppo locale e il debug.
-
Convalidare prima dell'invio
Esegui sempre JSON tramite un validatore prima di inviare a API o scrivere in un file di configurazione. Una singola virgola finale o una chiave senza virgolette farà sì che JSON.parse() lanci e interrompa il consumer.
-
Utilizzare un formattatore per cambiare modalità
Incolla il tuo JSON nel formattatore JSON per abbellirlo per la lettura o minimizzarlo per il trasporto. Lo strumento convalida la sintassi e segnala la posizione esatta di eventuali errori, risparmiando tempo di debug.
Esempi
Bella stampata (rientro di 2 spazi)
Ingresso: {"id":1,"name":"Alice","active":true}
Produzione: {
"id": 1,
"name": "Alice",
"active": true
}
Minimizzato per la produzione
Ingresso: {
"id": 1,
"name": "Alice"
}
Produzione: {"id":1,"name":"Alice"}
Tasti in ordine alfabetico
Ingresso: {"zebra":1,"apple":2,"mango":3}
Produzione: {"apple":2,"mango":3,"zebra":1}
Problemi comuni
- Virgole finali: {"a":1,} non è valida JSON. La maggior parte dei formattatori li elimina, ma parser rigorosi come JSON.parse() rifiuteranno l'input.
- Virgolette singole e chiavi senza virgolette: {'a':1} e {a:1} sono JavaScript validi ma non validi JSON. Utilizzare sempre virgolette doppie per chiavi e valori di stringa.
- Commenti in JSON: lo standard JSON non consente // o /* */ commenti. Utilizza JSONC, JSON5 o un file di schema separato se hai bisogno di documentazione in linea.
- Rientro misto: mescolare tabulazioni e spazi interrompe gli strumenti diff e può causare errori di lanugine di "rientro incoerente". Normalizza con un formattatore prima di eseguire il commit.
Suggerimenti
- Configura il tuo editor per formattare JSON al salvataggio con rientro di 2 spazi: ciò impedisce dibattiti sullo stile nella revisione del codice.
- Per le risposte API, imposta Content-Type: application/json; charset=utf-8 e servi JSON minimizzato con compressione gzip/Brotli per la massima efficienza.
- Utilizza l'ordinamento deterministico delle chiavi (ad esempio, alfabetico) quando JSON viene sottoposto ad hashing o confrontato nei test degli snapshot: l'ordine casuale causa errori falsi positivi.
- Quando si esegue il debug di un payload JSON di grandi dimensioni, stamparlo prima, quindi utilizzare regex o jq per estrarre il sottoalbero pertinente invece di scansionarlo a occhio.