Константы и ошибки

Переменные ошибок

Основные ошибки

var (
    // Базовые ошибки
    ErrInvalidJSON     = errors.New("invalid JSON format")
    ErrPathNotFound    = errors.New("path not found")
    ErrTypeMismatch    = errors.New("type mismatch")
    ErrInvalidPath     = errors.New("invalid path format")
    ErrProcessorClosed = errors.New("processor is closed")

    // Ошибки ограничений
    ErrSizeLimit        = errors.New("size limit exceeded")
    ErrDepthLimit       = errors.New("depth limit exceeded")
    ErrConcurrencyLimit = errors.New("concurrency limit exceeded") // возвращается, когда управляемые операции (Get/Set/Delete и др.) достигают MaxConcurrency

    // Ошибки безопасности и валидации
    ErrSecurityViolation = errors.New("security violation detected")
    ErrUnsupportedPath   = errors.New("unsupported path operation")

    // Ошибки ресурсов и производительности (обе Deprecated: в настоящее время не возвращаются ни одной операцией, сохранены для будущего использования)
    ErrOperationTimeout  = errors.New("operation timeout")
    ErrResourceExhausted = errors.New("system resources exhausted")
)

Проверка ошибок

Используйте errors.Is для проверки типа ошибки:

val, err := json.Get(data, "user.name")
if err != nil {
    if errors.Is(err, json.ErrPathNotFound) {
        // Путь не найден
        fmt.Println("Путь не найден")
    } else if errors.Is(err, json.ErrTypeMismatch) {
        // Несовпадение типов
        fmt.Println("Несовпадение типов")
    } else if errors.Is(err, json.ErrInvalidJSON) {
        // Ошибка формата JSON
        fmt.Println("Недопустимый JSON")
    }
}

Тип JsonsError

Определение структуры

type JsonsError struct {
    Op      string `json:"op"`      // Название операции
    Path    string `json:"path"`    // Путь, где произошла ошибка
    Message string `json:"message"` // Читаемое сообщение об ошибке
    Err     error  `json:"err"`     // Базовая ошибка
}

Методы

func (e *JsonsError) Error() string
func (e *JsonsError) Unwrap() error
func (e *JsonsError) Is(target error) bool

Пример использования

val, err := json.Get(data, "complex.path[0]")
if err != nil {
    var jsonErr *json.JsonsError
    if errors.As(err, &jsonErr) {
        fmt.Printf("Операция: %s\n", jsonErr.Op)
        fmt.Printf("Путь: %s\n", jsonErr.Path)
        fmt.Printf("Сообщение: %s\n", jsonErr.Message)
        if jsonErr.Err != nil {
            fmt.Printf("Причина: %v\n", jsonErr.Err)
        }
    }
}

Вспомогательные функции ошибок

Помимо описанных выше типов ошибок, библиотека предоставляет две вспомогательные функции обработки ошибок (подробности см. в разделе Вспомогательные утилиты):

Функция	Сигнатура	Описание
SafeError	func SafeError(err error) string	Возвращает безопасное для клиента сообщение об ошибке, опуская внутренние детали, такие как имена путей (CWE-209)
RedactedPath	func RedactedPath(path string) string	Возвращает путь с маскированием (непустые пути заменяются на "***") для использования в логах и ответах об ошибках

Предустановки конфигурации

Константы значений по умолчанию

const (
    // Ограничения размеров
    DefaultMaxJSONSize     = 100 * 1024 * 1024  // 100MB
    DefaultMaxNestingDepth = 200
    DefaultMaxPathDepth    = 50
    DefaultMaxDepth        = 100                 // Глубина вложенности кодирования/декодирования по умолчанию (Config.MaxDepth)
    DefaultMaxConcurrency  = 50

    // Ограничения безопасности
    DefaultMaxSecuritySize   = 10 * 1024 * 1024  // 10MB
    DefaultMaxObjectKeys     = 100000
    DefaultMaxArrayElements  = 100000
    DefaultMaxBatchSize      = 2000
    DefaultParallelThreshold = 10

    // Кэш
    DefaultCacheTTL = 5 * time.Minute
)

