Von Jerry Fan

JSONL in Go: bufio, json.Decoder und Nebenläufigkeit

Ein umfassender Leitfaden zum Umgang mit JSONL-Dateien (JSON Lines) in Go. Erfahren Sie, wie Sie JSONL-Daten mit den Paketen bufio und encoding/json aus der Standardbibliothek sowie mit Goroutines lesen, schreiben, streamen und nebenläufig verarbeiten.

Warum Go für JSONL?

Go eignet sich hervorragend für die Verarbeitung von JSONL-Dateien, besonders wenn es auf Performance und Nebenläufigkeit ankommt. Die Standardbibliothek bringt alles mit, was Sie dafür brauchen: bufio für effiziente zeilenweise Ein- und Ausgabe, encoding/json zum Parsen und Serialisieren sowie Goroutines für die parallele Verarbeitung. Zusätzliche Abhängigkeiten von Drittanbietern sind nicht nötig. Da Go zu Maschinencode kompiliert wird, läuft Ihre JSONL-Pipeline deutlich schneller als vergleichbare Python- oder Node.js-Skripte. Selbst auf einfacher Hardware lassen sich oft Millionen von Zeilen pro Sekunde verarbeiten.

JSONL (JSON Lines) speichert pro Zeile ein JSON-Objekt und passt damit gut zum Streaming-I/O-Modell von Go. Mit einem Scanner oder Decoder können Sie Datensätze einzeln lesen und verarbeiten, ohne die gesamte Datei in den Speicher zu laden. Zusammen mit den leichtgewichtigen Goroutines und Channels von Go lassen sich so nebenläufige JSONL-Pipelines aufbauen, die alle verfügbaren CPU-Kerne auslasten. Dieser Leitfaden zeigt Ihnen, wie Sie JSONL mit bufio.Scanner lesen, mit json.Decoder streamen, effizient schreiben, Datensätze nebenläufig verarbeiten und Fehler zuverlässig behandeln.

JSONL-Dateien mit bufio.Scanner lesen

Am einfachsten lesen Sie JSONL in Go mit bufio.Scanner. Er liest die Datei Zeile für Zeile ein; jede Zeile parsen Sie anschließend mit json.Unmarshal. Dabei behalten Sie die volle Kontrolle über die Puffergrößen und die Fehlerbehandlung.

Öffnen Sie die Datei, erstellen Sie einen Scanner und durchlaufen Sie die Datei Zeile für Zeile. Mit json.Unmarshal parsen Sie jede Zeile in eine Map oder ein Struct. Der Speicherbedarf richtet sich so nach der Größe eines einzelnen Datensatzes und nicht nach der gesamten Datei.

Dateien mit bufio.Scanner einlesen
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)


	// Puffer für Zeilen länger als 64KB vergrößern
	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))
}

Parsen Sie JSONL-Datensätze in produktivem Code in typisierte Go-Structs statt in generische Maps. Das sorgt für Typsicherheit zur Compile-Zeit, bessere Performance und übersichtlicheren Code. Mit json-Tags am Struct legen Sie fest, wie die Felder zugeordnet werden.

Datensätze in typisierte Structs parsen
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 mit json.Decoder

Für performantes Streaming liest json.Decoder direkt aus einem io.Reader, ohne die Daten vorher in Zeilen aufzuteilen. Der Decoder kümmert sich intern um die Pufferung. Er empfiehlt sich für große JSONL-Dateien oder Netzwerk-Streams, wenn möglichst wenige Speicherallokationen anfallen sollen.

Mit json.NewDecoder können Sie einen beliebigen io.Reader einbinden und JSON-Werte nacheinander dekodieren. Jeder Aufruf von Decode liest genau ein JSON-Objekt. Am Ende des Streams gibt Decode io.EOF zurück. Das ist effizienter als bufio.Scanner + json.Unmarshal, weil nicht jede Zeile in einen separaten Puffer kopiert werden muss.

Streaming mit 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++


		// Jeden Datensatz beim Dekodieren verarbeiten
		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)
	}
}

JSONL-Dateien in Go schreiben

JSONL in Go zu schreiben ist einfach: Serialisieren Sie jeden Datensatz mit json.Marshal, hängen Sie ein Zeilenumbruch-Byte an und schreiben Sie die Daten in eine Datei. Für optimale Performance schalten Sie einen bufio.Writer vor den Datei-Writer, um die Anzahl der Systemaufrufe zu reduzieren.

Serialisieren Sie jeden Datensatz mit json.Marshal zu JSON-Bytes und schreiben Sie diese mit einem abschließenden Zeilenumbruch in die Datei. Dieser einfache Ansatz eignet sich gut für kleine bis mittelgroße Dateien.

Dateien mit json.Marshal schreiben
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))
}

Für hohen Schreibdurchsatz kombinieren Sie json.NewEncoder mit einem bufio.Writer. Der Encoder fügt nach jedem Encode-Aufruf automatisch einen Zeilenumbruch hinzu. Der gepufferte Writer bündelt kleine Schreibvorgänge zu größeren Systemaufrufen. Rufen Sie immer Flush auf, bevor Sie die Datei schließen.

