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.
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.
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.
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.
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.
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.
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.
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
FlexibleEl 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
RecomendadoDecodificador 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
EscrituraCodificador 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.
Prueba nuestras herramientas gratuitas para JSONL
¿Prefieres no escribir código? Usa nuestras herramientas gratuitas en línea para ver, validar y convertir archivos JSONL directamente en tu navegador.
Estrategias para procesar gigabytes de datos JSONL: lectura en streaming, gestión de memoria, división de archivos, compresión y herramientas online.
Domina las buenas prácticas de JSONL: formato, coherencia del esquema, gestión de errores, optimización del rendimiento y organización de archivos. Evita los errores habituales con ejemplos prácticos.
Valida archivos JSONL línea por línea. Detecta al instante errores de sintaxis, problemas de codificación y fallos de formato.
Aprende a transmitir datos JSONL en tiempo real con Node.js, Python, Server-Sent Events y WebSockets. Crea pipelines de streaming para logs, métricas y flujos de datos en directo.
Guía completa para trabajar con archivos JSONL en Rust. Aprende a usar serde_json y BufReader, procesar datos en paralelo con rayon, realizar operaciones de entrada/salida asíncronas con tokio y aplicar patrones robustos de gestión de errores.