Функции запросов и получения

Функции запросов и получения пакета json поддерживают выражения пути, типобезопасное получение и массовые операции.

Функции запроса по пути

Get

Сигнатура: func Get(jsonStr, path string, cfg ...Config) (any, error)

Получает значение любого типа по пути.

Параметры

Имя	Тип	Обязательный	Описание
jsonStr	string	Да	Строка JSON
path	string	Да	Выражение пути
cfg	Config	Нет	Необязательная конфигурация

Пример

package main

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

func main() {
    val, err := json.Get(`{"items":[{"name":"test"}]}`, "items[0].name")
    if err != nil {
        panic(err)
    }
    fmt.Println(val) // Вывод: test
}

GetWithContext

Сигнатура: func GetWithContext(ctx context.Context, jsonStr, path string, cfg ...Config) (any, error)

Получение по пути с контекстом. Поддерживает тайм-аут и отмену операции. Контекстно-зависимая версия Get.

Примечание

Контекст проверяется до и после операции, но не во время парсинга/навигации. Для больших JSON-документов операция может не реагировать на отмену во время выполнения.

package main

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

func main() {
    ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
    defer cancel()

    val, err := json.GetWithContext(ctx, `{"user":{"name":"Alice"}}`, "user.name")
    if err != nil {
        panic(err)
    }
    fmt.Println(val) // Вывод: Alice
}

Типобезопасные функции получения

Типобезопасные функции получения предоставляют возврат к нулевому значению через вариативный параметр defaultValue. Если путь не существует, значение равно null или преобразование типа не удалось, возвращается defaultValue (если не указан — нулевое значение соответствующего типа).

GetString

Сигнатура: func GetString(jsonStr, path string, defaultValue ...string) string

Получает строковое значение по пути.

package main

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

func main() {
    jsonStr := `{"user": {"name": "CyberGo"}}`

    name := json.GetString(jsonStr, "user.name")
    fmt.Println(name) // Вывод: CyberGo

    // Несуществующий путь возвращает нулевое значение (пустую строку) или пользовательское значение по умолчанию
    nickname := json.GetString(jsonStr, "user.nickname", "Неизвестно")
    fmt.Println(nickname) // Вывод: Неизвестно
}

GetInt

Сигнатура: func GetInt(jsonStr, path string, defaultValue ...int) int

Получает целочисленное значение по пути.

package main

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

func main() {
    jsonStr := `{"pagination": {"count": 42}, "timeout": 30}`

    count := json.GetInt(jsonStr, "pagination.count")
    fmt.Println(count) // Вывод: 42

    timeout := json.GetInt(jsonStr, "timeout")
    fmt.Println(timeout) // Вывод: 30

    // Несуществующий путь возвращает пользовательское значение по умолчанию
    page := json.GetInt(jsonStr, "pagination.page", 1)
    fmt.Println(page) // Вывод: 1
}

GetFloat

Сигнатура: func GetFloat(jsonStr, path string, defaultValue ...float64) float64

Получает число с плавающей точкой по пути.

package main

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

func main() {
    jsonStr := `{"item": {"price": 19.99}, "rate": 0.85}`

    price := json.GetFloat(jsonStr, "item.price")
    fmt.Println(price) // Вывод: 19.99

    rate := json.GetFloat(jsonStr, "rate")
    fmt.Println(rate) // Вывод: 0.85

    // Несуществующий путь возвращает пользовательское значение по умолчанию
    discount := json.GetFloat(jsonStr, "item.discount", 0.0)
    fmt.Println(discount) // Вывод: 0
}

GetBool

Сигнатура: func GetBool(jsonStr, path string, defaultValue ...bool) bool

Получает логическое значение по пути.

package main

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

func main() {
    jsonStr := `{"feature": {"enabled": true}, "debug": false}`

    enabled := json.GetBool(jsonStr, "feature.enabled")
    fmt.Println(enabled) // Вывод: true

    debug := json.GetBool(jsonStr, "debug")
    fmt.Println(debug) // Вывод: false

    // Несуществующий путь возвращает пользовательское значение по умолчанию
    verbose := json.GetBool(jsonStr, "feature.verbose", false)
    fmt.Println(verbose) // Вывод: false
}

GetArray

Сигнатура: func GetArray(jsonStr, path string, defaultValue ...[]any) []any

Получает массив по пути.

package main

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

func main() {
    jsonStr := `{"items": ["apple", "banana", "cherry"]}`

    items := json.GetArray(jsonStr, "items")
    for i, item := range items {
        fmt.Printf("[%d] %v\n", i, item)
    }

    // Несуществующий путь возвращает пользовательское значение по умолчанию
    empty := json.GetArray(jsonStr, "tags", []any{"default"})
    fmt.Println(empty) // Вывод: [default]
}

GetObject

Сигнатура: func GetObject(jsonStr, path string, defaultValue ...map[string]any) map[string]any

Получает объект по пути.

package main

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

