Por Jerry Fan

JSONL em Go: bufio, json.Decoder e concorrência

Um guia completo para trabalhar com arquivos JSONL (JSON Lines) em Go. Aprenda a ler, escrever, trabalhar com streaming e processar dados JSONL de forma concorrente usando bufio e encoding/json da biblioteca padrão, além de goroutines.

Por que usar Go para trabalhar com JSONL?

Go é uma excelente escolha para processar arquivos JSONL, especialmente quando desempenho e concorrência são importantes. A biblioteca padrão oferece tudo de que você precisa: bufio para I/O eficiente linha a linha, encoding/json para parsing e serialização, e goroutines para processamento paralelo. Não é preciso usar dependências de terceiros. Por ser uma linguagem compilada, Go permite que seu pipeline JSONL seja significativamente mais rápido que scripts equivalentes em Python ou Node.js, muitas vezes processando milhões de linhas por segundo mesmo em hardware modesto.

JSONL (JSON Lines) armazena um objeto JSON por linha, o que se encaixa naturalmente no modelo de I/O em streaming do Go. Em vez de carregar o arquivo inteiro na memória, você pode ler e processar um registro por vez com um scanner ou decoder. Com as goroutines leves e os channels do Go, é possível criar pipelines JSONL concorrentes que utilizam toda a capacidade dos núcleos de CPU disponíveis. Neste guia, você vai aprender a ler JSONL com bufio.Scanner, trabalhar com streaming usando json.Decoder, escrever JSONL com eficiência, processar registros de forma concorrente e tratar erros de maneira robusta.

Leitura de arquivos JSONL com bufio.Scanner

A forma mais simples de ler JSONL em Go é usar bufio.Scanner. Ele lê o arquivo linha a linha, e você faz o parsing de cada uma com json.Unmarshal. Essa abordagem oferece controle total sobre o tamanho dos buffers e o tratamento de erros.

Abra o arquivo, crie um scanner e percorra as linhas. Cada linha é decodificada em um map ou uma struct com json.Unmarshal. Assim, o uso de memória fica proporcional ao tamanho de um único registro, e não ao do arquivo inteiro.

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


	// Aumenta o buffer para linhas maiores que 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("pulando JSON inválido: %v", err)
			continue
		}
		records = append(records, record)
	}


	if err := scanner.Err(); err != nil {
		log.Fatal(err)
	}


	fmt.Printf("Carregados %d registros\n", len(records))
}

Em código de produção, decodifique os registros JSONL em structs tipadas do Go em vez de maps genéricos. Isso garante segurança de tipos em tempo de compilação, melhora o desempenho e deixa o código mais claro. Use tags json na definição da struct para controlar o mapeamento dos campos.

Parsing com structs tipadas
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("abrir arquivo: %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("linha %d: %w", lineNum, err)
		}
		users = append(users, u)
	}


	if err := scanner.Err(); err != nil {
		return nil, fmt.Errorf("erro do scanner: %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 com json.Decoder

Para streaming de alto desempenho, json.Decoder lê diretamente de um io.Reader, sem uma etapa intermediária de separação das linhas. Ele gerencia o buffer internamente e é a opção recomendada para arquivos JSONL grandes ou streams de rede quando você precisa minimizar as alocações de memória.

json.NewDecoder recebe qualquer io.Reader e decodifica os valores JSON em sequência. Cada chamada a Decode lê exatamente um objeto JSON. Quando o stream chega ao fim, o decoder retorna io.EOF. Essa abordagem é mais eficiente que bufio.Scanner + json.Unmarshal porque evita copiar cada linha para um buffer separado.

Streaming com 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("abrir: %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("decodificar registro %d: %w", count+1, err)
		}
		count++


		// Processa cada registro conforme é decodificado
		if entry.Level == "ERROR" {
			fmt.Printf("[%s] %s: %s\n",
				entry.Timestamp, entry.Service, entry.Message)
		}
	}


	fmt.Printf("Processadas %d entradas de log\n", count)
	return nil
}


func main() {
	if err := processJSONLStream("logs.jsonl"); err != nil {
		log.Fatal(err)
	}
}

Escrita de arquivos JSONL em Go

Escrever JSONL em Go é simples: serialize cada registro com json.Marshal, acrescente um byte de quebra de linha e grave o resultado em um arquivo. Para obter o melhor desempenho, use um bufio.Writer sobre o writer do arquivo e reduza o número de chamadas de sistema.

Use json.Marshal para serializar cada registro em bytes no formato JSON e grave esses bytes seguidos de uma quebra de linha. Essa abordagem é simples e funciona bem para arquivos pequenos e médios.

Escrita básica com 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("pular erro de marshal: %v", err)
			continue
		}
		data = append(data, '\n')
		if _, err := file.Write(data); err != nil {
			log.Fatal(err)
		}
	}


	fmt.Printf("Escritos %d registros em products.jsonl\n", len(products))
}

