Autor: Jerry Fan

JSONL w Go: bufio, json.Decoder i współbieżność

Kompletny przewodnik po pracy z plikami JSONL (JSON Lines) w Go. Dowiedz się, jak odczytywać, zapisywać i przetwarzać dane JSONL strumieniowo oraz współbieżnie, korzystając z pakietów bufio i encoding/json z biblioteki standardowej oraz z goroutines.

Dlaczego warto przetwarzać JSONL w Go?

Go świetnie nadaje się do przetwarzania plików JSONL, zwłaszcza gdy liczą się wydajność i współbieżność. Biblioteka standardowa zapewnia wszystko, czego potrzebujesz: bufio do wydajnych operacji wejścia/wyjścia wiersz po wierszu, encoding/json do parsowania i serializacji oraz goroutines do przetwarzania równoległego. Nie potrzebujesz żadnych zewnętrznych zależności. Ponieważ Go jest językiem kompilowanym, Twój potok przetwarzania JSONL będzie działać znacznie szybciej niż równoważne skrypty w Pythonie czy Node.js — często przetwarzając miliony wierszy na sekundę nawet na niezbyt wydajnym sprzęcie.

W formacie JSONL (JSON Lines) każdy wiersz zawiera jeden obiekt JSON, co dobrze pasuje do strumieniowego modelu wejścia/wyjścia w Go. Zamiast wczytywać cały plik do pamięci, możesz odczytywać i przetwarzać rekordy pojedynczo za pomocą skanera lub dekodera. Lekkie goroutines i kanały pozwalają przy tym budować współbieżne potoki przetwarzania JSONL, które w pełni wykorzystują wszystkie dostępne rdzenie procesora. W tym przewodniku dowiesz się, jak odczytywać JSONL za pomocą bufio.Scanner, przetwarzać dane strumieniowo z json.Decoder, wydajnie zapisywać JSONL, przetwarzać rekordy współbieżnie i zadbać o niezawodną obsługę błędów.

Odczyt plików JSONL za pomocą bufio.Scanner

Najprostszy sposób odczytu JSONL w Go to użycie bufio.Scanner. Skaner odczytuje plik wiersz po wierszu, a każdy wiersz parsujesz za pomocą json.Unmarshal. Masz dzięki temu pełną kontrolę nad rozmiarem bufora i obsługą błędów.

Otwórz plik, utwórz skaner i przejdź po kolejnych wierszach. Każdy wiersz sparsuj za pomocą json.Unmarshal do mapy lub struktury. Dzięki temu zużycie pamięci zależy od rozmiaru pojedynczego rekordu, a nie całego pliku.

Prosty odczyt za pomocą 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)


	// Zwieksz bufor dla linii dluzszych niz 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("pomijanie nieprawidlowego JSON: %v", err)
			continue
		}
		records = append(records, record)
	}


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


	fmt.Printf("Zaladowano %d rekordow\n", len(records))
}

W kodzie produkcyjnym parsuj rekordy JSONL do struktur Go o określonych typach pól zamiast do map ogólnego przeznaczenia. Zyskujesz kontrolę typów na etapie kompilacji, lepszą wydajność i czytelniejszy kod. Dodaj do definicji struktury tagi json, aby określić mapowanie pól.

Parsowanie do struktur o określonych typach pól
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("otwarcie pliku: %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("linia %d: %w", lineNum, err)
		}
		users = append(users, u)
	}


	if err := scanner.Err(); err != nil {
		return nil, fmt.Errorf("blad skanera: %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)
	}
}

Przetwarzanie strumieniowe za pomocą json.Decoder

json.Decoder umożliwia wydajne przetwarzanie strumieniowe: odczytuje dane bezpośrednio z io.Reader, bez wcześniejszego dzielenia ich na wiersze. Sam obsługuje buforowanie. To zalecane rozwiązanie dla dużych plików JSONL i strumieni sieciowych, gdy zależy Ci na ograniczeniu alokacji pamięci do minimum.

