Руководство по Processor

Это руководство поможет понять, когда и как использовать Processor и какие преимущества он даёт по сравнению с функциями уровня пакета.

Функции пакета vs Processor

CyberGo JSON предоставляет два стиля API:

Аспект	Функции уровня пакета	Processor
Типичный вызов	json.GetString(data, "name")	p.GetString(data, "name")
Создание	не требуется, прямой вызов	p, err := json.New()
Конфигурация	передаётся при каждом вызове cfg ...Config	настраивается при создании, затем переиспользуется
Кэш	общий глобальный кэш	независимый кэш, контролируемый и очищаемый
Управление ресурсами	автоматическое (глобальный процессор)	ручное Close()
Система хуков	не поддерживается	поддерживается AddHook
Предпарсинг	не поддерживается	поддерживается PreParse + GetFromParsed
Сценарии применения	простые операции, скрипты, редкие вызовы	частые операции, пользовательская конфигурация, серверная часть

Быстрый выбор

• Функции пакета: периодические операции с JSON, отсутствие необходимости управлять жизненным циклом, быстрые скрипты
• Processor: требуется пользовательская конфигурация, частые запросы к одним данным, нужны хуки/аудит

Когда использовать Processor

Сценарий 1: пользовательская конфигурация

Функции уровня пакета используют конфигурацию по умолчанию. Если нужен безопасный режим, пользовательский кодировщик или хуки, используйте Processor:

// Функция пакета — всегда использует конфигурацию по умолчанию
val := json.GetString(data, "name")

// Processor — позволяет настроить конфигурацию
cfg := json.SecurityConfig() // безопасный режим
p, err := json.New(cfg)
if err != nil {
    panic(err)
}
defer p.Close()

// Все последующие операции используют безопасную конфигурацию
val, err := p.Get(data, "name")

Сценарий 2: частые запросы к одним данным (оптимизация PreParse)

При многократных запросах к одному JSON PreParse выполняет парсинг один раз, а последующие запросы переиспользуют результат:

p, err := json.New()
if err != nil {
    panic(err)
}
defer p.Close()

// Однократный парсинг
parsed, err := p.PreParse(largeJSON)
if err != nil {
    panic(err)
}

// Множественные запросы — переиспользование результата, без повторного парсинга
name, _ := p.GetFromParsed(parsed, "user.name")
email, _ := p.GetFromParsed(parsed, "user.email")
tags, _ := p.GetFromParsed(parsed, "tags")

Сравнение производительности

• Функция пакета GetString: каждый вызов парсит JSON (есть кэш, но попадания зависят от сценария)
• PreParse + GetFromParsed: парсинг один раз, N запросов выполняют только навигацию, ноль повторных парсингов

Сценарий 3: хуки и аудит

При необходимости логирования, мониторинга производительности или валидации входных данных Processor поддерживает систему хуков:

p, err := json.New()
if err != nil {
    panic(err)
}
defer p.Close()

// Добавление хука логирования
p.AddHook(json.LoggingHook(slog.Default()))
// Добавление хука замера времени
p.AddHook(json.TimingHook(&metricsRecorder))

// Все операции автоматически запускают хуки
result, err := p.Set(data, "user.name", "Alice")

Подробнее см. Система хуков Hook.

Управление жизненным циклом

Processor удерживает ресурсы (кэш, горутины), после использования его необходимо закрыть:

p, err := json.New()
if err != nil {
    panic(err)
}
defer p.Close() // обеспечивает освобождение ресурсов

// Использование Processor...
result, err := p.GetString(data, "name")

Последствия забытого Close

• Память кэша не освобождается
• Утечка фоновых горутин
• В сценариях высокой нагрузки возможно истощение ресурсов

Проверка состояния

if p.IsClosed() {
    // Processor закрыт, использовать больше нельзя
}

Глобальный процессор

Функции уровня пакета (Get, Set, Marshal и др.) внутри используют глобальный процессор. Его также можно заменить:

// Создание процессора с пользовательской конфигурацией
cfg := json.SecurityConfig()
p, err := json.New(cfg)
if err != nil {
    panic(err)
}

// Установка в качестве глобального процессора
json.SetGlobalProcessor(p)

// Теперь все функции уровня пакета используют безопасную конфигурацию
val := json.GetString(data, "name")

// Очистка при выходе из приложения
defer json.ShutdownGlobalProcessor()

Сценарии применения

• Единая глобальная политика безопасности
• Глобальное действие пользовательского кодировщика
• Замена конфигурации по умолчанию без повсеместной передачи Config

Дерево решений

Необходимо работать с JSON?
├── Периодическое использование, утилиты, скрипты
│   └── → функции пакета json.GetString / json.Set / json.Marshal
├── Нужна пользовательская конфигурация (безопасность/кодирование/хуки)
│   └── → Processor json.New(cfg)
├── Множественные запросы к одному JSON
│   └── → Processor + PreParse
├── Нужен аудит/мониторинг/логирование
│   └── → Processor + AddHook
└── Единая глобальная конфигурация
    └── → SetGlobalProcessor

Что дальше

• Синтаксис выражений пути — полный синтаксис запросов по пути
• Processor API — полный справочник методов
• Оптимизация производительности — глубокая настройка производительности
• Шпаргалка — быстрый справочник по API