Функции кодирования и вывода

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

Функции сериализации

Marshal

Сигнатура: func Marshal(value any, cfg ...Config) ([]byte, error)

Сериализация значения Go в срез байт JSON. 100% совместимость с encoding/json.Marshal: вызов json.Marshal(v) без cfg полностью идентичен стандартной библиотеке.

С помощью необязательного хвостового Config можно управлять поведением кодирования (отступы, обработка чисел и т.д.), образуя пару пакетный/экземплярный вместе с Processor.Marshal.

// Совместимость с encoding/json (без cfg)
data, err := json.Marshal(map[string]any{"name": "test"})
if err != nil {
    panic(err)
}
fmt.Println(string(data)) // {"name":"test"}

// С конфигурацией (неразрушающий необязательный параметр)
data, err = json.Marshal(value, json.PrettyConfig())

Unmarshal

Сигнатура: func Unmarshal(data []byte, value any, cfg ...Config) error

Десериализация среза байт JSON в значение Go. 100% совместимость с encoding/json.Unmarshal: вызов json.Unmarshal(data, &v) без cfg полностью идентичен стандартной библиотеке.

С помощью необязательного хвостового Config можно управлять ограничениями безопасности, сохранением чисел и т.д., образуя пару с Processor.Unmarshal.

var result struct {
    Name string `json:"name"`
}
// Совместимость с encoding/json (без cfg)
err := json.Unmarshal([]byte(`{"name":"test"}`), &result)

// С конфигурацией
err = json.Unmarshal(data, &v, json.SecurityConfig())

MarshalIndent

Сигнатура: func MarshalIndent(v any, prefix, indent string, cfg ...Config) ([]byte, error)

Сериализация с отступами. 100% совместимость с encoding/json.MarshalIndent: вызов json.MarshalIndent(v, prefix, indent) без cfg полностью идентичен стандартной библиотеке.

С помощью необязательного хвостового Config можно добавить конфигурацию; параметры prefix и indent переопределяют соответствующие поля Config.

// Совместимость с encoding/json (без cfg)
data, err := json.MarshalIndent(user, "", "  ")
if err != nil {
    panic(err)
}
fmt.Println(string(data))

// С конфигурацией
data, err = json.MarshalIndent(v, "", "  ", json.SecurityConfig())

Функции форматирования

Compact

Сигнатура: func Compact(dst *bytes.Buffer, src []byte, cfg ...Config) error

Сжатие JSON с удалением ненужных пробелов, результат записывается в dst. Совместимость с encoding/json.Compact.

var buf bytes.Buffer
err := json.Compact(&buf, []byte(`{"name": "test"}`))
if err != nil {
    panic(err)
}
fmt.Println(buf.String()) // {"name":"test"}

CompactString

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

Сжатие JSON в форме строкового ввода/вывода с удалением ненужных пробелов. Является пакетным зеркалом Processor.Compact и симметричен Prettify (зеркало Processor.Prettify).

Compact vs CompactString

Compact(dst, src): форма с буфером, совместимость с encoding/json.Compact, зеркало Processor.CompactBuffer
CompactString(s): строковая форма, зеркало Processor.Compact

compact, err := json.CompactString(`{
    "name": "Alice",
    "age": 30
}`)
// compact == `{"name":"Alice","age":30}`

// С конфигурацией (например, сохранение исходного формата чисел)
cfg := json.DefaultConfig()
cfg.PreserveNumbers = true
compact, err = json.CompactString(jsonStr, cfg)

Indent

Сигнатура: func Indent(dst *bytes.Buffer, src []byte, prefix, indent string, cfg ...Config) error

Форматирование JSON с добавлением отступов, результат записывается в dst. Совместимость с encoding/json.Indent.

var buf bytes.Buffer
err := json.Indent(&buf, []byte(`{"name": "test"}`), "", "  ")
if err != nil {
    panic(err)
}
fmt.Println(buf.String())
// {
//   "name": "test"
// }

HTMLEscape

Сигнатура: func HTMLEscape(dst *bytes.Buffer, src []byte, cfg ...Config)

HTML-экранирование содержимого JSON, замена специальных символов <, >, & (а также U+2028, U+2029) на соответствующие Unicode-escape последовательности, результат записывается в dst. Возвращаемого значения нет.

var buf bytes.Buffer
json.HTMLEscape(&buf, []byte(`{"html":"<script>alert(1)</script>"}`))
fmt.Println(buf.String())
// {"html":"\u003cscript\u003ealert(1)\u003c/script\u003e"}

Prettify

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

Форматирование JSON-строки с отступами по умолчанию, возвращает отформатированную строку.

pretty, err := json.Prettify(`{"name":"Alice","age":30}`)
if err != nil {
    panic(err)
}
fmt.Println(pretty)
// {
//   "name": "Alice",
//   "age": 30
// }

Функции настраиваемого кодирования

Encode

Сигнатура: func Encode(value any, cfg ...Config) (string, error)

Кодирование значения Go в JSON-строку с поддержкой необязательного параметра конфигурации.

Устарело

Encode функционально полностью идентичен EncodeWithConfig (оба делегируют одну реализацию). Используйте EncodeWithConfig или, при приемлемости вывода []byte, Marshal. Encode будет удалён в будущей мажорной версии.

