Par Jerry Fan

JSONL en Go : bufio, json.Decoder et concurrence

Un guide complet pour manipuler des fichiers JSONL (JSON Lines) en Go. Apprenez à lire, écrire et traiter des données JSONL en streaming et de façon concurrente avec bufio, encoding/json et les goroutines de la bibliothèque standard.

Pourquoi choisir Go pour le JSONL ?

Go est un excellent choix pour traiter des fichiers JSONL, surtout si les performances et la concurrence sont des critères importants. La bibliothèque standard fournit tout le nécessaire : bufio pour des entrées-sorties efficaces ligne par ligne, encoding/json pour le parsing et la sérialisation, et les goroutines pour le traitement parallèle. Aucune dépendance tierce n’est nécessaire. Comme Go est un langage compilé, votre pipeline JSONL s’exécutera nettement plus vite que des scripts équivalents en Python ou Node.js, avec souvent des millions de lignes traitées par seconde, même sur du matériel modeste.

JSONL (JSON Lines) stocke un objet JSON par ligne, ce qui convient naturellement au modèle d’entrées-sorties en streaming de Go. Plutôt que de charger tout le fichier en mémoire, vous pouvez lire et traiter les enregistrements un par un avec un scanner ou un décodeur. Les goroutines légères et les canaux de Go vous permettent ensuite de construire des pipelines JSONL concurrents qui exploitent à pleine capacité tous les cœurs CPU disponibles. Dans ce guide, vous apprendrez à lire du JSONL avec bufio.Scanner, à le traiter en streaming avec json.Decoder, à l’écrire efficacement, à traiter les enregistrements de façon concurrente et à gérer les erreurs de manière robuste.

Lire des fichiers JSONL avec bufio.Scanner

La méthode la plus simple pour lire du JSONL en Go consiste à utiliser bufio.Scanner. Il lit le fichier ligne par ligne, puis vous parsez chaque ligne avec json.Unmarshal. Cette approche vous laisse entièrement la main sur la taille des buffers et la gestion des erreurs.

Ouvrez le fichier, créez un scanner et parcourez les lignes. Chaque ligne est décodée dans une map ou une struct avec json.Unmarshal. La consommation mémoire reste ainsi proportionnelle à la taille d’un seul enregistrement, plutôt qu’à celle du fichier entier.

Lecture simple avec 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)


	// Augmenter le tampon pour les lignes de plus de 64 Ko
	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))
}

En production, décodez les enregistrements JSONL dans des structures Go typées plutôt que dans des maps génériques. Vous bénéficiez ainsi d’une vérification des types à la compilation, de meilleures performances et d’un code plus lisible. Ajoutez des tags json à votre struct pour définir la correspondance entre les champs.

Décoder les données dans des structures typées
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)
	}
}

Lire en streaming avec json.Decoder

Pour un traitement en streaming performant, json.Decoder lit directement depuis un io.Reader, sans étape intermédiaire de découpage en lignes. Il gère les buffers en interne. C’est l’approche recommandée pour les gros fichiers JSONL et les flux réseau lorsque vous souhaitez limiter les allocations mémoire.

json.NewDecoder prend en charge n’importe quel io.Reader et décode les valeurs JSON les unes après les autres. Chaque appel à Decode lit exactement un objet JSON. À la fin du flux, il renvoie io.EOF. Cette méthode est plus efficace que bufio.Scanner + json.Unmarshal, car elle évite de copier chaque ligne dans un buffer distinct.

Lire en streaming avec 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++


		// Traiter chaque enregistrement au fur et a mesure du decodage
		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)
	}
}

Écrire des fichiers JSONL en Go

Écrire du JSONL en Go est simple : sérialisez chaque enregistrement avec json.Marshal, ajoutez un octet de saut de ligne, puis écrivez le résultat dans un fichier. Pour obtenir les meilleures performances, utilisez un bufio.Writer pour les écritures dans le fichier afin de réduire les appels système.

Utilisez json.Marshal pour sérialiser chaque enregistrement sous forme d’octets JSON, puis écrivez ces octets suivis d’un saut de ligne. Cette méthode est simple et convient bien aux fichiers de petite ou moyenne taille.

Écriture simple avec 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))
}

Pour écrire à haut débit, utilisez json.NewEncoder avec un bufio.Writer. L’encodeur ajoute automatiquement un saut de ligne après chaque appel à Encode. Le buffer regroupe les petites écritures pour écrire davantage de données à chaque appel système. Appelez toujours Flush avant de fermer le fichier.

