Ghid pentru Formatator JSON
Cum validează Formatatorul JSON de la XGM cu parserul strict al browserului, ce înseamnă mesajele de eroare uzuale și cum reparați virgulele finale.
Cum arată un JSON valid
JSON (JavaScript Object Notation, RFC 8259) este un format text pentru date structurate, construit din obiecte, tablouri, șiruri, numere, valori booleene și null. Seamănă cu JavaScript, dar este mult mai strict. Multe lucruri pe care JavaScript le acceptă, precum cheile fără ghilimele sau virgulele finale, nu sunt JSON valid, iar un parser strict le respinge. Rigoarea este intenționată: cu cât formatul este mai îngust, cu atât limbaje și medii de execuție diferite citesc același document la fel. Este și cea mai ieftină cale de a verifica un fișier de configurare scris de mână înainte de a-l da unei aplicații.
| Tip | Exemplu | Reguli |
|---|---|---|
| Obiect | {"name": "XGM"} | Cheile trebuie să fie șiruri între ghilimele duble |
| Tablou | [1, 2, 3] | Separate prin virgulă, fără virgulă finală |
| Șir | "hello\n" | Doar ghilimele duble; caracterele de control trebuie escapate |
| Număr | 42, -1.5, 2e10 | Fără zerouri la început, fără NaN sau Infinity, fără hexazecimal |
| Boolean | true, false | Cu litere mici |
| Null | null | Cu litere mici |
Cum folosiți Formatatorul JSON
- Deschideți Formatator JSON și lipiți JSON-ul dumneavoastră, sau apăsați Încarcă exemplu.
- Alegeți indentarea (2 spații, 4 spații ori tab) și dacă vreți ca cheile să fie sortate.
- Apăsați Format (sau Ctrl+Enter) pentru o scriere lizibilă, ori Minifică pentru a elimina spațiile.
- Dacă datele nu sunt valide, citiți eroarea cu linia și coloana ei, reparați și încercați din nou.
- Copiați rezultatul sau exportați-l; nimic nu este încărcat.
Sortarea cheilor este utilă când comparați două documente JSON: odată ce amândouă sunt formatate cu cheile sortate, o comparație de text arată diferențele reale, nu câmpurile mutate de la un loc la altul. Tablourile nu sunt atinse, fiindcă ordinea lor face parte din date. Aceeași metodă ajută și în controlul versiunilor: diferențele de commit ale unui fișier de configurare formatat și sortat rămân scurte și lizibile. Rezultatul este întotdeauna UTF-8 și păstrează secvențele escapate așa cum sunt, deci datele dumneavoastră nu se schimbă în timpul formatării.
Erori frecvente și remedierea lor
| Greșeală | Invalid | Valid |
|---|---|---|
| Virgulă finală | {"a": 1,} | {"a": 1} |
| Ghilimele simple | {'a': 'b'} | {"a": "b"} |
| Cheie fără ghilimele | {a: 1} | {"a": 1} |
| Comentariu | {"a": 1 // note} | Ștergeți comentariile |
| NaN sau Infinity | {"x": NaN} | {"x": null} sau un șir |
| Linie nouă neescapată într-un șir | "line 1 + linie nouă + line 2" | "line 1\nline 2" |
| Virgulă lipsă | {"a": 1 "b": 2} | {"a": 1, "b": 2} |
| Zero la început | {"n": 007} | {"n": 7} |
Linia și coloana din eroare arată unde a observat parserul problema, ceea ce se întâmplă adesea imediat după greșeala reală. O virgulă lipsă este raportată la începutul valorii următoare, iar un șir neînchis poate fi raportat cu multe linii mai jos. Uitați-vă la poziția indicată și la cele câteva caractere dinaintea ei. Într-un document lung, cel mai rapid este să mergeți la linia raportată și să citiți și linia de deasupra ei. Ajută și să formatați datele mai întâi, pentru că într-un JSON strâns pe o singură linie numărul coloanei nu vă spune mare lucru.
Fișiere de configurare cu comentarii
Numere, precizie și valori mari
JSON în sine nu limitează mărimea numerelor, însă JavaScript reprezintă numerele ca valori în virgulă mobilă pe 64 de biți. Numerele întregi mai mari decât 2^53 − 1 (9007199254740991) pierd din precizie când sunt analizate într-un browser. Un identificator de 19 cifre poate ieși din formatare cu ultimele cifre schimbate. Pierderea este tăcută: nici parserul, nici formatatorul nu vă avertizează, pentru că rezultatul arată impecabil din punctul de vedere al sintaxei.
Input: {"id": 12345678901234567891}
Parsed: {"id": 12345678901234567000}API-urile care folosesc identificatori mari, precum unele rețele sociale și baze de date, le trimit adesea ca șiruri exact din acest motiv. Dacă depanați astfel de date, păstrați o copie a textului brut și fiți prudent cu rezultatul formatat al numerelor întregi mari. Același lucru este valabil pentru valorile zecimale foarte precise, pe care virgula mobilă nu le poate reprezenta exact. De aceea sumele de bani sunt transportate de obicei ca numere întregi în cea mai mică unitate ori ca șiruri.
Confidențialitatea când lucrați cu JSON
JSON conține adesea răspunsuri de API cu date personale, token-uri sau identificatori interni. Formatatorul XGM prelucrează totul în browserul dumneavoastră, iar datele introduse nu sunt stocate, trimise la server sau adăugate în adresa paginii. Instrumentele care rulează doar în browser nu ajung niciodată nici în istoricul local al verificărilor recente. La reîncărcarea paginii câmpul se golește, deci datele dispar în clipa în care închideți fila.
Cu toate acestea, evitați să lipiți secrete active, precum chei de API sau token-uri de sesiune, în orice pagină web atunci când puteți folosi un instrument local. Înlocuiți valorile sensibile cu substituenți înainte de a partaja JSON formatat în tichete sau în conversații. Aceeași regulă se aplică și capturilor de ecran; după ce a apărut o dată într-o înregistrare, un token nu mai poate fi considerat secret.
# Python
python3 -m json.tool --indent 2 data.json
# jq
jq . data.json
jq -S . data.json # sorted keys
jq -c . data.json # minifiedFormate și instrumente înrudite
JSON are deseori nevoie să fie convertit sau privit sub altă formă. Modul CSV în JSON transformă exporturile din foi de calcul în tablouri JSON, Decodorul JWT citește JSON-ul din interiorul token-urilor, iar Formatatorul de cod se ocupă de celălalt format de date obișnuit. Pentru depanarea unui API, Verificare antete HTTP arată ce Content-Type trimite un server. Parserul CSV respectă RFC 4180, deci câmpurile între ghilimele pot conține virgule, ghilimele și linii noi.
O cale rapidă de a inspecta un răspuns de API este să îl aduceți cu curl și să lipiți corpul în formatator. De exemplu, curl -s https://api.example.com/v1/orders/42 returnează o singură linie de JSON minificat; formatat, imbricarea și numele câmpurilor devin ușor de citit. Ștergeți token-urile și datele personale din rezultat înainte de a-l partaja. Puteți salva răspunsul într-un fișier și să îl parcurgeți cu jq, care face aceeași treabă în linia de comandă.
Când un API returnează o pagină HTML de eroare în loc de JSON, formatatorul raportează o eroare la linia 1, coloana 1, pentru că < nu este JSON valid. De obicei asta înseamnă că cererea a ajuns la un proxy, la o pagină de autentificare sau la o eroare de server, nu la API. Același simptom apare și când interogați fără token un punct final care cere autentificare.
Un răspuns JSON valid ar trebui servit ca application/json. Serverele care trimit JSON ca text/html pot declanșa ghicirea tipului de conținut în browser și îi obligă pe clienți să presupună, iar acesta este unul dintre motivele pentru care există antetul X-Content-Type-Options: nosniff. Nu este nevoie să adăugați un set de caractere, pentru că RFC 8259 cere ca JSON-ul trimis prin rețea să fie codificat în UTF-8.
Întrebări frecvente
JSON-ul meu este încărcat undeva?
Nu. Analiza și formatarea au loc în browserul dumneavoastră, iar datele introduse nu sunt stocate și nu ajung în adresa paginii. După prima încărcare, pagina funcționează și offline.
De ce obiectul meu JavaScript nu este JSON valid?
JSON cere chei și șiruri între ghilimele duble și interzice virgulele finale, comentariile, undefined, funcțiile și numerele speciale precum NaN.
Formatatorul îmi modifică datele?
Formatarea schimbă doar spațiile albe. Sortarea cheilor schimbă ordinea cheilor din obiecte. Numerele întregi foarte mari pot pierde din precizie, pentru că browserele analizează numerele în virgulă mobilă.
Poate lucra cu fișiere mari?
Se descurcă bine cu răspunsurile de API și cu fișierele de configurare obișnuite. Documentele foarte mari, de zeci de megaocteți, pot încetini pagina, pentru că totul se întâmplă în fila browserului. Pentru ele este mai potrivit jq în linia de comandă.
Ce înseamnă poziția erorii?
Linia și coloana unde parserul a găsit problema. Greșeala propriu-zisă este adesea chiar înaintea acelei poziții, de pildă o virgulă lipsă sau un ghilimel neînchis.
JSON permite chei duplicate?
RFC 8259 spune că numele ar trebui să fie unice, iar parserele tratează duplicatele diferit. Parserul browserului păstrează ultima valoare, așa că duplicatele dispar tăcut din rezultatul formatat.
Să folosesc 2 sau 4 spații?
Este o chestiune de stil. Două spații sunt uzuale în proiectele web, patru în convențiile unor limbaje. Pentru transport, cel mai bun este JSON-ul minificat.
Care este diferența dintre formatare și minificare?
Formatarea adaugă indentare și linii noi pentru citire. Minificarea elimină toate spațiile inutile, pentru dimensiunea cea mai mică.
De ce nu se analizează un JSON care pare valid?
Caracterele invizibile sunt o cauză frecventă: spațiile neseparatoare și ghilimelele tipografice copiate din documente sau din aplicații de chat arată ca spațiile și ghilimelele obișnuite, dar nu sunt. Rescrieți manual ghilimelele din jurul poziției raportate.
Este valid un JSON cu marcaj de ordine a octeților?
RFC 8259 spune că implementările nu trebuie să adauge un marcaj de ordine a octeților la JSON-ul trimis prin rețea, iar parserele îl pot ignora. Ștergeți-l dacă un parser strict se plânge de primul caracter.