Επικύρωση της σύνταξης ενός JSON

Σε τι χρησιμοποιείται ο επικυρωτής JSON;

Ένας επικυρωτής JSON έχει έναν πιο μέτριο, αλλά πιο ακριβή, ρόλο από έναν μορφοποιητή: δεν ξαναγράφει τίποτα. Παίρνει μια συμβολοσειρά και απαντά σε μια δυαδική ερώτηση: είναι αυτό το κείμενο σύμφωνο με το JSON; RFC 8259; Εάν ναι, το εργαλείο επιστρέφει τον έλεγχο. Εάν όχι, υποδεικνύει ακριβώς τη γραμμή, τη στήλη και ένα απόσπασμα του JSON γύρω από το πρόβλημα, για να βοηθήσετε τον προγραμματιστή να το διορθώσει αμέσως.

Στην πράξη, είναι το εργαλείο που χρησιμοποιούμε μόλις ένας αναλυτής κάπου επιστρέψει ένα μήνυμα σφάλματος κρυπτική όπως Σφάλμα σύνταξης: Μη αναμενόμενο διακριτικό } σε JSON στη θέση 217. Αντί για μετρήστε με το χέρι τους χαρακτήρες σε ένα πρόγραμμα επεξεργασίας, επικολλήστε την πλήρη συμβολοσειρά, διαβάστε τη θέση και δείτε το προσβλητικό απόσπασμα.

Επικύρωση, μορφοποίηση: δύο διακριτές λειτουργίες

Συχνά μπερδεύουμε και τα δύο. Ο μορφοποιητής JSON χρησιμοποιεί έγκυρο JSON και το ξαναγράφει με ευανάγνωστη εσοχή. Ο επικυρωτής είναι ικανοποιημένος με μια συντακτική ετυμηγορία. Αυτός δεν εκτελεί σημασιολογική επικύρωση: δεν γνωρίζει εάν η τιμή ενός πεδίου email μοιάζει με email, ούτε εάν η δομή ταιριάζει με ένα σχήμα JSON. Για αυτό, χρησιμοποιούμε ειδικά εργαλεία (ajv στο Node, justinrainbow/json-schema στην PHP).

Η κλασική ακολουθία στον εντοπισμό σφαλμάτων είναι: επικύρωση πρώτα (το εργαλείο υποδεικνύει το συντακτικό σφάλμα), μορφοποιήστε τότε (το πλέον έγκυρο ωφέλιμο φορτίο γίνεται αναγνώσιμο), συγκρίνετε τέλος με ένα άλλο ωφέλιμο φορτίο αναφοράς μέσω του Συγκριτή JSON.

Τα πιο συνηθισμένα σφάλματα JSON