json.NewDecoder przyjmuje dowolny io.Reader i tworzy dekoder, który dekoduje kolejne wartości JSON. Każde wywołanie Decode odczytuje dokładnie jeden obiekt JSON. Po osiągnięciu końca strumienia zwraca io.EOF. To rozwiązanie jest wydajniejsze niż bufio.Scanner + json.Unmarshal, ponieważ nie wymaga kopiowania każdego wiersza do osobnego bufora.

Przetwarzanie strumieniowe za pomocą 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("otwarcie: %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("dekodowanie rekordu %d: %w", count+1, err)
		}
		count++


		// Przetwarzaj kazdy rekord w momencie dekodowania
		if entry.Level == "ERROR" {
			fmt.Printf("[%s] %s: %s\n",
				entry.Timestamp, entry.Service, entry.Message)
		}
	}


	fmt.Printf("Przetworzono %d wpisow logu\n", count)
	return nil
}


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

Zapis plików JSONL w Go

Zapis JSONL w Go jest prosty: serializujesz każdy rekord za pomocą json.Marshal, dodajesz bajt znaku nowego wiersza i zapisujesz dane do pliku. Aby uzyskać najlepszą wydajność, użyj bufio.Writer jako bufora zapisu do pliku — ograniczysz w ten sposób liczbę wywołań systemowych.

Użyj json.Marshal, aby zserializować każdy rekord do bajtów w formacie JSON, a następnie zapisz je, dodając na końcu znak nowego wiersza. To proste podejście dobrze sprawdza się w przypadku małych i średnich plików.

Prosty zapis za pomocą 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("pomijanie bledu marshal: %v", err)
			continue
		}
		data = append(data, '\n')
		if _, err := file.Write(data); err != nil {
			log.Fatal(err)
		}
	}


	fmt.Printf("Zapisano %d rekordow do products.jsonl\n", len(products))
}

Aby uzyskać dużą przepustowość zapisu, użyj json.NewEncoder w połączeniu z bufio.Writer. Enkoder automatycznie dodaje znak nowego wiersza po każdym wywołaniu Encode, a bufor zapisu łączy małe operacje zapisu w większe, ograniczając liczbę wywołań systemowych. Przed zamknięciem pliku zawsze wywołuj Flush.

Zapis z buforowaniem za pomocą 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("tworzenie pliku: %w", err)
	}
	defer file.Close()


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


	// Wylacz escapowanie HTML dla czystszego wyjscia
	encoder.SetEscapeHTML(false)


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


	// Oproznij buforowane dane do pliku
	if err := writer.Flush(); err != nil {
		return fmt.Errorf("oproznij: %w", err)
	}


	fmt.Printf("Zapisano %d zdarzen do %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)
	}
}

Współbieżne przetwarzanie JSONL za pomocą goroutines

Goroutines i kanały w Go ułatwiają budowanie współbieżnych potoków przetwarzania JSONL. We wzorcu fan-out rekordy są odczytywane z pliku, rozdzielane między wiele goroutines roboczych, a wyniki trafiają do wspólnego kanału. To idealne rozwiązanie do przekształcania dużych plików JSONL, gdy wydajność ogranicza moc obliczeniowa procesora.

Współbieżne przetwarzanie JSONL za pomocą 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 {
	// Symulacja pracy intensywnie obciazajacej procesor
	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)


	// Uruchom workery
	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)
			}
		}()
	}


	// Zamknij kanal wynikow gdy wszystkie workery skoncza
	go func() {
		wg.Wait()
		close(results)
	}()


	// Czytaj plik i wysylaj rekordy do workerow
	go func() {
		scanner := bufio.NewScanner(file)
		for scanner.Scan() {
			var r Record
			if err := json.Unmarshal(scanner.Bytes(), &r); err != nil {
				log.Printf("pomijanie nieprawidlowej linii: %v", err)
				continue
			}
			jobs <- r
		}
		close(jobs)
	}()


	// Zbierz i zapisz wyniki
	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("blad kodowania: %v", err)
		}
		count++
	}
	writer.Flush()


	fmt.Printf("Przetworzono %d rekordow za pomoca %d workerow\n", count, numWorkers)
}