Para gravar grandes volumes de dados com eficiência, use json.NewEncoder com um bufio.Writer. O encoder acrescenta uma quebra de linha automaticamente após cada chamada a Encode, enquanto o writer com buffer agrupa pequenas escritas em chamadas de sistema maiores. Sempre chame Flush antes de fechar o arquivo.

Escrita com buffer usando 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("criar arquivo: %w", err)
	}
	defer file.Close()


	writer := bufio.NewWriter(file)
	encoder := json.NewEncoder(writer)


	// Desabilita escape de HTML para saída mais limpa
	encoder.SetEscapeHTML(false)


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


	// Flush dos dados no buffer para o arquivo
	if err := writer.Flush(); err != nil {
		return fmt.Errorf("flush: %w", err)
	}


	fmt.Printf("Escritos %d eventos em %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)
	}
}

Processamento concorrente de JSONL com goroutines

As goroutines e os channels do Go facilitam a criação de pipelines JSONL concorrentes. No padrão fan-out, os registros são lidos de um arquivo, distribuídos entre várias goroutines que atuam como workers, e os resultados são coletados por um channel. Esse padrão é ideal para transformações que exigem uso intensivo de CPU em arquivos JSONL grandes.

Processamento concorrente de JSONL com 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 {
	// Simula trabalho intensivo de CPU
	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)


	// Inicia os 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)
			}
		}()
	}


	// Fecha o channel de resultados quando todos os workers terminarem
	go func() {
		wg.Wait()
		close(results)
	}()


	// Lê o arquivo e envia registros para os workers
	go func() {
		scanner := bufio.NewScanner(file)
		for scanner.Scan() {
			var r Record
			if err := json.Unmarshal(scanner.Bytes(), &r); err != nil {
				log.Printf("pulando linha inválida: %v", err)
				continue
			}
			jobs <- r
		}
		close(jobs)
	}()


	// Coleta e escreve os resultados
	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("erro ao codificar: %v", err)
		}
		count++
	}
	writer.Flush()


	fmt.Printf("Processados %d registros com %d workers\n", count, numWorkers)
}

Este padrão fan-out distribui os registros JSONL entre tantas goroutines quanto o número de núcleos de CPU. Os channels com buffer evitam que as goroutines bloqueiem ao enviar ou receber dados. O sync.WaitGroup garante que todos os workers terminem antes que o channel de resultados seja fechado. Para cargas de trabalho limitadas por I/O, como chamadas de API, você pode definir numWorkers acima do número de CPUs. No processamento concorrente, a ordem de saída não é garantida.

Boas práticas de tratamento de erros

Para processar JSONL de forma robusta em Go, é preciso cuidar do tratamento de erros. Na prática, arquivos JSONL podem conter linhas malformadas, problemas de codificação ou registros maiores que o esperado. Este padrão permite acompanhar os erros por linha, configurar se as linhas com erro devem ser ignoradas e gerar um resumo do processamento.

Boas práticas de tratamento de erros
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("linha %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 deve ser *[]map[string]any")
	}


	for r.scanner.Scan() {
		r.lineNum++
		line := r.scanner.Bytes()


		// Pula linhas vazias
		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(
		"Linhas: %d | Sucesso: %d | Puladas: %d | Erros: %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("Erro de parse em %s", e.Error())
	}
}

A struct JSONLReader acompanha os números das linhas, reúne os erros de parsing com o conteúdo bruto correspondente e gera um resumo dos registros processados com sucesso e das falhas. O buffer de 10MB do scanner permite lidar com linhas excepcionalmente grandes sem causar panic. Em produção, você pode ampliar essa implementação com suporte a context.Context para cancelamento, um limite máximo de erros para interromper o processamento ou logs estruturados com slog.

Pacotes Go para processamento de JSONL

A biblioteca padrão do Go oferece todos os recursos necessários para processar JSONL. Veja as três principais abordagens e quando usar cada uma.

bufio.Scanner

Flexível

O leitor padrão para leitura linha a linha. Use com json.Unmarshal para fazer o parsing explicitamente. É a melhor opção quando você precisa controlar o tamanho dos buffers, ignorar ou inspecionar o conteúdo bruto das linhas, ou incluir os números das linhas nos relatos de erro. Aceita linhas até o tamanho de buffer configurado.

json.Decoder

Recomendado

Decodificador JSON em streaming que lê diretamente de um io.Reader. É mais eficiente que Scanner + Unmarshal porque evita copiar dados. Ideal para arquivos grandes e streams de rede. Processa valores JSON consecutivos automaticamente, sem exigir uma etapa explícita de separação por quebras de linha.

json.Encoder

Escrita

Codificador JSON em streaming que escreve em um io.Writer. Acrescenta uma quebra de linha automaticamente após cada chamada a Encode, o que o torna ideal para gerar saída em JSONL. Use com bufio.Writer para gravar grandes volumes de dados com eficiência. Permite configurar SetEscapeHTML e SetIndent.

Trabalhe com arquivos JSONL online

Visualize, valide e converta arquivos JSONL de até 1GB diretamente no navegador. Sem precisar enviar arquivos, com 100% de privacidade.

Perguntas frequentes

Referências