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.
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.
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.
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.
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.
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.
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.
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ívelO 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
RecomendadoDecodificador 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
EscritaCodificador 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.
Experimente nossas ferramentas gratuitas para JSONL
Não quer escrever código? Use nossas ferramentas online gratuitas para visualizar, validar e converter arquivos JSONL diretamente no navegador.
Estratégias para processar gigabytes de dados JSONL: leitura por streaming, gerenciamento de memória, divisão de arquivos, compressão e ferramentas online.
Domine as boas práticas de JSONL para formatação, consistência de schema, tratamento de erros, otimização de desempenho e organização de arquivos. Evite problemas comuns com exemplos práticos.
Valide arquivos JSONL linha por linha. Detecte erros de sintaxe, problemas de codificação e de formato instantaneamente.
Aprenda a transmitir dados JSONL em tempo real usando Node.js, Python, Server-Sent Events e WebSockets. Crie pipelines de streaming para logs, métricas e feeds de dados em tempo real.
Guia completo para trabalhar com arquivos JSONL em Rust. Aprenda a usar serde_json e BufReader, fazer processamento paralelo com rayon e E/S assíncrona com tokio, além de aplicar padrões robustos de tratamento de erros.