Por Jerry Fan

JSONL en Go: bufio, json.Decoder y concurrencia

Una guía completa para trabajar con archivos JSONL (JSON Lines) en Go. Aprende a leer, escribir y procesar datos JSONL en streaming y de forma concurrente con bufio y encoding/json de la biblioteca estándar y con goroutines.

¿Por qué usar Go para trabajar con JSONL?

Go es una excelente opción para procesar archivos JSONL, sobre todo cuando el rendimiento y la concurrencia son importantes. La biblioteca estándar ofrece todo lo que necesitas: bufio para leer y escribir de forma eficiente línea a línea, encoding/json para el análisis y la serialización, y goroutines para el procesamiento en paralelo. No necesitas dependencias de terceros. Al ser un lenguaje compilado, Go permite que tu pipeline de JSONL se ejecute mucho más rápido que los scripts equivalentes en Python o Node.js, a menudo procesando millones de líneas por segundo incluso con hardware modesto.

JSONL (JSON Lines) almacena un objeto JSON por línea, por lo que encaja de forma natural con el modelo de E/S en streaming de Go. En lugar de cargar todo el archivo en memoria, puedes leer y procesar los registros de uno en uno con un scanner o un decodificador. Si combinas este enfoque con las goroutines ligeras y los canales de Go, puedes crear pipelines concurrentes de JSONL que aprovechen al máximo todos los núcleos de CPU disponibles. En esta guía aprenderás a leer JSONL con bufio.Scanner, procesarlo en streaming con json.Decoder, escribirlo de forma eficiente, procesar registros de forma concurrente y gestionar los errores de manera robusta.

Lectura de archivos JSONL con bufio.Scanner

La forma más sencilla de leer JSONL en Go es usar bufio.Scanner para recorrer el archivo línea a línea y json.Unmarshal para analizar cada línea. Este enfoque te da un control total sobre el tamaño de los búferes y la gestión de errores.

Abre el archivo, crea un scanner y recórrelo línea a línea. Con json.Unmarshal, cada línea se convierte en un map o un struct. Así, el consumo de memoria es proporcional al tamaño de un único registro, no al del archivo completo.

Lectura básica 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)


	// Increase buffer for lines longer than 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))
}

En código de producción, deserializa los registros JSONL en structs tipados de Go en lugar de usar maps genéricos. Así obtienes seguridad de tipos en tiempo de compilación, mejor rendimiento y un código más claro. Define tu struct con etiquetas json para controlar la correspondencia entre los campos.

Deserialización en structs tipados
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

Para procesar datos en streaming con un alto rendimiento, json.Decoder lee directamente de un io.Reader sin un paso intermedio de separación en líneas. Gestiona el búfer internamente y es la opción recomendada para archivos JSONL grandes o flujos de datos de red cuando quieres reducir al mínimo las asignaciones de memoria.

json.NewDecoder toma cualquier io.Reader y decodifica los valores JSON de forma secuencial. Cada llamada a Decode lee exactamente un objeto JSON. Cuando el flujo de datos termina, devuelve io.EOF. Este enfoque es más eficiente que bufio.Scanner + json.Unmarshal porque evita copiar cada línea en un búfer independiente.

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


		// Process each record as it's decoded
		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)
	}
}

Escritura de archivos JSONL en Go

Escribir JSONL en Go es sencillo: serializa cada registro con json.Marshal, añade un byte de salto de línea y escribe el resultado en un archivo. Para obtener el mejor rendimiento, usa un bufio.Writer sobre el archivo de salida y reduce así las llamadas al sistema.

Usa json.Marshal para serializar cada registro como bytes JSON y escríbelos seguidos de un salto de línea. Es un enfoque sencillo que funciona bien con archivos pequeños y medianos.

Escritura básica 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))
}