Gepuffertes Schreiben mit 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)


	// HTML-Escaping für sauberere Ausgabe deaktivieren
	encoder.SetEscapeHTML(false)


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


	// Gepufferte Daten in die Datei schreiben
	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)
	}
}

Nebenläufige JSONL-Verarbeitung mit Goroutines

Mit Goroutines und Channels lassen sich in Go leicht nebenläufige JSONL-Pipelines aufbauen. Beim Fan-out-Muster werden Datensätze aus einer Datei gelesen, auf mehrere Worker-Goroutines verteilt und die Ergebnisse über einen Channel gesammelt. Das eignet sich besonders für CPU-intensive Transformationen großer JSONL-Dateien.

Nebenläufige JSONL-Verarbeitung mit 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 {
	// CPU-intensive Arbeit simulieren
	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)


	// Worker starten
	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)
			}
		}()
	}


	// Results-Channel schließen wenn alle Worker fertig sind
	go func() {
		wg.Wait()
		close(results)
	}()


	// Datei lesen und Datensätze an Worker senden
	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)
	}()


	// Ergebnisse sammeln und schreiben
	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)
}

Dieses Fan-out-Muster verteilt die JSONL-Datensätze auf so viele Goroutines, wie CPU-Kerne vorhanden sind. Die gepufferten Channels verhindern, dass Goroutines beim Senden oder Empfangen blockieren. Die sync.WaitGroup stellt sicher, dass alle Worker ihre Arbeit beendet haben, bevor der Channel für die Ergebnisse geschlossen wird. Bei I/O-lastigen Aufgaben wie API-Aufrufen können Sie numWorkers höher als die Anzahl der CPU-Kerne setzen. Beachten Sie, dass bei nebenläufiger Verarbeitung die Reihenfolge der Ausgabe nicht garantiert ist.

Best Practices für die Fehlerbehandlung

Eine robuste JSONL-Verarbeitung in Go braucht eine sorgfältige Fehlerbehandlung. In der Praxis können JSONL-Dateien fehlerhafte Zeilen, Probleme mit der Zeichenkodierung oder unerwartet große Datensätze enthalten. Das folgende Muster erfasst Fehler mit der zugehörigen Zeilennummer, bietet ein konfigurierbares Verhalten zum Überspringen fehlerhafter Datensätze und gibt eine Zusammenfassung aus.

Best Practices für die Fehlerbehandlung
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()


		// Leere Zeilen überspringen
		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())
	}
}

Das Struct JSONLReader erfasst Zeilennummern, sammelt Parse-Fehler samt unverändertem Zeileninhalt und fasst die erfolgreich und fehlerhaft verarbeiteten Datensätze zusammen. Mit dem 10-MB-Puffer des Scanners lassen sich auch ungewöhnlich große Zeilen ohne Panic verarbeiten. Für den produktiven Einsatz können Sie den Reader etwa um eine Abbruchmöglichkeit über context.Context, eine Fehlerobergrenze zum Beenden der Verarbeitung oder strukturiertes Logging mit slog erweitern.

Go-Pakete für die JSONL-Verarbeitung

Die Standardbibliothek von Go enthält alle Bausteine, die Sie für die JSONL-Verarbeitung brauchen. Hier finden Sie die drei wichtigsten Ansätze und erfahren, wann sich welcher eignet.

bufio.Scanner

Flexibel

Der Reader aus der Standardbibliothek zum zeilenweisen Einlesen. Das eigentliche Parsen übernehmen Sie mit json.Unmarshal. Diese Kombination eignet sich besonders, wenn Sie Puffergrößen selbst festlegen, unverarbeitete Zeilen überspringen oder untersuchen möchten oder Zeilennummern für Fehlermeldungen benötigen. Die maximale Zeilenlänge richtet sich nach der konfigurierten Puffergröße.

json.Decoder

Empfohlen

Ein JSON-Decoder für Streaming, der direkt aus einem io.Reader liest. Er arbeitet effizienter als Scanner + Unmarshal, weil er das Kopieren von Daten vermeidet. Ideal für große Dateien und Netzwerk-Streams. Aufeinanderfolgende JSON-Werte verarbeitet er automatisch, ohne dass Sie die Daten ausdrücklich an Zeilenumbrüchen aufteilen müssen.

json.Encoder

Ausgabe

Ein JSON-Encoder für Streaming, der in einen io.Writer schreibt. Nach jedem Encode-Aufruf fügt er automatisch einen Zeilenumbruch hinzu und eignet sich damit ideal für die JSONL-Ausgabe. Kombinieren Sie ihn für hohen Schreibdurchsatz mit bufio.Writer. Über SetEscapeHTML und SetIndent lässt sich die Ausgabe konfigurieren.

JSONL-Dateien online bearbeiten

Zeigen Sie JSONL-Dateien bis zu 1 GB direkt im Browser an, validieren und konvertieren Sie sie. Ohne Upload, zu 100 % privat.

Häufig gestellte Fragen

Quellen