- Startseite
- Anleitung
- JSONL in Go: bufio, json.Decoder und Nebenläufigkeit
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.
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.
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.
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.
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.
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.
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.
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
FlexibelDer 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
EmpfohlenEin 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
AusgabeEin 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.
Probieren Sie unsere kostenlosen JSONL-Tools aus
Sie möchten keinen Code schreiben? Mit unseren kostenlosen Online-Tools können Sie JSONL-Dateien direkt im Browser anzeigen, validieren und konvertieren.
Strategien für JSONL-Daten im Gigabyte-Bereich: Lesen per Streaming, Speicherverwaltung, Aufteilen von Dateien, Komprimierung und Online-Tools.
Bewährte Vorgehensweisen für JSONL: Formatierung, einheitliche Schemas, Fehlerbehandlung, Performance-Optimierung und Dateiorganisation. Praktische Beispiele helfen Ihnen, typische Fallstricke zu vermeiden.
Validieren Sie JSONL-Dateien Zeile für Zeile und erkennen Sie Syntaxfehler, Probleme mit der Zeichenkodierung und Formatfehler sofort.
Erfahren Sie, wie Sie JSONL-Daten mit Node.js, Python, Server-Sent Events und WebSockets in Echtzeit streamen. Erstellen Sie Streaming-Pipelines für Logs, Metriken und Live-Datenfeeds.
Ein umfassender Leitfaden für JSONL-Dateien in Rust. Lernen Sie den Umgang mit serde_json und BufReader, parallele Verarbeitung mit rayon, asynchrone Ein- und Ausgabe mit tokio und robuste Muster zur Fehlerbehandlung.