func main() {
    jsonStr := `{"user": {"profile": {"name": "CyberGo", "level": 5}}}`

    profile := json.GetObject(jsonStr, "user.profile")
    fmt.Println(profile) // map[level:5 name:CyberGo]

    // Несуществующий путь возвращает пользовательское значение по умолчанию
    settings := json.GetObject(jsonStr, "user.settings", map[string]any{"theme": "dark"})
    fmt.Println(settings) // Вывод: map[theme:dark]
}

Обобщённые функции получения

GetTyped[T]

Сигнатура: func GetTyped[T any](jsonStr, path string, defaultValue ...T) T

Обобщённая функция получения, поддерживающая пользовательские типы. Если путь не существует, значение равно null или преобразование типа не удалось, возвращается defaultValue (если не указан — нулевое значение типа T).

Пояснение к именованию: GetTyped[T] семантически эквивалентен GetAs[T], что означает получение и преобразование JSON-значения в указанный тип T.

package main

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

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

func main() {
    jsonStr := `{"user": {"name": "CyberGo", "age": 30}}`

    // Получение типизированной структуры
    user := json.GetTyped[User](jsonStr, "user")
    fmt.Printf("Name: %s, Age: %d\n", user.Name, user.Age)

    // Примеры встроенных типов
    name := json.GetTyped[string](jsonStr, "user.name")
    fmt.Println(name) // Вывод: CyberGo

    age := json.GetTyped[int](jsonStr, "user.age")
    fmt.Println(age) // Вывод: 30

    // Несуществующий путь возвращает пользовательское значение по умолчанию
    email := json.GetTyped[string](jsonStr, "user.email", "[email protected]")
    fmt.Println(email) // Вывод: [email protected]
}

Функции безопасного получения

SafeGet (функция пакета)

Сигнатура: func SafeGet(jsonStr, path string, cfg ...Config) AccessResult

Выполняет типобезопасное получение, возвращает AccessResult с методами преобразования типов (AsString, AsInt, AsFloat64, AsBool).

package main

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

func main() {
    jsonStr := `{"user": {"name": "CyberGo", "age": 30}}`

    result := json.SafeGet(jsonStr, "user.age")
    if result.Exists {
        age, _ := result.AsInt()
        fmt.Println(age) // Вывод: 30
    }

    nameResult := json.SafeGet(jsonStr, "user.name")
    name, _ := nameResult.AsString()
    fmt.Println(name) // Вывод: CyberGo
}

SafeGet (метод Processor)

Сигнатура: func (p *Processor) SafeGet(jsonStr, path string, cfg ...Config) AccessResult

Выполняет типобезопасное получение через экземпляр Processor.

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

jsonStr := `{"user": {"name": "CyberGo", "age": 30}}`

result := p.SafeGet(jsonStr, "user.age")
if result.Exists {
    age, _ := result.AsInt()
    fmt.Println(age) // Вывод: 30
}

Расширенные методы Processor

Следующие методы предоставляются как функции уровня пакета и как методы Processor.

GetMultiple (функция пакета)

Сигнатура: func GetMultiple(jsonStr string, paths []string, cfg ...Config) (map[string]any, error)

Массовое получение значений по нескольким путям (функция уровня пакета, не требует создания Processor).

jsonStr := `{"user": {"name": "CyberGo", "age": 30, "email": "[email protected]"}}`

paths := []string{"user.name", "user.age", "user.email"}
values, err := json.GetMultiple(jsonStr, paths)
if err != nil {
    panic(err)
}
fmt.Println(values["user.name"]) // Вывод: CyberGo

Processor.GetMultiple

Сигнатура: func (p *Processor) GetMultiple(jsonStr string, paths []string, cfg ...Config) (map[string]any, error)

Массовое получение значений по нескольким путям.

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

jsonStr := `{"user": {"name": "CyberGo", "age": 30, "email": "[email protected]"}}`

paths := []string{"user.name", "user.age", "user.email"}
values, err := p.GetMultiple(jsonStr, paths)
if err != nil {
    panic(err)
}
fmt.Println(values["user.name"]) // Вывод: CyberGo

Связанные типы

AccessResult

Поля структуры AccessResult, используемой в SafeGet:

Поле	Тип	Описание
Value	any	Полученное значение
Exists	bool	Существует ли путь
Type	string	Обнаруженный тип значения

Методы: Ok() · Unwrap() · UnwrapOr() · AsString() · AsStringConverted() · AsInt() · AsFloat64() · AsBool()

Подробнее см. Тип AccessResult.

Result[T]

Поля обобщённой структуры Result[T]:

Поле	Тип	Описание
Value	T	Полученное значение
Exists	bool	Найдено ли значение
Error	error	Информация об ошибке

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

• Функции парсинга и валидации - Операции парсинга/валидации Parse, Valid, ValidateSchema и др.
• Функции пакетных операций - Пакетная обработка ProcessBatch
• Функции модификации - Операции Set, Delete и др.
• Кодирование и вывод - Операции сериализации Marshal, Unmarshal и др.
• Вспомогательные функции - Утилиты CompareJSON, MergeJSON и др.
• Параметры конфигурации - Подробное описание Config