---
sidebar_label: "Обзор"
title: "JSON библиотека - CyberGo JSON | Быстрый Go"
description: "CyberGo JSON — быстрая потокобезопасная Go JSON-библиотека с JSONPath, потоковой обработкой, обобщёнными API и Schema, совместимая с encoding/json."
---

# Библиотека обработки JSON

`github.com/cybergodev/json` — высокопроизводительная, потокобезопасная библиотека Go для обработки JSON. Предоставляет богатый набор функций для работы с JSON, включая парсинг, запросы, модификацию, валидацию и форматирование, сохраняя 100% совместимость со стандартной библиотекой `encoding/json`.

## Основные возможности

- **100% совместимость с encoding/json** — бесшовная замена стандартной библиотеки без изменения существующего кода
- **Потокобезопасность** — все операции безопасны для параллельного выполнения в высоконагруженных сценариях
- **Запросы по пути** — поддержка выражений пути в стиле JSONPath, включая подстановочные знаки и срезы
- **Типобезопасное получение** — обобщённый API (`GetTyped[T]`) и методы типизированного получения (`SafeGet`)
- **Потоковая обработка** — поддержка потоковой обработки больших файлов и формата JSONL/NDJSON
- **Защита безопасности** — встроенная валидация входных данных, ограничение глубины, обнаружение опасных паттернов
- **Высокопроизводительное кэширование** — интеллектуальное кэширование, оптимизация предпарсинга, переиспользование объектов из пула
- **Расширяемость** — система хуков, пользовательские кодировщики, валидаторы

## Установка

```bash
go get github.com/cybergodev/json
```

## Быстрый старт за 30 секунд

```go
package main

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

func main() {
    data := `{"name": "CyberGo", "version": 1, "tags": ["json", "go"]}`

    // 1. Получение значения по пути
    name := json.GetString(data, "name")
    fmt.Println("Name:", name)

    // 2. Модификация значения
    updated, _ := json.Set(data, "version", 2)
    fmt.Println("Updated:", updated)

    // 3. Валидация
    if json.Valid([]byte(data)) {
        fmt.Println("Valid JSON")
    }

    // 4. Получение со значением по умолчанию
    desc := json.GetString(data, "description", "Описание по умолчанию")
    fmt.Println("Description:", desc)

    // 5. Декодирование в структуру
    type Config struct {
        Name    string   `json:"name"`
        Version int      `json:"version"`
        Tags    []string `json:"tags"`
    }
    var config Config
    json.Unmarshal([]byte(data), &config)
    fmt.Printf("Config: %+v\n", config)
}
```

## Обзор возможностей

### Операции с путями

| Функция | Метод | Описание |
|---------|-------|----------|
| Получение значения | `Get`, `GetString`, `GetInt`... | Поддержка вложенных путей и индексов массивов |
| Получение со значением по умолчанию | `GetString`, `GetInt` и др. | Передача параметра defaultValue |
| Установка значения | `Set` | Автоматическое создание несуществующих путей (Config.CreatePaths) |
| Удаление значения | `Delete` | Удаление значения по указанному пути |

### Кодирование и декодирование

| Функция | Метод | Описание |
|---------|-------|----------|
| Кодирование | `Marshal`, `MarshalIndent` | 100% совместимость с encoding/json |
| Декодирование | `Unmarshal`, `Parse`, `ParseAny` | Поддержка обобщений и типобезопасности |
| Форматирование | `Prettify`, `Compact` | Красивое форматирование / сжатие JSON |

### Расширенные возможности

| Функция | Метод/Тип | Описание |
|---------|-----------|----------|
| Обобщённый API | `GetTyped[T]` | Типобезопасное обобщённое получение |
| Предпарсинг | `Processor.PreParse`, `Processor.GetFromParsed` | Один парсинг — множество запросов |
| Безопасное получение | `SafeGet` → `AccessResult` | Цепочечные преобразования типов |
| Потоковая обработка | `NDJSONProcessor` | Потоковая обработка построчно, контролируемая память |
| Обработка JSONL | `StreamLinesInto[T]` | Конвейер логов/данных |
| Валидация Schema | `ValidateSchema` | Валидация по JSON Schema |

## Навигация по модулям

| Модуль | Описание |
|--------|----------|
| [Быстрый старт](./getting-started/) | Установка, базовое использование, ключевые концепции |
| [Синтаксис путей](./getting-started/path-syntax) | Запросы по пути, срезы, подстановочные знаки, извлечение полей |
| [Документация API](./api-reference/) | Полный справочник API |
| [Обработка больших файлов](./streaming/large-files) | Потоковая обработка, поблочное чтение/запись, оптимизация памяти |
| [Примеры использования](./examples/) | Практические примеры кода |
| [Продвинутые примеры](./examples/examples-advanced) | Пакетное кодирование, предпарсинг, система хуков |

## Характеристики производительности

- **Парсинг без копирования** — сокращение выделения памяти
- **Интеллектуальное кэширование** — автоматическое кэширование горячих путей, поддержка прогрева кэша
- **Пул объектов** — переиспользование промежуточных объектов, снижение нагрузки на GC
- **Параллельная потоковая обработка** — потоковая обработка JSONL поддерживает параллелизм с несколькими воркерами (`StreamJSONLParallel`)
- **Оптимизация предпарсинга** — однократный парсинг большого JSON для множества запросов

## Сравнение со стандартной библиотекой

| Возможность | encoding/json | cybergodev/json |
|-------------|---------------|-----------------|
| Базовое кодирование/декодирование | ✅ | ✅ 100% совместимость |
| Запросы по пути | ❌ | ✅ Синтаксис с точкой и скобками |
| Типобезопасное получение | ❌ | ✅ Обобщённый API |
| Потоковая обработка | Базовая | ✅ Расширенная |
| Поддержка JSONL | ❌ | ✅ Нативная поддержка |
| Валидация безопасности | ❌ | ✅ Встроенная защита |
| Система хуков | ❌ | ✅ Расширяемая |
| Оптимизация кэширования | ❌ | ✅ Интеллектуальное кэширование |

## Руководство быстрого выбора

| Сценарий | Рекомендуемое решение |
|----------|----------------------|
| Простой запрос | `GetString(data, "path")` |
| Со значением по умолчанию | `GetString(data, "path", "default")` |
| Типобезопасность | `GetTyped[User](data, "user")` |
| Частые запросы | `Processor` + `PreParse` |
| Большие файлы | `Processor.ForeachFile` |
| Недоверенный ввод | `SecurityConfig()` |

## Что дальше

- [Быстрый старт](./getting-started/) — начните за 5 минут
- [Синтаксис путей](./getting-started/path-syntax) — полное описание синтаксиса путей
- [Примеры использования](./examples/) — больше практических примеров