---
sidebar_label: "Руководство по Processor"
title: "Processor - CyberGo JSON | Руководство и выбор"
description: "Руководство по CyberGo JSON Processor: выбор между функциями пакета и Processor, PreParse, управление жизненным циклом и глобальный процессор."
sidebar_position: 3
---

# Руководство по 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` |
| **Сценарии применения** | простые операции, скрипты, редкие вызовы | частые операции, пользовательская конфигурация, серверная часть |

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

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

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

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

```go
// Функция пакета — всегда использует конфигурацию по умолчанию
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` выполняет парсинг один раз, а последующие запросы переиспользуют результат:

```go
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")
```

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

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

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

```go
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](../extensions/hooks).

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

## Что дальше

- [Синтаксис выражений пути](./path-syntax) — полный синтаксис запросов по пути
- [Processor API](../api-reference/processor/) — полный справочник методов
- [Оптимизация производительности](../advanced/performance) — глубокая настройка производительности
- [Шпаргалка](./cheatsheet) — быстрый справочник по API