Функции обработки JSONL

Пакет json предоставляет функции обработки JSONL (JSON Lines), поддерживающие парсинг, потоковое чтение, преобразование и запись данных JSON с разделением строками.

Функции обработки JSONL

JSONL (JSON Lines) — формат с разделением строками, где каждая строка представляет отдельный JSON-объект.

ParseJSONL

Сигнатура: func ParseJSONL(data []byte, cfg ...Config) ([]any, error)

Парсит данные JSONL (JSON с разделением строками).

Параметры

Имя	Тип	Обязательный	Описание
`data`	`[]byte`	Да	Байтовые данные JSONL
`cfg`	`Config`	Нет	Необязательная конфигурация

package main

import (
    "fmt"
    "github.com/cybergodev/json"
)

func main() {
    jsonl := `{"name":"Alice"}
{"name":"Bob"}
{"name":"Charlie"}`
    results, err := json.ParseJSONL([]byte(jsonl))
    if err != nil {
        panic(err)
    }
    for i, r := range results {
        fmt.Printf("[%d] %v\n", i, r)
    }
}

StreamLinesInto

Сигнатура: func StreamLinesInto[T any](reader io.Reader, fn func(lineNum int, data T) error, cfg ...Config) ([]T, error)

Потоково читает данные JSONL из io.Reader и обрабатывает каждую строку через функцию обратного вызова. Это рекомендуемый обобщённый способ обработки JSONL.

Параметры

Имя	Тип	Обязательный	Описание
`reader`	`io.Reader`	Да	Источник данных
`fn`	`func(lineNum int, data T) error`	Да	Обратный вызов обработки (получает номер строки и данные)
`cfg`	`Config`	Нет	Необязательная конфигурация

Возвращаемое значение

Тип	Описание
`[]T`	Срез всех обработанных результатов
`error`	Информация об ошибке

package main

import (
    "fmt"
    "strings"
    "github.com/cybergodev/json"
)

type User struct {
    Name string `json:"name"`
}

func main() {
    src := `{"name":"Alice"}
{"name":"Bob"}`

    // Базовое использование
    results, err := json.StreamLinesInto[User](strings.NewReader(src), func(lineNum int, user User) error {
        fmt.Printf("Строка %d: пользователь %s\n", lineNum, user.Name)
        return nil // Возврат ошибки прервет обработку
    })
    if err != nil {
        panic(err)
    }
    fmt.Printf("Всего обработано %d записей\n", len(results))
}

ToJSONL

Сигнатура: func ToJSONL(data []any, cfg ...Config) ([]byte, error)

Преобразует срез данных в формат JSONL.

Параметры

Имя	Тип	Обязательный	Описание
`data`	`[]any`	Да	Срез данных
`cfg`	`Config`	Нет	Необязательная конфигурация

package main

import (
    "fmt"
    "github.com/cybergodev/json"
)

func main() {
    items := []any{
        map[string]any{"name": "Alice"},
        map[string]any{"name": "Bob"},
    }
    jsonl, err := json.ToJSONL(items)
    if err != nil {
        panic(err)
    }
    fmt.Println(string(jsonl))
    // {"name":"Alice"}
    // {"name":"Bob"}
}

ToJSONLString

Сигнатура: func ToJSONLString(data []any, cfg ...Config) (string, error)

Преобразует срез данных в строку JSONL.

Параметры

Имя	Тип	Обязательный	Описание
`data`	`[]any`	Да	Срез данных
`cfg`	`Config`	Нет	Необязательная конфигурация

package main

import (
    "fmt"
    "github.com/cybergodev/json"
)

func main() {
    items := []any{
        map[string]any{"name": "Alice"},
        map[string]any{"name": "Bob"},
    }
    jsonlStr, err := json.ToJSONLString(items)
    if err != nil {
        panic(err)
    }
    fmt.Println(jsonlStr)
}

Функции потоковой обработки JSONL (на уровне пакета)

Пакет json предоставляет пакетные удобные функции потоковой обработки JSONL; их сигнатуры совпадают с соответствующими методами Processor, и в конце они дополнительно принимают необязательный параметр cfg ...Config; внутри используется глобальный Processor, кэшируемый по cfg, поэтому вручную создавать экземпляр не нужно — подходит для одноразовых сценариев обработки. При необходимости многократной обработки или совместного использования одной конфигурации рекомендуется создать независимый Processor через json.New(cfg).

Полное описание и примеры см. в Руководстве по потоковой обработке JSONL и Методах JSONL уровня Processor.

StreamJSONL

Сигнатура: func StreamJSONL(reader io.Reader, fn func(lineNum int, item *IterableValue) error, cfg ...Config) error

Потоково построчно обрабатывает JSONL; каждая строка парсится в IterableValue перед вызовом обратного вызова.

StreamJSONLParallel

Сигнатура: func StreamJSONLParallel(reader io.Reader, workers int, fn func(lineNum int, item *IterableValue) error, cfg ...Config) error

Обрабатывает JSONL с использованием workers параллельных горутин (для сценариев с интенсивной нагрузкой на CPU).

StreamJSONLParallelWithContext