W tym wariancie wzorca fan-out rekordy JSONL są rozdzielane między goroutines, których liczba odpowiada liczbie rdzeni procesora. Buforowane kanały zapobiegają blokowaniu goroutines przy wysyłaniu i odbieraniu danych. sync.WaitGroup zapewnia, że wszystkie goroutines robocze zakończą pracę przed zamknięciem kanału wyników. W przypadku zadań, których wydajność ograniczają operacje wejścia/wyjścia, takich jak wywołania API, możesz ustawić numWorkers na wartość większą niż liczba rdzeni. Pamiętaj, że przy przetwarzaniu współbieżnym kolejność wyników nie jest gwarantowana.

Dobre praktyki obsługi błędów

Niezawodne przetwarzanie JSONL w Go wymaga starannej obsługi błędów. W praktyce pliki JSONL mogą zawierać niepoprawne wiersze, błędy kodowania lub nieoczekiwanie duże rekordy. Ten wzorzec pozwala rejestrować błędy z podziałem na wiersze, konfigurować pomijanie błędnych rekordów i generować podsumowanie przetwarzania.

Dobre praktyki obsługi błędów
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("linia %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 musi byc *[]map[string]any")
	}


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


		// Pomin puste linie
		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(
		"Linie: %d | Sukces: %d | Pominiete: %d | Bledy: %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("Blad parsowania w %s", e.Error())
	}
}

Struktura JSONLReader śledzi numery wierszy, zbiera błędy parsowania wraz z oryginalną treścią wierszy i podsumowuje liczbę poprawnie oraz błędnie przetworzonych rekordów. Bufor skanera o rozmiarze 10MB pozwala obsługiwać wyjątkowo długie wiersze bez wywoływania paniki. W kodzie produkcyjnym możesz rozbudować to rozwiązanie o anulowanie przetwarzania za pomocą context.Context, limit błędów, po którego osiągnięciu przetwarzanie zostaje przerwane, lub logowanie strukturalne za pomocą slog.

Pakiety Go do przetwarzania JSONL

Biblioteka standardowa Go zawiera wszystko, czego potrzebujesz do przetwarzania JSONL. Poniżej znajdziesz trzy podstawowe podejścia wraz ze wskazówkami, kiedy wybrać każde z nich.

bufio.Scanner

Elastyczny

Standardowy skaner odczytujący dane wiersz po wierszu. Używaj go z json.Unmarshal, aby samodzielnie parsować każdy wiersz. Sprawdza się najlepiej, gdy potrzebujesz kontroli nad rozmiarem bufora, chcesz pomijać wiersze lub sprawdzać ich oryginalną treść albo potrzebujesz numerów wierszy do raportowania błędów. Obsługuje wiersze o długości do ustawionego limitu bufora.

json.Decoder

Zalecany

Strumieniowy dekoder JSON odczytujący dane bezpośrednio z io.Reader. Jest wydajniejszy niż Scanner + Unmarshal, ponieważ nie wymaga kopiowania danych. Idealny do dużych plików i strumieni sieciowych. Automatycznie obsługuje następujące po sobie wartości JSON, bez konieczności osobnego dzielenia danych na wiersze.

json.Encoder

Zapis

Strumieniowy enkoder JSON zapisujący dane do io.Writer. Automatycznie dodaje znak nowego wiersza po każdym wywołaniu Encode, dzięki czemu świetnie nadaje się do zapisu JSONL. Połącz go z bufio.Writer, aby uzyskać dużą przepustowość zapisu. Umożliwia konfigurację za pomocą SetEscapeHTML i SetIndent.

Pracuj z plikami JSONL online

Przeglądaj, waliduj i konwertuj pliki JSONL o rozmiarze do 1GB bezpośrednio w przeglądarce. Bez przesyłania plików na serwer, z zachowaniem 100% prywatności.

Najczęściej zadawane pytania

Źródła