Функции предустановок конфигурации

DefaultConfig

Сигнатура: func DefaultConfig() Config

Возвращает конфигурацию по умолчанию.

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

SecurityConfig

Сигнатура: func SecurityConfig() Config

Возвращает конфигурацию безопасности, подходящую для обработки недоверенных входных данных.

// Рекомендуется для:
// - Публичных API и веб-сервисов
// - Пользовательских данных
// - Внешних вебхуков
// - Точек аутентификации
// - Обработки финансовых данных
cfg := json.SecurityConfig()
processor, err := json.New(cfg)
if err != nil {
    panic(err)
}
defer processor.Close()

Особенности конфигурации безопасности:

• Полная проверка безопасности
• Строгий режим
• Консервативные ограничительные значения
• Включённый кэш

PrettyConfig

Сигнатура: func PrettyConfig() Config

Возвращает конфигурацию для форматированного вывода.

result, err := json.EncodeWithConfig(data, json.PrettyConfig())

Константы режимов слияния

// MergeMode - тип режима слияния (экспортируется из внутреннего пакета)
type MergeMode = internal.MergeMode

const (
    // MergeUnion - объединяющее слияние (по умолчанию)
    // Объекты: объединяются все ключи, при конфликте берётся перезаписывающее значение
    // Массивы: объединяются все элементы с удалением дубликатов
    MergeUnion = internal.MergeUnion

    // MergeIntersection - пересечение
    // Объекты: сохраняются только общие ключи
    // Массивы: сохраняются только общие элементы
    MergeIntersection = internal.MergeIntersection

    // MergeDifference - разность
    // Объекты: сохраняются только ключи, существующие в базовом, но отсутствующие в перезаписывающем
    // Массивы: сохраняются только элементы, существующие в базовом, но отсутствующие в перезаписывающем
    MergeDifference = internal.MergeDifference
)

Тип сегмента пути

PathSegment - тип сегмента пути, экспортируемый из внутреннего пакета internal, для представления компонентов разобранного пути.

type PathSegment = internal.PathSegment

Псевдоним внутренней реализации

PathSegment — это псевдоним типа internal.PathSegment. Его конкретные поля, типы полей (например, PathSegmentType, PathSegmentFlags) и методы принадлежат пакету internal, не экспортируются как публичный API и могут меняться между версиями — не полагайтесь на его внутреннюю структуру напрямую в бизнес-коде.

• При реализации пользовательского синтаксиса путей возвращайте []PathSegment через метод ParsePath интерфейса PathParser.
• Для предкомпилированных путей используйте Processor.CompilePath, который возвращает *CompiledPath.

Уровни шаблонов безопасности

type PatternLevel int

const (
    // PatternLevelCritical - критический риск, всегда блокирует операцию
    PatternLevelCritical PatternLevel = iota

    // PatternLevelWarning - уровень предупреждения, блокирует в строгом режиме
    PatternLevelWarning

    // PatternLevelInfo - информационный уровень, только запись в лог
    PatternLevelInfo
)

Структура DangerousPattern

type DangerousPattern struct {
    Pattern string       // Подстрока для обнаружения
    Name    string       // Читаемое описание риска безопасности
    Level   PatternLevel // Уровень обработки
}

Лучшие практики обработки ошибок

Использование errors.Is для проверки типа

result, err := json.Get(data, path)
if errors.Is(err, json.ErrPathNotFound) {
    return defaultValue
}
if errors.Is(err, json.ErrTypeMismatch) {
    return defaultValue
}

Использование errors.As для получения подробностей

var jsonErr *json.JsonsError
if errors.As(err, &jsonErr) {
    log.Printf("Операция %s failed по пути %s: %s",
        jsonErr.Op, jsonErr.Path, jsonErr.Message)
}

Обёртывание ошибок

val := json.GetString(data, path)
if val == "" {
    return fmt.Errorf("получение конфигурации %s вернуло пустое значение", path)
}

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

• Обработка ошибок - Руководство по продвинутой обработке ошибок
• Config - Параметры конфигурации
• Обзор безопасности - Лучшие практики безопасности