Salta ai contenuti

12. Performance

  • 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, indent in 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:

  1. 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 usa structuredClone(x).
  2. Meno byte = più veloce ovunque: rete, parsing, memoria. Chiedi solo i campi che servono (paginazione, select nelle query strutturate), e attiva la compressione HTTP: un JSON ripetitivo si comprime 5–10 volte.
  3. Niente indent in produzione. L’indentazione serve agli umani; tra macchine aumenta i byte del 20–40 % senza nessun vantaggio.

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.

Misuriamo i byte con e senza compressione contro il server pubblico (dietro Caddy, che comprime).

terminale
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/null il corpo si butta
grep -i content-encoding
mostra solo l'header che dice come è compressa la risposta

Cosa dovresti vedere:

33891 byte, 0.07s
5708 byte, 0.08s
content-encoding: gzip

Sul 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.

# pip install httpx orjson
import json, timeit, httpx, orjson
testo = httpx.get("https://corso-api-json.giuseppebosi.com/api/v1/export/books.ndjson").text
righe = [r for r in testo.splitlines() if r]
grande = "[" + ",".join(righe) + "]" # un array JSON da ~34 KB
dati = json.loads(grande)
N = 200
ms = 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'> ← attenzione
print(orjson.dumps({"x": 1.5}, option=orjson.OPT_INDENT_2))

Output sulla macchina del corso (VPS modesto):

byte: 33885
json.loads 0.5 ms
orjson.loads 0.2 ms
json.dumps 0.6 ms
orjson.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.

Confronta i byte: pagina completa contro proiezione dei soli campi che servono.

GET/api/v1/books?limit=50— 50 libri completi
POST/api/v1/query— gli stessi 50 libri, solo tre campi

Provalo online, senza installare nulla:

Apri il notebook in Google Colab Apri il progetto TypeScript in StackBlitz

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/.

  1. Ripeti il benchmark Python con grande moltiplicato per 100 ("[" + ",".join(righe * 100) + "]", ~3.4 MB). Di quanto cambia il rapporto json/orjson?
  2. Con curl, misura %{size_download} di /api/v1/books?limit=100 con e senza --compressed sul server pubblico. Qual è il rapporto di compressione?
Cosa aspettarsi
  1. Il rapporto resta simile (3–5×) ma i valori assoluti passano a decine di millisecondi: è lì che orjson inizia a contare.
  2. 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.
  • orjson.dumps() restituisce bytes: 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=2 lasciato nel codice di produzione: byte in più a ogni risposta.

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.