result, err := json.Encode(user)
if err != nil {
    panic(err)
}
fmt.Println(result)

С конфигурацией

result, err := json.Encode(user, json.SecurityConfig())

EncodePretty

Сигнатура: func EncodePretty(value any, cfg ...Config) (string, error)

Кодирование значения Go в форматированную JSON-строку (с отступами) с поддержкой необязательного параметра конфигурации.

result, err := json.EncodePretty(user)
if err != nil {
    panic(err)
}
fmt.Println(result)

С конфигурацией

result, err := json.EncodePretty(user, json.PrettyConfig())

EncodeWithConfig

Сигнатура: func EncodeWithConfig(value any, cfg ...Config) (string, error)

Кодирование значения Go в JSON-строку с использованием указанной конфигурации. Подходит для сценариев, требующих точного контроля над поведением кодирования.

// С конфигурацией красивой печати
result, err := json.EncodeWithConfig(data, json.PrettyConfig())
if err != nil {
    panic(err)
}
fmt.Println(result)

Использование конфигурации безопасности

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

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

EncodeBatch

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

Пакетное кодирование пар ключ-значение в строку JSON-объекта.

result, err := json.EncodeBatch(map[string]any{
    "name":  "Alice",
    "age":   30,
    "email": "[email protected]",
})
if err != nil {
    panic(err)
}
fmt.Println(result) // {"age":30,"email":"[email protected]","name":"Alice"}

EncodeFields

Сигнатура: func EncodeFields(value any, fields []string, cfg ...Config) (string, error)

Кодирование только указанных полей для реализации фильтрации вывода.

user := struct {
    Name     string `json:"name"`
    Email    string `json:"email"`
    Password string `json:"password"`
}{
    Name: "Alice", Email: "[email protected]", Password: "secret",
}

// Вывод только открытых полей
result, err := json.EncodeFields(user, []string{"name", "email"})
if err != nil {
    panic(err)
}
fmt.Println(result) // {"name":"Alice","email":"[email protected]"}

EncodeStream

Сигнатура: func EncodeStream(values any, cfg ...Config) (string, error)

Кодирует несколько значений в поток JSON-массива (array stream). values обычно представляет собой срез или перечислимую коллекцию, выводя строку JSON-массива вида [v1,v2,...].

values := []map[string]any{
    {"id": 1, "name": "Alice"},
    {"id": 2, "name": "Bob"},
}

result, err := json.EncodeStream(values)
if err != nil {
    panic(err)
}
fmt.Println(result)

Методы форматирования Processor

Тип Processor предоставляет дополнительные методы форматирования. Используйте json.New() для создания Processor (возвращает (*Processor, error)):

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

Processor.CompactBuffer

Сигнатура: func (p *Processor) CompactBuffer(dst *bytes.Buffer, src []byte, cfg ...Config) error

Сжатие байт JSON и запись в буфер dst. Функция Compact уровня пакета делегирует этому методу.

var buf bytes.Buffer
err := p.CompactBuffer(&buf, []byte(`{"name": "Alice"}`))
// buf.String() => {"name":"Alice"}

Processor.Indent

Сигнатура: func (p *Processor) Indent(dst *bytes.Buffer, src []byte, prefix, indent string, cfg ...Config) error

Запись JSON с отступами в буфер dst. Совместимость с encoding/json.Indent.

var buf bytes.Buffer
err := p.Indent(&buf, []byte(`{"name":"Alice"}`), "", "  ")

Processor.HTMLEscape

Сигнатура: func (p *Processor) HTMLEscape(dst *bytes.Buffer, src []byte, cfg ...Config)

Запись HTML-экранированного JSON в буфер dst, без возвращаемого значения. Совместимость с encoding/json.HTMLEscape.

var buf bytes.Buffer
p.HTMLEscape(&buf, []byte(`{"html":"<script>"}`))

TIP

Полную документацию по Processor см. в разделе Processor.

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

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

// Конфигурация по умолчанию
cfg := json.DefaultConfig()

// Конфигурация красивой печати
cfg = json.PrettyConfig()

// Конфигурация безопасности
cfg = json.SecurityConfig()

TIP

Полную документацию по полям Config см. в разделе Конфигурация.

Смотрите также

Функции запросов и получения - Операции запросов Get, GetString и др.
Функции изменения - Операции изменения Set, Delete и др.
Файловые операции - Файловые операции LoadFromFile, SaveToFile и др.
Конфигурация - Тип Config и параметры
Интерфейсы - Типы Processor, Encoder, Decoder

Функции кодирования и вывода ​

Функции сериализации ​

Marshal ​

Unmarshal ​

MarshalIndent ​

Функции форматирования ​

Compact ​

CompactString ​

Indent ​

HTMLEscape ​

Prettify ​

Функции настраиваемого кодирования ​

Encode ​

EncodePretty ​

EncodeWithConfig ​

Функции пакетного кодирования ​

EncodeBatch ​

EncodeFields ​

EncodeStream ​

Методы форматирования Processor ​

Processor.CompactBuffer ​

Processor.Indent ​

Processor.HTMLEscape ​

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

Смотрите также ​