La prima volta che ho scritto un'espressione JSONPath che contava, ho sbagliato tre volte prima che funzionasse, e sapevo solo che era sbagliato perché il gateway API che stavo configurando restituiva una policy vuota invece del campo che volevo Non c'era un ciclo di feedback Modificavo l'espressione, ridistribuivo e aspettavo Una volta iniziato a tenere aperto un tester JSONPath in un'altra scheda, quello stesso lavoro richiedeva due minuti invece di un pomeriggio Questa guida riguarda il modo in cui utilizzo il Tester JSONPath su Toolz.dev, ciò che la sintassi fa effettivamente, e le piccole trappole che fanno un'espressione non restituiscono nulla quando si era sicuri che dovesse corrispondere.
tl; dr: JSONPath è un linguaggio di query per JSON, come XPath lo è per XML Un tester JSONPath valuta un'espressione come
$.store.book[*].authorcontro un documento e restituisce ogni valore corrispondente più il suo percorso Il Tester JSONPath lo fa interamente nel tuo browser, con il supporto per caratteri jolly, discesa ricorsiva, sezioni, unioni ed espressioni di filtro, in modo da poter creare ed eseguire il debug di una query rispetto a dati reali prima di incollarla nel codice.
Che cos'è JSONPath?
JSONPath è una sintassi compatta per selezionare parti di un documento JSON Si scrive un breve percorso che descrive un percorso attraverso i dati, e valutandoli si restituisce il valore o i valori in quel percorso L'idea viene da Stefan Goessner's Proposta del 2007, che rispecchiava deliberatamente XPath in modo che chiunque avesse interrogato XML si sentisse a casa Per anni non c'era alcuna specifica formale, solo quell'articolo e una famiglia di implementazioni che per lo più concordavano, e all'inizio del 2024 l'IETF ha pubblicato RFC9535 per appuntare la grammatica.
Incontri JSONPath più spesso di quanto potresti aspettarti È la lingua di selezione negli strumenti di test API come Postman e Karate, in Kubernetes kubectl formattazione dell'output, in AWS CloudWatch e Step Functions, nei processori log e in decine di piattaforme low-code in cui un utente deve estrarre un campo da un payload webhook senza scrivere codice Imparando una volta che ripaga su tutte quelle.
Il modello mentale è semplice Un documento JSON è un albero Gli oggetti hanno rami nominati, gli array hanno rami numerati e le foglie sono i tuoi valori scalari Un'espressione JSONPath è un insieme di direzioni per camminare su quell'albero e il risultato è ogni foglia o sottoalbero su cui atterri Dove diventa potente è che una singola espressione può atterrare su molti luoghi contemporaneamente.
Cosa fa effettivamente un tester JSONPath?
Un tester prende due ingressi, il tuo JSON e un'espressione, e ti mostra ogni nodo selezionato dall'espressione Sembra ovvio, ma il valore è nel feedback Quando un'espressione non restituisce nulla, o restituisce più di quanto ti aspettavi, un tester trasforma un gioco di indovinare in un controllo di due secondi, perché puoi vedere esattamente quali nodi corrispondevano e regolare un carattere alla volta.
Su Toolz.dev il flusso è breve Incolla un documento JSON, o carica la libreria di esempio che la maggior parte dei tutorial JSONPath utilizza, digita un'espressione e valuta Lo strumento elenca ogni valore abbinato con un conteggio in esecuzione e puoi commutare l'output tra tre visualizzazioni I valori ti danno solo i risultati come un array JSON Paths ti dà la posizione normalizzata di ogni corrispondenza, che è il modo più rapido per scoprire l'espressione di cui hai effettivamente bisogno Le voci ti danno entrambe insieme, in modo da poter vedere il percorso e il valore fianco a fianco.
Il motivo per testare rispetto ai dati reali piuttosto che ragionare sulla tua testa è che JSON from the wild è più disordinato degli esempi Un campo a volte è un oggetto e a volte un array Una chiave che ti aspettavi manca sulla metà dei record Un numero è arrivato come stringa Eseguendo l'espressione contro le superfici del carico utile effettivo quelle sorprese immediatamente invece che al momento della distribuzione.
Come faccio a selezionare gli elementi da un array?
Gli array sono i luoghi in cui avviene la maggior parte del lavoro JSONPath e ci sono quattro modi per affrontarli.
Un singolo indice seleziona un elemento. $.store.book[0] restituisce il primo libro e JSONPath, come la maggior parte delle lingue, conta da zero. Un indice negativo conta dalla fine, quindi $.store.book[-1] restituisce l'ultimo libro senza che tu abbia bisogno di sapere quanti ce ne sono Quel modulo negativo è veramente utile quando vuoi l'elemento più recente in un registro o l'ultima voce in un feed.
Un carattere jolly seleziona ogni elemento. $.store.book[*] restituisce tutti e quattro i libri e $.store.book[*].author restituisce l'autore di ciascuno, dandoti una gamma pulita di autori Il carattere jolly funziona anche sugli oggetti, dove $.store.* restituisce ogni valore dell'oggetto negozio indipendentemente dalla chiave.
Un sindacato seleziona un insieme specifico. $.store.book[0,2] restituisce il primo e il terzo libro e la stessa sintassi della virgola funziona con i nomi, quindi $['store']['bicycle'] e i tasti con virgolette tra parentesi ti consentono di indirizzare i tasti che contengono spazi o punteggiatura che il punto non può formare.
Una fetta seleziona un intervallo, prendendo in prestito Python' S start:end:step forma. $.store.book[:2] prende i primi due, $.store.book[1:3] prende un intervallo medio con l'esclusiva dell'indice finale, $.store.book[::2] prende ogni secondo elemento, e $.store.book[::-1] inverte l'array Le fette sono la parte meno conosciuta della sintassi e quella che salva più digitazioni una volta che l'hai.
Cosa fa il doppio punto?
Il doppio punto è la discesa ricorsiva, ed è la caratteristica che fa sentire JSONPath come una ricerca piuttosto che un percorso. $..author trova ogni author chiave in qualsiasi punto del documento, non importa quanto profondamente sia annidato, e $..* restituisce ogni valore ad ogni livello Quando non si conosce la forma esatta di un documento, o quando lo stesso campo appare a diverse profondità, la discesa ricorsiva li trova tutti in un'unica espressione.
Considera la libreria di esempio. $..price restituisce cinque valori, i quattro prezzi dei libri e il prezzo della bicicletta, perché scende in ogni oggetto e raccoglie ogni price trova. Una pianura $.store.book[*].price restituirebbe solo i quattro prezzi dei libri, perché percorre un percorso fisso La differenza tra queste due espressioni è la differenza tra chiedere prezzi in una località conosciuta e chiedere prezzi ovunque.
La discesa ricorsiva è abbastanza potente da essere pericolosa, nel senso che può corrispondere più di quanto intendevi. Questo è esattamente il motivo per cui qui conta un tester. Corri $..name contro un payload non familiare e potresti scoprire che corrisponde a un nome utente, un nome di prodotto e un nome di file che non avevi idea di condividere una chiave Vedere i percorsi nell'output ti dice se restringere l'espressione prima di fare affidamento su di essa.
Come funzionano le espressioni di filtro?
Un filtro mantiene solo gli elementi per i quali una condizione è vera, ed è scritto [?(...)] di @ sta per l'elemento corrente. $.store.book[?(@.price < 10)] restituisce i libri più economici di dieci All'interno del filtro è possibile confrontare un campo rispetto a un letterale con gli operatori ==, !=, <, <=, >, e >=, testare la semplice presenza di un campo e combinare le condizioni con && e ||.
Alcuni esempi concreti rendono chiara la forma:
$.store.book[?(@.category == "fiction")]seleziona i titoli di fiction.$.store.book[?(@.price < 10 && @.category == "fiction")]si restringe alla narrativa a buon mercato.$.store.book[?(@.isbn)]seleziona solo i libri che hanno un codice ISBN, utilizzando l'esistenza anziché il confronto.$.vals[?(@ > 2)]filtra una semplice matrice di numeri, dove@da solo si riferisce all'elemento stesso.
Il singolo bug del filtro più comune è una mancata corrispondenza dei tipi. In JSON, "12" e 12 sono valori diversi, quindi un filtro che confronta un campo numerico con un numero quotato, o un campo stringa con un numero nudo, non corrisponde silenziosamente a nulla Quando un filtro ti sorprende, la prima cosa da verificare è se il campo e il letterale sono dello stesso tipo Testare l'espressione rispetto ai dati reali, dove puoi vedere i valori effettivi, è il modo in cui lo catturi in pochi secondi invece che dopo una distribuzione fallita.
JSONPath contro JSON Pointer contro JSON diff
Questi tre strumenti toccano tutti la struttura JSON, ma rispondono a domande diverse e scegliere quello sbagliato fa perdere tempo. Ecco come si confrontano:
| avvicinare | Risposte | fiammiferi | Meglio per |
|---|---|---|---|
| JSONPath | Quali nodi soddisfano questa query? | Zero, uno, o molti | Estrazione di campi, filtraggio di array, esplorazione di forme sconosciute |
| Puntatore JSON (RFC 6901) | Cosa c'è in questa posizione esatta? | Sempre esattamente una | Riferimento a un singolo campo fisso, come nello schema JSON $ref |
| JSON diff | Cosa è cambiato tra due documenti? | Un insieme di cambiamenti | Confronto di due versioni degli stessi dati |
Puntatore JSON, definito in RFC6901affronta un punto preciso con un percorso separato da barre come /store/book/0/title, e non utilizza mai caratteri jolly o filtri Raggiungilo quando devi nominare un singolo campo in modo inequivocabile Raggiungi JSONPath quando una singola espressione dovrebbe selezionare un insieme di campi E quando la tua vera domanda è cosa differisce tra due payload anziché cosa seleziona una query, a JSON DIFF è lo strumento giusto Sapere quale dei tre ti serve effettivamente è metà della battaglia.
Perché la mia espressione non restituisce alcun risultato?
Un risultato vuoto deriva quasi sempre da una delle poche cause e un tester ti consente di escluderle rapidamente.
Il primo è un disallineamento strutturale Hai scritto $.data.items.name in cui items è un array, quindi ne avevi bisogno $.data.items[*].name con un carattere jolly La forma punto entra in un oggetto e un array non è un oggetto con a name chiave, quindi il percorso termina. Commutando la vista di output su percorsi e facendo passare l'espressione un segmento alla volta viene mostrato esattamente dove smette di corrispondere.
Il secondo è un errore di ortografia o di involucro Le chiavi JSON sono case sensitive, quindi $.userId non corrisponderà a userID field, e uno spazio finale o un errore di battitura in un nome chiave produce lo stesso silenzioso nulla Poiché il tester ti mostra il documento proprio accanto all'espressione, questi sono veloci da individuare.
Il terzo, come trattato sopra, è un disadattamento del tipo di filtro, in cui un confronto numerico viene eseguito rispetto a un valore di stringa o al contrario. Il quarto presuppone che esista una chiave su ogni elemento quando esiste solo su alcuni. I filtri ricorsivi di discesa ed esistenza sono i soliti rimedi. In ogni caso, la correzione deriva dal guardare a quali nodi tocca l'espressione, che è esattamente lo scopo di un tester.
Se si costruisce attraverso lo stack nel modo in cui lo faccio io, spostandosi tra un'API Laravel, un front-end React e lo script di shell occasionale, JSONPath si presenta in tutti e tre e un tester basato su browser che non carica mai i dati è lo strumento che ho scritto su come utilità come questa si inseriscono in un kit più ampio nel Toolkit per sviluppatori web, e il caso di mantenere questo tipo di lavoro lato cliente è nel Privacy dei dati negli strumenti online guida.
Come si adatta questo al resto del mio flusso di lavoro JSON?
Un tester JSONPath è raramente l'unico strumento aperto Quando il JSON che sto interrogando è arrivato minified o con rientro incoerente, lo eseguo attraverso il Formattatore JSON per prima cosa posso leggere la struttura mentre scrivo l'espressione Il formattatore e il tester insieme sono il modo in cui passo da una risposta API illeggibile a una query funzionante.
Una volta che so a quali campi tengo, il passo successivo è spesso quello di rimodellarli Se devo inserire i valori selezionati in un foglio di calcolo o in un file di ambiente, il JSON Flattener trasforma la struttura nidificata in chiavi di notazione punto e la sua sintassi del percorso è abbastanza vicina a JSONPath da rinforzare l'una l'altra. Se sto costruendo un tipo per i dati in TypeScript, il JSON a dattiloscritto convertitore genera l'interfaccia, e se ho bisogno di convalidare la forma piuttosto che limitarmi a leggerla, il Generatore di schemi JSON produce uno schema a cui posso aggiungere dei vincoli JSONPath è il passo di esplorazione; questi strumenti sono quello che faccio con quello che trovo.
Vale la pena ripetere il punto privacy perché il lavoro JSONPath avviene così spesso contro dati sensibili Le risposte API portano token, record utente e ID interni e incollarli in uno strumento lato server significa fidarsi di qualcun altro' registra Perché il tester Toolz.dev analizza e valuta interamente nel tuo browser, niente di tutto ciò lascia la tua macchina e lo strumento continua a funzionare con la rete disconnessa Questa è la differenza tra uno strumento che puoi utilizzare su un payload di stadiazione e uno che puoi utilizzare sulla cosa reale.
Domande frequenti
A cosa serve JSONPath?
JSONPath viene utilizzato per selezionare ed estrarre parti di un documento JSON con una singola espressione È il linguaggio di query negli strumenti di test API, nella formattazione dell'output di Kubernetes, nei servizi cloud come AWS Step Functions e in molte piattaforme low-code, ovunque qualcuno abbia bisogno di estrarre un campo o filtrare un array da un payload JSON senza scrivere codice procedurale.
Come faccio a selezionare ogni elemento di un array in JSONPath?
Usa il carattere jolly, quindi $.items[*] restituisce ogni elemento dell'array di elementi e $.items[*].id restituisce l'id di ciascuno È anche possibile selezionare un elemento per indice con $.items[0], l'ultimo elemento con l'indice negativo $.items[-1], un set con un'unione come $.items[0,2], o un intervallo con una fetta simile $.items[1:3].
Cosa significa il doppio punto in JSONPath?
Il doppio punto è la discesa ricorsiva, che cerca a qualsiasi profondità. $..author trova ogni chiave dell'autore in qualsiasi punto del documento, non importa quanto profondamente annidata, e $..* restituisce ogni valore ad ogni livello È il modo più veloce per estrarre un campo da un documento di cui non conosci in anticipo l'esatta struttura.
Come funzionano le espressioni di filtro in JSONPath?
Un filtro [?(...)] mantiene solo gli elementi per i quali una condizione è vera, con @ riferendosi all'elemento corrente Ad esempio $.book[?(@.price < 10)] restituisce libri più economici di dieci e puoi combinare le condizioni con && e ||, come ad esempio [?(@.price < 10 && @.category == "fiction")]. Puoi anche testare l'esistenza di un campo's con [?(@.isbn)].
Perché la mia espressione JSONPath non restituisce nulla?
Le due cause più comuni sono una mancata corrispondenza strutturale e una mancata corrispondenza dei tipi Controlla che ogni chiave esista e sia scritta con l'involucro esatto, e che tu abbia usato un carattere jolly in cui i dati sono un array anziché un oggetto Nei filtri, ricorda che & quot;12" e 12 sono valori diversi, quindi confronta un campo stringa con un valore quotato e un campo numerico con un numero nudo.
Qual è la differenza tra JSONPath e JSON Pointer?
Un puntatore JSON indirizza una posizione esatta, come /store/book/0/title, e restituisce sempre un singolo valore JSONPath è un linguaggio di query in cui una singola espressione può corrispondere a molti nodi contemporaneamente tramite caratteri jolly, discesa ricorsiva e filtri Utilizza un puntatore per fare riferimento a un campo fisso e JSONPath per selezionare un insieme di campi o filtrare una raccolta.
Posso vedere il percorso di ogni partita, non solo il valore?
Sì. Passa la modalità di output ai percorsi per ottenere la posizione normalizzata di ogni corrispondenza, oppure le voci per ottenere insieme il percorso e il valore Vedere i percorsi reali è il modo più rapido per perfezionare un'espressione finché non seleziona esattamente i nodi che intendevi, il che è particolarmente utile con la discesa ricorsiva.
Il mio JSON viene caricato quando utilizzo il tester?
No. Il documento viene analizzato e l'espressione viene valutata nel browser con JavaScript, quindi non viene trasmesso, registrato o archiviato nulla È possibile confermarlo guardando la scheda di rete mentre si esegue una query, o disconnettendosi da internet, perché il tester continua a funzionare offline una volta caricata la pagina.
Provalo sui tuoi dati con il gratuito Tester JSONPath. Valuta i caratteri jolly, la discesa ricorsiva, le sezioni, le unioni e le espressioni di filtro interamente nel browser, senza che venga caricato nulla.