• Κόμμα στο τέλος: {"a": 1, "b": 2,}. Ανεκτό από JavaScript, ECMAScript και JSON5. απορρίφθηκε από καθαρό JSON. Αυτό είναι το #1 λάθος κατά την αντιγραφή και επικόλληση από ένα πρόγραμμα επεξεργασίας κώδικα.
• Απόστροφα αντί για διπλά εισαγωγικά: Το {'a': 1} δεν είναι έγκυρο. JSON δέχεται μόνο διπλά εισαγωγικά, γύρω από κλειδιά και τιμές συμβολοσειρών.
• Μη εισαγωγικά κλειδιά: {a: 1}, έγκυρη σύνταξη JavaScript αλλά μη έγκυρο JSON.
• Χαρακτήρες ελέγχου χωρίς διαφυγή σε μια συμβολοσειρά: ακατέργαστη νέα γραμμή, α πίνακα. Το JSON απαιτεί , , .
• Σχόλια: // σχόλιο ή /* */. Αποδεκτό σε JSONC (config VS Code) ή JSON5, απορρίφθηκε σε καθαρό JSON.
• Λανθασμένη κωδικοποίηση: ένα UTF-8 BOM στην αρχή του αρχείου, εσφαλμένο περιεχόμενο Latin-1 μετατράπηκε. Το πρόγραμμα επικύρωσης συχνά επιστρέφει ένα γενικό μήνυμα για αυτές τις περιπτώσεις.
• Ημιτελής δομή: ένα { ή [ χωρίς κλείσιμο, κοινό όταν περικόπτετε ένα ωφέλιμο φορτίο κατά την αντιγραφή και επικόλληση.

Πώς ο επικυρωτής εντοπίζει το σφάλμα

Το εργαλείο χρησιμοποιεί τη σημαία json_decode() της PHP με τη σημαία JSON_THROW_ON_ERROR. PHP επιστρέφει ένα μήνυμα που περιέχει μια θέση σε byte (θέση 217), την οποία μετατρέπουμε σε Ζεύγος γραμμής/στήλης μετρώντας τις αλλαγές γραμμής πριν από τη μετατόπιση. Ένα απόσπασμα περίπου 80 χαρακτήρων είναι στη συνέχεια κόψτε τη θέση για να δώσετε το πλαίσιο. Αυτό είναι γενικά αρκετό για την αναγνώριση το σφάλμα: ένα παράθεμα που δεν έχει τοποθετηθεί, ένα επιπλέον κόμμα, μια παρένθεση που λείπει.

Προειδοποίηση: η θέση που αναφέρεται από την PHP δεν είναι πάντα ακριβώς ο προσβλητικός χαρακτήρας. Αυτή είναι συχνά μετά το σφάλμα, όταν ο αναλυτής έχει εγκαταλείψει. Εάν το απόσπασμα εμφανίζει "name": "Alice", }, το πραγματικό σφάλμα είναι το κόμμα, όχι το άγκιστρο.

Τυπικές περιπτώσεις χρήσης

• Εφθαρμένη διαμόρφωση: composer.json, package.json, tsconfig.json που εμποδίζουν την εκκίνηση μιας κατασκευής. Επικολλάμε, βλέπουμε τη γραμμή, διορθώνουμε.
• Περικομμένη απόκριση API: Ένας διακομιστής μεσολάβησης έκοψε το ωφέλιμο φορτίο. Η δομή δεν έχει ολοκληρωθεί, ο επικυρωτής αναφέρει αυτό.
• Webhook Payload: Μια υπηρεσία τρίτου μέρους στέλνει JSON με κακή μορφή. Ο επικυρωτής επιτρέπει για να παρατηρήσετε το πρόβλημα στην πλευρά του αποστολέα χωρίς να βουτήξετε στον κωδικό της εφαρμογής.
• JSON που κατασκευάστηκε με συνένωση: πρακτική στην αποφυγή αλλά συνηθισμένη, ειδικά στο bash ή σε SQL. Το εργαλείο επικύρωσης αποκαλύπτει διπλά εισαγωγικά χωρίς διαφυγή.

Περιορισμοί εργαλείων

Το πρόγραμμα επικύρωσης δεν επικυρώνει ένα σχήμα. Δεν λέει ότι του λείπει το γήπεδο email, ότι η τιμή δεν είναι ακέραιος ή ότι ο αναμενόμενος πίνακας δεν έχει το σωστό μήκος. Για αυτούς τους δομικούς ελέγχους, χρησιμοποιούμε το σχήμα JSON. Ο επικυρωτής επίσης δεν διορθώνει το JSON: δεν επιχειρεί να προσθέσει ένα άγκιστρο που λείπει ή να αφαιρέσει ένα επιπλέον κόμμα. Είναι επιλογή : η αυτόματη διόρθωση πολύ συχνά κρύβει πραγματικά σφάλματα.

Συχνές ερωτήσεις

Παράδειγμα αιτήματος

curl -X POST https://cdrn.fr/api/v1/tools/json-validator/execute \
  -H "Content-Type: application/json" \
  -d '{"input":"..."}'

Σχήμα εισόδου

Σημεία πρόσβασης

• GET https://cdrn.fr/api/v1/tools - εμφανίζει όλα τα διαθέσιμα εργαλεία
• GET https://cdrn.fr/api/v1/tools/json-validator - ανακτά το σχήμα αυτού του εργαλείου
• POST https://cdrn.fr/api/v1/tools/json-validator/execute - εκτελεί αυτό το εργαλείο με payload JSON