Сигнатура: func StreamJSONLParallelWithContext(ctx context.Context, reader io.Reader, workers int, fn func(lineNum int, item *IterableValue) error, cfg ...Config) error

Параллельная обработка JSONL с поддержкой отмены/тайм-аута контекста.

StreamJSONLChunked

Сигнатура: func StreamJSONLChunked(reader io.Reader, chunkSize int, fn func(chunk []*IterableValue) error, cfg ...Config) error

Поблочно обрабатывает по chunkSize; каждая партия передаётся в обратный вызов как []*IterableValue.

ForeachJSONL

Сигнатура: func ForeachJSONL(reader io.Reader, fn func(lineNum int, item *IterableValue) error, cfg ...Config) error

Обходит JSONL (псевдоним с поведением, идентичным StreamJSONL).

MapJSONL

Сигнатура: func MapJSONL(reader io.Reader, fn func(lineNum int, item *IterableValue) (any, error), cfg ...Config) ([]any, error)

Отображает каждую строку в новое значение, возвращает срез результатов.

ReduceJSONL

Сигнатура: func ReduceJSONL(reader io.Reader, initial any, fn func(acc any, item *IterableValue) any, cfg ...Config) (any, error)

Сводит JSONL к одному значению; initial — начальное значение аккумулятора.

FilterJSONL

Сигнатура: func FilterJSONL(reader io.Reader, predicate func(item *IterableValue) bool, cfg ...Config) ([]*IterableValue, error)

Фильтрует по предикату, возвращает срез совпадающих элементов.

StreamJSONLFile

Сигнатура: func StreamJSONLFile(filename string, fn func(lineNum int, item *IterableValue) error, cfg ...Config) error

Напрямую потоково обрабатывает весь JSONL-файл.

CollectJSONL

Сигнатура: func CollectJSONL(reader io.Reader, cfg ...Config) ([]*IterableValue, error)

Читает все строки JSONL и собирает их в срез (примечание: полная загрузка в память; для больших файлов рекомендуется использовать StreamJSONL).

FirstJSONL

Сигнатура: func FirstJSONL(reader io.Reader, predicate func(item *IterableValue) bool, cfg ...Config) (*IterableValue, bool, error)

Возвращает первый элемент, удовлетворяющий предикату; второе возвращаемое значение указывает, найден ли элемент.

Конфигурация JSONL

WARNING

Отдельная структура JSONLConfig и функция DefaultJSONLConfig() удалены. Конфигурация JSONL теперь интегрирована в поля JSONL* структуры Config.

Конфигурация JSONL через Config

cfg := json.DefaultConfig()

// Конфигурация JSONL
cfg.JSONLBufferSize    = 64 * 1024    // Размер буфера чтения (по умолчанию: 64KB)
cfg.JSONLMaxLineSize   = 1024 * 1024  // Максимальный размер одной строки (по умолчанию: 1MB)
cfg.JSONLSkipEmpty     = true         // Пропускать пустые строки (по умолчанию: true)
cfg.JSONLSkipComments  = false        // Пропускать строки с комментариями (по умолчанию: false)
cfg.JSONLContinueOnErr = false        // Продолжать при ошибке (по умолчанию: false)
cfg.JSONLWorkers       = 4            // Количество параллельных горутин (по умолчанию: 4)
cfg.JSONLChunkSize     = 1000         // Строк на пакет обработки (по умолчанию: 1000)
cfg.JSONLMaxMemory     = 100 * 1024 * 1024 // Максимальная память (по умолчанию: 100MB)

processor, err := json.New(cfg)

Подробнее см. Конфигурация Config

JSONL-писатель

NewJSONLWriter

Сигнатура: func NewJSONLWriter(writer io.Writer, cfg ...Config) *JSONLWriter

Создаёт JSONL-писатель.

package main

import (
    "os"
    "github.com/cybergodev/json"
)

func main() {
    file, err := os.Create("output.jsonl")
    if err != nil {
        panic(err)
    }
    defer file.Close()
    jw := json.NewJSONLWriter(file)
    jw.Write(map[string]any{"id": 1, "name": "Alice"})
    jw.Write(map[string]any{"id": 2, "name": "Bob"})
}

Методы JSONLWriter

Метод	Сигнатура	Описание
`Write`	`(data any) error`	Записать одну строку
`WriteAll`	`(data []any) error`	Записать несколько строк
`WriteRaw`	`(line []byte) error`	Записать сырую байтовую строку
`Err`	`() error`	Возвращает накопленную ошибку
`Stats`	`() JSONLStats`	Возвращает статистику записи

jw := json.NewJSONLWriter(file)

items := []any{
    map[string]any{"id": 1, "name": "Alice"},
    map[string]any{"id": 2, "name": "Bob"},
}
if err := jw.WriteAll(items); err != nil {
    log.Fatal(err)
}

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

Связанные разделы

Функции файловых операций - Файловые операции LoadFromFile, SaveToFile и др.
Методы Processor JSONL - Подробное описание методов JSONL уровня Processor
Потоковая обработка - Подробное описание потокового процессора

Функции обработки JSONL ​