Di Jerry Fan

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.

Lettura di base con bufio.Scanner
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.

Deserializzare i record in struct tipizzate
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.

Streaming con json.Decoder
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.

Scrittura di base con json.Marshal
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.

Scrittura con buffer e json.Encoder
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.

Elaborare dati JSONL in modo concorrente con le goroutine
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.

Buone pratiche per la gestione degli errori
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

Flessibile

Lo 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

Consigliato

Decoder 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

Scrittura

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

Lavora con i file JSONL online

Visualizza, valida e converti file JSONL fino a 1GB direttamente nel browser. Non devi caricare alcun file su un server: la privacy è garantita al 100%.

Domande frequenti

Riferimenti