12. Performance
Obiettivi
Sezione intitolata “Obiettivi”- Misurare il costo di parsing e serializzazione con un benchmark riproducibile.
- Sapere quando
orjson(Python) vale la dipendenza in più, e quando no. - Ridurre i byte sul filo con la compressione HTTP (
Accept-Encoding). - Riconoscere gli sprechi tipici: parse/stringify ripetuti, copie inutili,
indentin produzione.
Il parsing JSON è CPU-bound e proporzionale ai byte. Ordini di grandezza indicativi su una macchina moderna: il modulo json di Python fa circa 50–100 MB/s, orjson 5–10 volte tanto; JSON.parse di V8 (Node) è nell’ordine di 100–300 MB/s. Per capire se a te serve ottimizzare, misura sul tuo carico: un benchmark di 10 righe vale più di qualunque tabella.
Tre regole che pesano più della libreria:
- Non parsare due volte.
JSON.parse(JSON.stringify(x))come “deep clone” o convertire stringa → oggetto → stringa in ogni passaggio di una pipeline è lo spreco più comune. In JS usastructuredClone(x). - Meno byte = più veloce ovunque: rete, parsing, memoria. Chiedi solo i campi che servono (paginazione,
selectnelle query strutturate), e attiva la compressione HTTP: un JSON ripetitivo si comprime 5–10 volte. - Niente
indentin produzione. L’indentazione serve agli umani; tra macchine aumenta i byte del 20–40 % senza nessun vantaggio.
orjson in due parole
Sezione intitolata “orjson in due parole”orjson è una libreria in Rust: orjson.loads(bytes|str) -> obj, orjson.dumps(obj) -> bytes (attenzione: bytes, non str). Serializza nativamente datetime, dataclass, numpy, UUID; l’opzione OPT_INDENT_2 indenta, OPT_SORT_KEYS ordina le chiavi. Non supporta object_hook, default è supportato. FastAPI la usa automaticamente con ORJSONResponse.
curl, spiegato
Sezione intitolata “curl, spiegato”Misuriamo i byte con e senza compressione contro il server pubblico (dietro Caddy, che comprime).
curl -s -o /dev/null -w '%{size_download} byte, %{time_total}s\n' \https://corso-api-json.giuseppebosi.com/api/v1/export/books.ndjson
curl -s -o /dev/null -w '%{size_download} byte, %{time_total}s\n' \-H 'Accept-Encoding: gzip' --compressed \https://corso-api-json.giuseppebosi.com/api/v1/export/books.ndjson
curl -s -D - -o /dev/null -H 'Accept-Encoding: gzip' 'https://corso-api-json.giuseppebosi.com/api/v1/books?limit=100' | grep -i content-encoding- -o /dev/null
- butta via il corpo: qui interessano solo le misure
- -w '…'
- write-out: stampa un formato con variabili di curl dopo la richiesta
- %{size_download}
- byte effettivamente scaricati (compressi, se compressi)
- %{time_total}
- tempo totale della richiesta in secondi
- -H 'Accept-Encoding: gzip'
- header che dice al server: "accetto una risposta compressa gzip" (anche
br,zstd) - --compressed
- fa decomprimere a curl il corpo ricevuto; senza, curl salverebbe i byte gzip così come sono
- -D -
- dump header: stampa gli header della risposta (
-= sullo schermo); con-o /dev/nullil corpo si butta - grep -i content-encoding
- mostra solo l'header che dice come è compressa la risposta
Cosa dovresti vedere:
33891 byte, 0.07s5708 byte, 0.08scontent-encoding: gzipSul server pubblico l’export passa da ~34 KB a ~6 KB. La compressione la fanno in tandem FastAPI (GZipMiddleware, anche sulle risposte in streaming) e il reverse proxy Caddy (che aggiunge zstd e comprime le pagine del sito): la vedi anche in locale con uv run fastapi dev.
Python e TypeScript
Sezione intitolata “Python e TypeScript”# pip install httpx orjsonimport json, timeit, httpx, orjson
testo = httpx.get("https://corso-api-json.giuseppebosi.com/api/v1/export/books.ndjson").textrighe = [r for r in testo.splitlines() if r]grande = "[" + ",".join(righe) + "]" # un array JSON da ~34 KBdati = json.loads(grande)N = 200ms = lambda f: timeit.timeit(f, number=N) / N * 1000
print("byte:", len(grande))print("json.loads %.2f ms" % ms(lambda: json.loads(grande)))print("orjson.loads %.2f ms" % ms(lambda: orjson.loads(grande)))print("json.dumps %.2f ms" % ms(lambda: json.dumps(dati)))print("orjson.dumps %.2f ms" % ms(lambda: orjson.dumps(dati)))print(type(orjson.dumps(dati))) # <class 'bytes'> ← attenzioneprint(orjson.dumps({"x": 1.5}, option=orjson.OPT_INDENT_2))Output sulla macchina del corso (VPS modesto):
byte: 33885json.loads 0.5 msorjson.loads 0.2 msjson.dumps 0.6 msorjson.dumps 0.1 ms<class 'bytes'>b'{\n "x": 1.5\n}'Su 34 KB la differenza è mezzo millisecondo: irrilevante. Su 340 MB diventa secondi. Regola pratica: orjson quando serializzi/parsi molti MB al secondo (API ad alto traffico, pipeline di dati); altrimenti json va benissimo e non aggiunge dipendenze compilate.
// node --experimental-strip-types bench.tsconst r = await fetch("https://corso-api-json.giuseppebosi.com/api/v1/export/books.ndjson");const righe = (await r.text()).split("\n").filter(Boolean);const grande = "[" + righe.join(",") + "]";const N = 200;
let t = performance.now();for (let i = 0; i < N; i++) JSON.parse(grande);console.log(`JSON.parse ${((performance.now() - t) / N).toFixed(2)} ms su ${grande.length} byte`);
const dati = JSON.parse(grande);t = performance.now();for (let i = 0; i < N; i++) JSON.stringify(dati);console.log(`JSON.stringify ${((performance.now() - t) / N).toFixed(2)} ms`);
// deep clone: structuredClone batte parse(stringify(x)) ed è corretto con Date, Map, Sett = performance.now();for (let i = 0; i < N; i++) structuredClone(dati);console.log(`structuredClone ${((performance.now() - t) / N).toFixed(2)} ms`);Output sulla macchina del corso:
JSON.parse 0.32 ms su 33885 byteJSON.stringify 0.16 msstructuredClone 0.6 msIn JavaScript non c’è un “orjson”: JSON.parse è già nativo e ottimizzato. Le vittorie vengono dalle regole 1–3 e, per file enormi, dallo streaming del capitolo 11. Un trucco reale di V8: per oggetti di configurazione grandi (>10 KB) inclusi in un bundle, JSON.parse('...') è più veloce di un literal oggetto, perché il parser JSON è più semplice di quello JS.
Prova subito
Sezione intitolata “Prova subito”Confronta i byte: pagina completa contro proiezione dei soli campi che servono.
Header della risposta
Header della risposta
Esercizio
Sezione intitolata “Esercizio”Provalo online, senza installare nulla:
La richiesta GET diretta nel browser: https://corso-api-json.giuseppebosi.com/api/v1/books?limit=50
Python su Google Colab (serve un account Google gratuito per eseguire le celle); TypeScript su StackBlitz (si apre e parte da solo nel browser). Se l’API di prova è spenta, accendila da /api-attiva/.
- Ripeti il benchmark Python con
grandemoltiplicato per 100 ("[" + ",".join(righe * 100) + "]", ~3.4 MB). Di quanto cambia il rapportojson/orjson? - Con curl, misura
%{size_download}di/api/v1/books?limit=100con e senza--compressedsul server pubblico. Qual è il rapporto di compressione?
Cosa aspettarsi
- Il rapporto resta simile (3–5×) ma i valori assoluti passano a decine di millisecondi: è lì che
orjsoninizia a contare. - Circa 5–7×: JSON con chiavi ripetute (“title”, “price”…) si comprime molto bene. È il motivo per cui la compressione va sempre attiva su un’API.
Errori comuni
Sezione intitolata “Errori comuni”orjson.dumps()restituiscebytes:f.write(orjson.dumps(x))su un file aperto in modalità testo fallisce; apri in"wb"o fai.decode().- Benchmark su una sola esecuzione: la prima chiamata paga cache e JIT; ripeti N volte e fai la media (o usa
timeit). - Ottimizzare il parsing quando il collo di bottiglia è la rete (vedi l’avviso sopra).
indent=2lasciato nel codice di produzione: byte in più a ogni risposta.
In sintesi
Sezione intitolata “In sintesi”Misura, comprimi, non parsare due volte. orjson è un’ottima leva quando i MB al secondo sono tanti; prima di allora il json di serie basta. Nel prossimo capitolo JSON entra nel database: colonne JSON, funzioni SQL e indici.