JSONL in Go: bufio, json.Decoder e concorrenza
Una guida completa per lavorare con i file JSONL (JSON Lines) in Go. Impara a leggere, scrivere ed elaborare dati JSONL in streaming e in modo concorrente con bufio ed encoding/json della libreria standard e con le goroutine.
Perché usare Go per JSONL?
Go è un’ottima scelta per elaborare file JSONL, soprattutto quando contano le prestazioni e la concorrenza. La libreria standard offre tutto il necessario: bufio per operazioni di I/O efficienti riga per riga, encoding/json per il parsing e la serializzazione e le goroutine per l’elaborazione parallela. Non servono dipendenze di terze parti. Essendo un linguaggio compilato, Go permette alla tua pipeline JSONL di essere nettamente più veloce degli script equivalenti in Python o Node.js, arrivando spesso a elaborare milioni di righe al secondo anche su hardware modesto.
Il formato JSONL (JSON Lines) memorizza un oggetto JSON per riga e si presta quindi al modello di I/O in streaming di Go. Anziché caricare in memoria l’intero file, puoi leggere ed elaborare un record alla volta con uno scanner o un decoder. Grazie anche alle goroutine leggere e ai canali di Go, puoi creare pipeline JSONL concorrenti che sfruttano appieno tutti i core della CPU disponibili. In questa guida imparerai a leggere file JSONL con bufio.Scanner, a elaborarli in streaming con json.Decoder, a scriverli in modo efficiente, a elaborare i record in modo concorrente e a gestire gli errori in modo robusto.
Leggere file JSONL con bufio.Scanner
Il modo più semplice per leggere file JSONL in Go è usare bufio.Scanner: lo scanner legge il file riga per riga e json.Unmarshal esegue il parsing di ogni riga. Con questo approccio hai il pieno controllo sulle dimensioni del buffer e sulla gestione degli errori.
Apri il file, crea uno scanner e scorri le righe. Con json.Unmarshal, il contenuto di ogni riga viene deserializzato in una map o in una struct. In questo modo il consumo di memoria resta proporzionale alle dimensioni di un singolo record, anziché a quelle dell’intero file.
package main
import (
"bufio"
"encoding/json"
"fmt"
"log"
"os"
)
func main() {
file, err := os.Open("data.jsonl")
if err != nil {
log.Fatal(err)
}
defer file.Close()
var records []map[string]any
scanner := bufio.NewScanner(file)
// Aumenta il buffer per righe più lunghe di 64KB
scanner.Buffer(make([]byte, 0, 1024*1024), 1024*1024)
for scanner.Scan() {
var record map[string]any
if err := json.Unmarshal(scanner.Bytes(), &record); err != nil {
log.Printf("skipping invalid JSON: %v", err)
continue
}
records = append(records, record)
}
if err := scanner.Err(); err != nil {
log.Fatal(err)
}
fmt.Printf("Loaded %d records\n", len(records))
}Nel codice destinato alla produzione, deserializza i record JSONL in struct Go tipizzate anziché in map generiche. Ottieni così controlli sui tipi in fase di compilazione, prestazioni migliori e codice più chiaro. Definisci la struct con i tag json per stabilire la corrispondenza tra i campi.
package main
import (
"bufio"
"encoding/json"
"fmt"
"log"
"os"
)
type User struct {
ID int `json:"id"`
Name string `json:"name"`
Email string `json:"email"`
Age int `json:"age,omitempty"`
}
func readUsers(path string) ([]User, error) {
file, err := os.Open(path)
if err != nil {
return nil, fmt.Errorf("open file: %w", err)
}
defer file.Close()
var users []User
scanner := bufio.NewScanner(file)
lineNum := 0
for scanner.Scan() {
lineNum++
var u User
if err := json.Unmarshal(scanner.Bytes(), &u); err != nil {
return nil, fmt.Errorf("line %d: %w", lineNum, err)
}
users = append(users, u)
}
if err := scanner.Err(); err != nil {
return nil, fmt.Errorf("scanner error: %w", err)
}
return users, nil
}
func main() {
users, err := readUsers("users.jsonl")
if err != nil {
log.Fatal(err)
}
for _, u := range users {
fmt.Printf("%s (%s)\n", u.Name, u.Email)
}
}Streaming con json.Decoder
Per elaborare dati in streaming ad alte prestazioni, json.Decoder legge direttamente da un io.Reader, senza un passaggio intermedio per suddividere i dati in righe. Gestisce internamente il buffering ed è la soluzione consigliata per file JSONL di grandi dimensioni o flussi di rete quando vuoi ridurre al minimo le allocazioni.
json.NewDecoder accetta qualsiasi io.Reader e decodifica i valori JSON in sequenza. Ogni chiamata a Decode legge esattamente un oggetto JSON. Alla fine del flusso, restituisce io.EOF. Questo approccio è più efficiente di bufio.Scanner + json.Unmarshal perché evita di copiare ogni riga in un buffer separato.
package main
import (
"encoding/json"
"errors"
"fmt"
"io"
"log"
"os"
)
type LogEntry struct {
Timestamp string `json:"timestamp"`
Level string `json:"level"`
Message string `json:"message"`
Service string `json:"service"`
}
func processJSONLStream(path string) error {
file, err := os.Open(path)
if err != nil {
return fmt.Errorf("open: %w", err)
}
defer file.Close()
decoder := json.NewDecoder(file)
var count int
for {
var entry LogEntry
err := decoder.Decode(&entry)
if errors.Is(err, io.EOF) {
break
}
if err != nil {
return fmt.Errorf("decode record %d: %w", count+1, err)
}
count++
// Elabora ogni record mentre viene decodificato
if entry.Level == "ERROR" {
fmt.Printf("[%s] %s: %s\n",
entry.Timestamp, entry.Service, entry.Message)
}
}
fmt.Printf("Processed %d log entries\n", count)
return nil
}
func main() {
if err := processJSONLStream("logs.jsonl"); err != nil {
log.Fatal(err)
}
}Scrivere file JSONL in Go
Scrivere file JSONL in Go è semplice: serializza ogni record con json.Marshal, aggiungi un byte di fine riga e scrivi il risultato su file. Per ottenere le migliori prestazioni, usa un bufio.Writer come buffer per la scrittura sul file, così da ridurre le chiamate di sistema.
Usa json.Marshal per serializzare ogni record in una sequenza di byte JSON, quindi scrivi i byte seguiti da un carattere di fine riga. È un approccio semplice, adatto a file di piccole e medie dimensioni.
package main
import (
"encoding/json"
"fmt"
"log"
"os"
)
type Product struct {
ID int `json:"id"`
Name string `json:"name"`
Price float64 `json:"price"`
}
func main() {
products := []Product{
{ID: 1, Name: "Laptop", Price: 999.99},
{ID: 2, Name: "Mouse", Price: 29.99},
{ID: 3, Name: "Keyboard", Price: 79.99},
}
file, err := os.Create("products.jsonl")
if err != nil {
log.Fatal(err)
}
defer file.Close()
for _, p := range products {
data, err := json.Marshal(p)
if err != nil {
log.Printf("skip marshal error: %v", err)
continue
}
data = append(data, '\n')
if _, err := file.Write(data); err != nil {
log.Fatal(err)
}
}
fmt.Printf("Wrote %d records to products.jsonl\n", len(products))
}Per scrivere grandi quantità di dati in modo efficiente, usa json.NewEncoder con un bufio.Writer. L’encoder aggiunge automaticamente un carattere di fine riga dopo ogni chiamata a Encode, mentre il writer con buffer raggruppa le piccole scritture in chiamate di sistema che trasferiscono più dati. Ricorda di chiamare sempre Flush prima di chiudere il file.
package main
import (
"bufio"
"encoding/json"
"fmt"
"log"
"os"
)
type Event struct {
Type string `json:"type"`
Timestamp int64 `json:"timestamp"`
Payload map[string]any `json:"payload"`
}
func writeEvents(path string, events []Event) error {
file, err := os.Create(path)
if err != nil {
return fmt.Errorf("create file: %w", err)
}
defer file.Close()
writer := bufio.NewWriter(file)
encoder := json.NewEncoder(writer)
// Disabilita l'escaping HTML per un output più pulito
encoder.SetEscapeHTML(false)
for i, event := range events {
if err := encoder.Encode(event); err != nil {
return fmt.Errorf("encode event %d: %w", i, err)
}
}
// Scrivi i dati bufferizzati nel file
if err := writer.Flush(); err != nil {
return fmt.Errorf("flush: %w", err)
}
fmt.Printf("Wrote %d events to %s\n", len(events), path)
return nil
}
func main() {
events := []Event{
{Type: "click", Timestamp: 1700000001, Payload: map[string]any{"x": 120, "y": 450}},
{Type: "view", Timestamp: 1700000002, Payload: map[string]any{"page": "/home"}},
}
if err := writeEvents("events.jsonl", events); err != nil {
log.Fatal(err)
}
}Elaborare dati JSONL in modo concorrente con le goroutine
Le goroutine e i canali di Go semplificano la creazione di pipeline JSONL concorrenti. Il pattern fan-out consiste nel leggere i record da un file, distribuirli tra più goroutine worker e raccogliere i risultati tramite un canale. È ideale per le trasformazioni CPU-bound su file JSONL di grandi dimensioni.
package main
import (
"bufio"
"encoding/json"
"fmt"
"log"
"os"
"runtime"
"sync"
)
type Record struct {
ID int `json:"id"`
Data map[string]any `json:"data"`
}
type Result struct {
ID int `json:"id"`
Processed bool `json:"processed"`
Score int `json:"score"`
}
func process(r Record) Result {
// Simula lavoro CPU-bound
score := len(r.Data) * r.ID
return Result{ID: r.ID, Processed: true, Score: score}
}
func main() {
file, err := os.Open("records.jsonl")
if err != nil {
log.Fatal(err)
}
defer file.Close()
numWorkers := runtime.NumCPU()
jobs := make(chan Record, numWorkers*2)
results := make(chan Result, numWorkers*2)
// Avvia i worker
var wg sync.WaitGroup
for i := 0; i < numWorkers; i++ {
wg.Add(1)
go func() {
defer wg.Done()
for record := range jobs {
results <- process(record)
}
}()
}
// Chiudi il canale dei risultati quando tutti i worker terminano
go func() {
wg.Wait()
close(results)
}()
// Leggi il file e invia i record ai worker
go func() {
scanner := bufio.NewScanner(file)
for scanner.Scan() {
var r Record
if err := json.Unmarshal(scanner.Bytes(), &r); err != nil {
log.Printf("skip invalid line: %v", err)
continue
}
jobs <- r
}
close(jobs)
}()
// Raccogli e scrivi i risultati
outFile, err := os.Create("results.jsonl")
if err != nil {
log.Fatal(err)
}
defer outFile.Close()
writer := bufio.NewWriter(outFile)
encoder := json.NewEncoder(writer)
var count int
for result := range results {
if err := encoder.Encode(result); err != nil {
log.Printf("encode error: %v", err)
}
count++
}
writer.Flush()
fmt.Printf("Processed %d records with %d workers\n", count, numWorkers)
}Questo pattern fan-out distribuisce i record JSONL tra un numero di goroutine pari a quello dei core della CPU. I canali con buffer evitano che le goroutine si blocchino durante l’invio o la ricezione. sync.WaitGroup garantisce che tutti i worker abbiano terminato prima della chiusura del canale dei risultati. Per i carichi I/O-bound, come le chiamate API, puoi impostare numWorkers su un valore superiore al numero di CPU. Tieni presente che l’elaborazione concorrente non garantisce l’ordine dei risultati in output.
Buone pratiche per la gestione degli errori
Per elaborare dati JSONL in Go in modo robusto, devi gestire gli errori con attenzione. Nell’uso reale, i file JSONL possono contenere righe malformate, problemi di codifica o record più grandi del previsto. Questo pattern permette di tenere traccia degli errori per ogni riga, configurare il salto delle righe in caso di errore e produrre un riepilogo dell’elaborazione.
package main
import (
"bufio"
"encoding/json"
"fmt"
"log"
"os"
)
type ParseError struct {
Line int
Err error
Raw string
}
func (e *ParseError) Error() string {
return fmt.Sprintf("line %d: %v", e.Line, e.Err)
}
type JSONLReader struct {
scanner *bufio.Scanner
lineNum int
Errors []ParseError
Skipped int
Success int
}
func NewJSONLReader(file *os.File) *JSONLReader {
scanner := bufio.NewScanner(file)
scanner.Buffer(make([]byte, 0, 1024*1024), 10*1024*1024)
return &JSONLReader{scanner: scanner}
}
func (r *JSONLReader) ReadAll(target any) error {
slice, ok := target.(*[]map[string]any)
if !ok {
return fmt.Errorf("target must be *[]map[string]any")
}
for r.scanner.Scan() {
r.lineNum++
line := r.scanner.Bytes()
// Salta le righe vuote
if len(line) == 0 {
continue
}
var record map[string]any
if err := json.Unmarshal(line, &record); err != nil {
r.Errors = append(r.Errors, ParseError{
Line: r.lineNum,
Err: err,
Raw: string(line),
})
r.Skipped++
continue
}
*slice = append(*slice, record)
r.Success++
}
return r.scanner.Err()
}
func (r *JSONLReader) Summary() string {
return fmt.Sprintf(
"Lines: %d | Success: %d | Skipped: %d | Errors: %d",
r.lineNum, r.Success, r.Skipped, len(r.Errors),
)
}
func main() {
file, err := os.Open("data.jsonl")
if err != nil {
log.Fatal(err)
}
defer file.Close()
reader := NewJSONLReader(file)
var records []map[string]any
if err := reader.ReadAll(&records); err != nil {
log.Fatal(err)
}
fmt.Println(reader.Summary())
for _, e := range reader.Errors {
log.Printf("Parse error at %s", e.Error())
}
}La struct JSONLReader tiene traccia dei numeri di riga, raccoglie gli errori di parsing insieme al contenuto originale delle righe e produce un riepilogo dei record elaborati correttamente e di quelli con errori. Il buffer dello scanner da 10MB consente di gestire righe insolitamente grandi senza generare un panic. In produzione, puoi estendere questa soluzione aggiungendo il supporto a context.Context per annullare l’elaborazione, una soglia massima di errori oltre la quale interromperla o il logging strutturato con slog.
Pacchetti Go per elaborare dati JSONL
La libreria standard di Go offre tutti i componenti necessari per elaborare dati JSONL. Ecco i tre approcci principali e quando usarli.
bufio.Scanner
FlessibileLo strumento standard per leggere un file riga per riga, da usare con json.Unmarshal per eseguire esplicitamente il parsing. È la scelta ideale se vuoi controllare le dimensioni del buffer, saltare o esaminare le righe originali oppure includere i numeri di riga nelle segnalazioni di errore. Gestisce righe fino alla dimensione del buffer configurato.
json.Decoder
ConsigliatoDecoder JSON in streaming che legge direttamente da un io.Reader. È più efficiente di Scanner + Unmarshal perché evita di copiare i dati. Ideale per file di grandi dimensioni e flussi di rete. Gestisce automaticamente valori JSON consecutivi, senza dover suddividere esplicitamente i dati in corrispondenza dei caratteri di fine riga.
json.Encoder
ScritturaEncoder JSON in streaming che scrive su un io.Writer. Aggiunge automaticamente un carattere di fine riga dopo ogni chiamata a Encode, risultando ideale per produrre output JSONL. Usalo insieme a bufio.Writer per scrivere grandi quantità di dati in modo efficiente. Supporta la configurazione tramite SetEscapeHTML e SetIndent.
Prova i nostri strumenti gratuiti per JSONL
Non vuoi scrivere codice? Usa i nostri strumenti online gratuiti per visualizzare, validare e convertire file JSONL direttamente nel browser.
Strategie per elaborare gigabyte di dati JSONL: lettura in streaming, gestione della memoria, suddivisione dei file, compressione e strumenti online.
Impara le best practice per la formattazione dei file JSONL, la coerenza dello schema, la gestione degli errori, l’ottimizzazione delle prestazioni e l’organizzazione dei file. Evita gli errori più comuni con esempi pratici.
Valida i file JSONL riga per riga. Individua subito errori di sintassi e problemi di codifica o di formato.
Impara a elaborare dati JSONL in streaming in tempo reale con Node.js, Python, Server-Sent Events e WebSocket. Crea pipeline di streaming per log, metriche e flussi di dati in tempo reale.
Una guida completa per lavorare con i file JSONL in Rust. Impara a usare serde_json e BufReader, l’elaborazione parallela con rayon, l’I/O asincrono con tokio e pattern robusti per la gestione degli errori.