Écriture avec buffer et 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)


	// Desactiver l'echappement HTML pour une sortie plus propre
	encoder.SetEscapeHTML(false)


	for i, event := range events {
		if err := encoder.Encode(event); err != nil {
			return fmt.Errorf("encode event %d: %w", i, err)
		}
	}


	// Vider les donnees bufferisees dans le fichier
	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)
	}
}

Traiter du JSONL de façon concurrente avec les goroutines

Les goroutines et les canaux de Go permettent de créer facilement des pipelines JSONL concurrents. Le schéma fan-out consiste à lire les enregistrements d’un fichier, à les répartir entre plusieurs goroutines de travail, puis à récupérer les résultats via un canal. Il convient particulièrement aux transformations gourmandes en CPU sur de gros fichiers JSONL.

Traiter du JSONL de façon concurrente avec les goroutines
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 {
	// Simuler un travail intensif en CPU
	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)


	// Demarrer les workers
	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)
			}
		}()
	}


	// Fermer le canal des resultats quand tous les workers ont termine
	go func() {
		wg.Wait()
		close(results)
	}()


	// Lire le fichier et envoyer les enregistrements aux workers
	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)
	}()


	// Collecter et ecrire les resultats
	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)
}

Ce schéma fan-out répartit les enregistrements JSONL entre autant de goroutines qu’il y a de cœurs CPU. Les canaux avec buffer évitent aux goroutines de se bloquer lors de l’envoi ou de la réception. sync.WaitGroup garantit que tous les workers ont terminé avant la fermeture du canal de résultats. Pour les traitements limités par les entrées-sorties, comme les appels API, vous pouvez augmenter numWorkers au-delà du nombre de cœurs CPU. Attention : le traitement concurrent ne garantit pas l’ordre des résultats en sortie.

Bonnes pratiques de gestion des erreurs

Pour traiter du JSONL de manière robuste en Go, il faut soigner la gestion des erreurs. En pratique, les fichiers JSONL peuvent contenir des lignes mal formées, des problèmes d’encodage ou des enregistrements d’une taille inattendue. L’approche suivante permet de suivre les erreurs par ligne, de configurer le passage à la ligne suivante en cas d’erreur et de produire un bilan du traitement.

Bonnes pratiques de gestion des erreurs
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()


		// Ignorer les lignes vides
		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 structure JSONLReader suit les numéros de ligne, recueille les erreurs de parsing avec le contenu brut correspondant et produit un bilan des réussites et des échecs. Le buffer de 10 Mo du scanner permet de traiter des lignes inhabituellement longues sans déclencher de panique. En production, vous pouvez enrichir cette implémentation en ajoutant la prise en charge de context.Context pour l’annulation, un nombre maximal d’erreurs au-delà duquel le traitement s’arrête, ou encore des logs structurés avec slog.

Les packages Go pour traiter du JSONL

La bibliothèque standard de Go fournit toutes les briques nécessaires au traitement du JSONL. Voici les trois principales approches et les cas d’utilisation adaptés à chacune.

bufio.Scanner

Flexible

Le lecteur standard pour parcourir un fichier ligne par ligne. Il s’utilise avec json.Unmarshal, que vous appelez explicitement pour parser chaque ligne. C’est le bon choix pour contrôler la taille des buffers, ignorer ou inspecter les lignes brutes, ou obtenir les numéros de ligne pour signaler les erreurs. Il accepte les lignes jusqu’à la taille de buffer configurée.

json.Decoder

Recommandé

Un décodeur JSON en streaming qui lit directement depuis un io.Reader. Plus efficace que Scanner + Unmarshal, car il évite la copie des données. Il convient particulièrement aux gros fichiers et aux flux réseau. Il gère automatiquement les valeurs JSON qui se suivent, sans découpage explicite au niveau des sauts de ligne.

json.Encoder

Écriture

Un encodeur JSON en streaming qui écrit dans un io.Writer. Il ajoute automatiquement un saut de ligne après chaque appel à Encode, ce qui le rend idéal pour produire du JSONL. Associez-le à bufio.Writer pour écrire à haut débit. Il se configure à l’aide de SetEscapeHTML et SetIndent.

Manipulez vos fichiers JSONL en ligne

Visualisez, validez et convertissez des fichiers JSONL jusqu’à 1 Go directement dans votre navigateur. Aucun envoi de fichier nécessaire, confidentialité à 100%.

Questions fréquentes

Références