JSONL in Go: bufio, json.Decoder en concurrency
Een complete handleiding voor het werken met JSONL-bestanden (JSON Lines) in Go. Leer hoe je JSONL-data leest, schrijft, streamt en gelijktijdig verwerkt met bufio en encoding/json uit de standaardbibliotheek en met goroutines.
Waarom Go voor JSONL?
Go is een uitstekende keuze voor het verwerken van JSONL-bestanden, zeker als prestaties en concurrency belangrijk zijn. De standaardbibliotheek biedt alles wat je nodig hebt: bufio voor efficiënte I/O per regel, encoding/json voor parsing en serialisatie, en goroutines voor parallelle verwerking. Je hebt geen externe dependencies nodig. Doordat Go gecompileerd is, draait je JSONL-pipeline aanzienlijk sneller dan vergelijkbare Python- of Node.js-scripts. Zelfs op bescheiden hardware kun je vaak miljoenen regels per seconde verwerken.
JSONL (JSON Lines) slaat één JSON-object per regel op en sluit daarmee goed aan op het streaming I/O-model van Go. Met een scanner of decoder kun je records één voor één lezen en verwerken, zonder het hele bestand in het geheugen te laden. Met de lichtgewicht goroutines en channels van Go bouw je JSONL-pipelines die records gelijktijdig verwerken en alle beschikbare CPU-cores volledig benutten. In deze handleiding leer je hoe je JSONL leest met bufio.Scanner, streamt met json.Decoder, efficiënt schrijft, gelijktijdig verwerkt en hoe je fouten robuust afhandelt.
JSONL-bestanden lezen met bufio.Scanner
De eenvoudigste manier om JSONL in Go te lezen is met bufio.Scanner. De scanner leest een bestand regel voor regel; elke regel parse je vervolgens met json.Unmarshal. Zo houd je volledige controle over de buffergrootte en de foutafhandeling.
Open het bestand, maak een scanner aan en loop regel voor regel door het bestand. Met json.Unmarshal parse je elke regel naar een map of struct. Het geheugengebruik hangt zo af van de grootte van één record, in plaats van het hele bestand.
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)
// Vergroot de buffer voor regels langer dan 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("ongeldige JSON overgeslagen: %v", err)
continue
}
records = append(records, record)
}
if err := scanner.Err(); err != nil {
log.Fatal(err)
}
fmt.Printf("%d records geladen\n", len(records))
}Parse JSONL-records in productiecode naar getypeerde Go-structs in plaats van generieke maps. Dat levert typeveiligheid tijdens het compileren, betere prestaties en duidelijkere code op. Gebruik json-tags in je struct om te bepalen hoe JSON-velden aan structvelden worden gekoppeld.
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("bestand openen: %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("regel %d: %w", lineNum, err)
}
users = append(users, u)
}
if err := scanner.Err(); err != nil {
return nil, fmt.Errorf("scannerfout: %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)
}
}Streamen met json.Decoder
Voor snelle streaming leest json.Decoder rechtstreeks uit een io.Reader, zonder de invoer eerst in regels te splitsen. De decoder regelt de buffering zelf. Deze aanpak is aan te raden voor grote JSONL-bestanden of netwerkstreams waarbij je het aantal geheugenallocaties wilt beperken.
Met json.NewDecoder maak je een decoder voor elke willekeurige io.Reader. Die decodeert de JSON-waarden één voor één. Elke aanroep van Decode leest precies één JSON-object. Aan het einde van de stream geeft de decoder io.EOF terug. Dit is efficiënter dan bufio.Scanner + json.Unmarshal, omdat niet elke regel naar een aparte buffer wordt gekopieerd.
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("openen: %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("decoderen record %d: %w", count+1, err)
}
count++
// Verwerk elk record terwijl het gedecodeerd wordt
if entry.Level == "ERROR" {
fmt.Printf("[%s] %s: %s\n",
entry.Timestamp, entry.Service, entry.Message)
}
}
fmt.Printf("%d logvermeldingen verwerkt\n", count)
return nil
}
func main() {
if err := processJSONLStream("logs.jsonl"); err != nil {
log.Fatal(err)
}
}JSONL-bestanden schrijven in Go
JSONL schrijven in Go is eenvoudig: serialiseer elk record met json.Marshal, voeg een newline-byte toe en schrijf het resultaat naar een bestand. Gebruik voor de beste prestaties een bufio.Writer rond de bestandswriter. Zo beperk je het aantal systeemaanroepen.
Gebruik json.Marshal om elk record te serialiseren naar JSON-bytes en schrijf die vervolgens weg, gevolgd door een newline. Deze eenvoudige aanpak werkt goed voor kleine tot middelgrote bestanden.
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("marshal-fout overgeslagen: %v", err)
continue
}
data = append(data, '\n')
if _, err := file.Write(data); err != nil {
log.Fatal(err)
}
}
fmt.Printf("%d records geschreven naar products.jsonl\n", len(products))
}Gebruik json.NewEncoder met een bufio.Writer om grote hoeveelheden data snel weg te schrijven. De encoder voegt na elke Encode-aanroep automatisch een newline toe. De gebufferde writer bundelt kleine schrijfbewerkingen tot grotere systeemaanroepen. Roep altijd Flush aan voordat je het bestand sluit.
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("bestand aanmaken: %w", err)
}
defer file.Close()
writer := bufio.NewWriter(file)
encoder := json.NewEncoder(writer)
// Schakel HTML-escaping uit voor schonere output
encoder.SetEscapeHTML(false)
for i, event := range events {
if err := encoder.Encode(event); err != nil {
return fmt.Errorf("event %d encoderen: %w", i, err)
}
}
// Flush gebufferde data naar bestand
if err := writer.Flush(); err != nil {
return fmt.Errorf("flush: %w", err)
}
fmt.Printf("%d events geschreven naar %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)
}
}JSONL gelijktijdig verwerken met goroutines
Met de goroutines en channels van Go bouw je eenvoudig JSONL-pipelines die records gelijktijdig verwerken. Het fan-out-patroon leest records uit een bestand, verdeelt ze over meerdere worker-goroutines en verzamelt de resultaten via een channel. Dit is ideaal voor CPU-intensieve transformaties van grote JSONL-bestanden.
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 {
// Simuleer CPU-intensief werk
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)
// Start 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)
}
}()
}
// Sluit results-channel wanneer alle workers klaar zijn
go func() {
wg.Wait()
close(results)
}()
// Lees bestand en stuur records naar workers
go func() {
scanner := bufio.NewScanner(file)
for scanner.Scan() {
var r Record
if err := json.Unmarshal(scanner.Bytes(), &r); err != nil {
log.Printf("ongeldige regel overgeslagen: %v", err)
continue
}
jobs <- r
}
close(jobs)
}()
// Verzamel en schrijf resultaten
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("coderingsfout: %v", err)
}
count++
}
writer.Flush()
fmt.Printf("%d records verwerkt met %d workers\n", count, numWorkers)
}Dit fan-out-patroon verdeelt JSONL-records over evenveel goroutines als er CPU-cores zijn. De gebufferde channels voorkomen dat goroutines blokkeren bij het verzenden of ontvangen. De sync.WaitGroup zorgt ervoor dat alle workers klaar zijn voordat het results-channel wordt gesloten. Voor workloads die vooral op I/O wachten, zoals API-aanroepen, kun je numWorkers hoger instellen dan het aantal CPU-cores. Houd er rekening mee dat de volgorde van de uitvoer bij gelijktijdige verwerking niet gegarandeerd is.
Best practices voor foutafhandeling
Om JSONL in Go robuust te verwerken, moet je fouten zorgvuldig afhandelen. In de praktijk kunnen JSONL-bestanden ongeldige regels, problemen met de tekencodering of onverwacht grote records bevatten. Met dit patroon houd je fouten per regel bij, kun je instellen of regels met fouten worden overgeslagen en krijg je een overzicht van de resultaten.
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("regel %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 moet *[]map[string]any zijn")
}
for r.scanner.Scan() {
r.lineNum++
line := r.scanner.Bytes()
// Sla lege regels over
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(
"Regels: %d | Geslaagd: %d | Overgeslagen: %d | Fouten: %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("Parseerfout op %s", e.Error())
}
}Deze JSONLReader-struct houdt regelnummers bij, verzamelt parsefouten met de oorspronkelijke inhoud van de regel en geeft een overzicht van geslaagde en mislukte verwerkingen. De scannerbuffer van 10MB kan ook uitzonderlijk lange regels aan zonder een panic te veroorzaken. Voor productiegebruik kun je dit uitbreiden met ondersteuning voor context.Context om de verwerking te annuleren, een maximumaantal fouten waarna de verwerking stopt, of gestructureerde logging met slog.
Go-packages voor JSONL-verwerking
De standaardbibliotheek van Go bevat alle bouwstenen die je nodig hebt om JSONL te verwerken. Hieronder vind je de drie belangrijkste opties en lees je wanneer je welke gebruikt.
bufio.Scanner
FlexibelDe standaardreader om bestanden regel voor regel te lezen. Gebruik json.Unmarshal om de regels expliciet te parsen. Een goede keuze als je de buffergrootte zelf wilt bepalen, onbewerkte regels wilt overslaan of inspecteren, of regelnummers nodig hebt voor foutmeldingen. Kan regels lezen tot de ingestelde buffergrootte.
json.Decoder
AanbevolenEen streaming JSON-decoder die rechtstreeks uit een io.Reader leest. Efficiënter dan Scanner + Unmarshal, doordat er geen data wordt gekopieerd. Ideaal voor grote bestanden en netwerkstreams. Verwerkt opeenvolgende JSON-waarden automatisch, zonder de invoer expliciet op newlines te hoeven splitsen.
json.Encoder
SchrijvenEen streaming JSON-encoder die naar een io.Writer schrijft. Voegt na elke Encode-aanroep automatisch een newline toe en is daardoor ideaal voor JSONL-uitvoer. Combineer de encoder met bufio.Writer om grote hoeveelheden data snel weg te schrijven. Je kunt de uitvoer instellen met SetEscapeHTML en SetIndent.
Probeer onze gratis JSONL-tools
Liever geen code schrijven? Met onze gratis online tools kun je JSONL-bestanden direct in je browser bekijken, valideren en converteren.
Strategieën om gigabytes aan JSONL-data te verwerken. Met aandacht voor lezen via streaming, geheugenbeheer, het splitsen van bestanden, compressie en online tools.
Leer de best practices voor JSONL toepassen: opmaak, consistente schema’s, foutafhandeling, prestatieoptimalisatie en het organiseren van bestanden. Vermijd veelvoorkomende valkuilen aan de hand van praktische voorbeelden.
Valideer JSONL-bestanden regel voor regel. Spoor syntaxfouten, tekencoderingsproblemen en fouten in het formaat direct op.
Leer hoe je JSONL-data in realtime streamt met Node.js, Python, Server-Sent Events en WebSockets. Bouw streamingpipelines voor logs, metrics en live datafeeds.
Een complete handleiding om met JSONL-bestanden in Rust te werken. Leer werken met serde_json en BufReader, parallelle verwerking met rayon, asynchrone I/O met tokio en patronen voor robuuste foutafhandeling.