Para escribir grandes volúmenes de datos con un alto rendimiento, usa json.NewEncoder con un bufio.Writer. El codificador añade automáticamente un salto de línea después de cada llamada a Encode, mientras que el escritor con búfer agrupa las escrituras pequeñas en llamadas al sistema de mayor tamaño. Llama siempre a Flush antes de cerrar el archivo.

Escritura con búfer mediante 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)


	// Disable HTML escaping for cleaner output
	encoder.SetEscapeHTML(false)


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


	// Flush buffered data to 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)
	}
}

Procesamiento concurrente de JSONL con goroutines

Las goroutines y los canales de Go facilitan la creación de pipelines concurrentes de JSONL. El patrón fan-out consiste en leer los registros de un archivo, repartirlos entre varias goroutines de trabajo y recoger los resultados a través de un canal. Es ideal para aplicar transformaciones que requieren mucho cálculo en archivos JSONL grandes.

Procesamiento concurrente de JSONL con 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 {
	// Simulate CPU-bound work
	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)
			}
		}()
	}


	// Close results channel when all workers finish
	go func() {
		wg.Wait()
		close(results)
	}()


	// Read file and send records to 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)
	}()


	// Collect and write results
	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)
}

Este patrón fan-out reparte los registros JSONL entre tantas goroutines como núcleos de CPU haya. Los canales con búfer evitan que las goroutines se bloqueen al enviar o recibir datos. sync.WaitGroup garantiza que todos los workers terminen antes de que se cierre el canal de resultados. Para cargas de trabajo limitadas por la E/S, como las llamadas a APIs, puedes aumentar numWorkers por encima del número de núcleos de CPU. Ten en cuenta que el procesamiento concurrente no garantiza el orden de salida.

Buenas prácticas para la gestión de errores

Para procesar JSONL de forma robusta en Go, debes gestionar los errores con cuidado. En la práctica, los archivos JSONL pueden contener líneas mal formadas, problemas de codificación o registros más grandes de lo esperado. Este patrón permite registrar los errores por línea, configurar si se omiten los registros con errores y generar un informe de resumen.

Buenas prácticas para la gestión de errores
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()


		// Skip empty lines
		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())
	}
}

El struct JSONLReader lleva la cuenta de los números de línea, recopila los errores de análisis junto con el contenido original y genera un resumen de los registros procesados correctamente y los fallidos. El búfer de 10MB del scanner permite manejar líneas inusualmente grandes sin provocar un panic. En producción, podrías ampliarlo para admitir la cancelación con context.Context, detener el procesamiento al superar un umbral de errores o generar logs estructurados con slog.

Paquetes de Go para procesar JSONL

La biblioteca estándar de Go incluye todo lo que necesitas para procesar JSONL. Estos son los tres enfoques principales y los casos en los que conviene usar cada uno.

bufio.Scanner

Flexible

El lector estándar para recorrer archivos línea a línea. Se combina con json.Unmarshal para analizar cada línea de forma explícita. Es la mejor opción cuando necesitas controlar el tamaño del búfer, omitir o inspeccionar las líneas originales, o incluir números de línea en los informes de errores. Admite líneas de hasta el tamaño de búfer que hayas configurado.

json.Decoder

Recomendado

Decodificador de JSON en streaming que lee directamente de un io.Reader. Es más eficiente que Scanner + Unmarshal porque evita copiar los datos. Resulta ideal para archivos grandes y flujos de datos de red. Procesa automáticamente los valores JSON consecutivos, sin necesidad de separarlos explícitamente por saltos de línea.

json.Encoder

Escritura

Codificador de JSON en streaming que escribe en un io.Writer. Añade automáticamente un salto de línea después de cada llamada a Encode, por lo que resulta ideal para generar JSONL. Combínalo con bufio.Writer para escribir con un alto rendimiento. Permite configurar la salida con SetEscapeHTML y SetIndent.

Trabaja con archivos JSONL en línea

Visualiza, valida y convierte archivos JSONL de hasta 1GB directamente en tu navegador. Sin subir archivos y con un 100% de privacidad.

Preguntas frecuentes

Referencias