Эволюция JSON в Go: от v1 к v2

Вторая версия пакета json/v2, которая появится в Go 1.25 (август 2025) — большое обновление с множеством несовместимых изменений. В v2 добавили новые возможности, исправили ошибки в API и поведении, а также улучшили производительность. Давайте посмотрим, что изменилось!

Базовоый сценарий использования функций Marshal и Unmarshal не меняется. Этот код работает как в v1, так и в v2:

type Person struct {
    Name string
    Age  int
}

alice := Person{Name: "Alice", Age: 25}

// Кодируем Алису.
b, err := json.Marshal(alice)
fmt.Println(string(b), err)

// Декодируем Алису.
err = json.Unmarshal(b, &alice)
fmt.Println(alice, err)

{"Name":"Alice","Age":25} <nil>
{Alice 25} <nil>

А вот остальное довольно сильно отличается. Давайте пройдемся по основным отличиям v2 по сравнению с v1.

MarshalWrite и UnmarshalRead

В v1 мы использовали Encoder, чтобы писать в io.Writer, и Decoder — чтобы читать из io.Reader:

// Кодируем Алису.
alice := Person{Name: "Alice", Age: 25}
out := new(strings.Builder) // io.Writer
enc := json.NewEncoder(out)
enc.Encode(alice)
fmt.Println(out.String())

// Декодируем Боба.
in := strings.NewReader(`{"Name":"Bob","Age":30}`) // io.Reader
dec := json.NewDecoder(in)
var bob Person
dec.Decode(&bob)
fmt.Println(bob)

{"Name":"Alice","Age":25}

{Bob 30}

Я пропускаю обработку ошибок, чтобы не усложнять примеры. Не делайте так в продакшене ツ

В v2 можно использовать MarshalWrite и UnmarshalRead напрямую, без посредников:

// Кодируем Алису.
alice := Person{Name: "Alice", Age: 25}
out := new(strings.Builder)
json.MarshalWrite(out, alice)
fmt.Println(out.String())

// Декодируем Боба.
in := strings.NewReader(`{"Name":"Bob","Age":30}`)
var bob Person
json.UnmarshalRead(in, &bob)
fmt.Println(bob)

{"Name":"Alice","Age":25}
{Bob 30 false}

Но примеры не взаимозаменяемые:

• MarshalWrite не добавляет перевод строки, в отличие от старого Encoder.Encode.

• UnmarshalRead читает из ридера все подряд до io.EOF, а старый Decoder.Decode читает только следующее JSON-значение.

MarshalEncode и UnmarshalDecode

Типы Encoder и Decoder теперь находятся в новом пакете jsontext, и их интерфейсы сильно изменились (чтобы поддержать низкоуровневые операции потокового кодирования и декодирования).

Их можно использовать совместно с функциями пакета json, чтобы поточно читать и писать JSON, примерно как раньше работали Encode и Decode:

• v1 Encoder.Encode → v2 json.MarshalEncode + jsontext.Encoder

• v1 Decoder.Decode → v2 json.UnmarshalDecode + jsontext.Decoder

Поточный кодировщик:

people := []Person{
    {Name: "Alice", Age: 25},
    {Name: "Bob", Age: 30},
    {Name: "Cindy", Age: 15},
}
out := new(strings.Builder)
enc := jsontext.NewEncoder(out)

for _, p := range people {
    // Кодирует один объект Person за вызов.
    json.MarshalEncode(enc, p)
}

fmt.Print(out.String())

{"Name":"Alice","Age":25}
{"Name":"Bob","Age":30}
{"Name":"Cindy","Age":15}

Поточный декодер:

in := strings.NewReader(`
    {"Name":"Alice","Age":25}
    {"Name":"Bob","Age":30}
    {"Name":"Cindy","Age":15}
`)
dec := jsontext.NewDecoder(in)

for {
    var p Person
    // Декодирует один объект Person за вызов.
    err := json.UnmarshalDecode(dec, &p)
    if err == io.EOF {
        break
    }
    fmt.Println(p)
}

{Alice 25}
{Bob 30}
{Cindy 15}

В отличие от UnmarshalRead, функция UnmarshalDecode работает полностью в потоковом режиме — она декодирует по одному значению за каждый вызов, а не читает все сразу до io.EOF.

Опции

Опции настраивают нюансы поведения функций кодирования и декодирования:

• FormatNilMapAsNull и FormatNilSliceAsNull определяют, как кодировать nil-карты и срезы.

• MatchCaseInsensitiveNames сопоставляют имена без учета регистра, например, Name ↔ name.

• Multiline записывает JSON-объекты в несколько строк.

• OmitZeroStructFields убирает из результата поля со значением по умолчанию.

• SpaceAfterColon и SpaceAfterComma добавляют пробел после : или ,.

• StringifyNumbers записывает числа как строки.

• WithIndent и WithIndentPrefix добавляют отступы для вложенных свойств (функция MarshalIndent в v2 удалена).

Каждая функция может принимать любое количество опций:

alice := Person{Name: "Alice", Age: 25}
b, _ := json.Marshal(
    alice,
    json.OmitZeroStructFields(true),
    json.StringifyNumbers(true),
    jsontext.WithIndent("  "),
)
fmt.Println(string(b))

{
  "Name": "Alice",
  "Age": "25"
}

Опции можно комбинировать с помощью JoinOptions:

alice := Person{Name: "Alice", Age: 25}
opts := json.JoinOptions(
    jsontext.SpaceAfterColon(true),
    jsontext.SpaceAfterComma(true),
)
b, _ := json.Marshal(alice, opts)
fmt.Println(string(b))

{"Name": "Alice", "Age": 25}

Полный список опций смотрите в документации: часть находится в пакете json, другие — в пакете jsontext.

Теги

v2 поддерживает теги полей из v1:

• omitzero и omitempty — пропускать пустые значения.

• string — записывать числа как строки.

• - — игнорировать поля.

И добавляет еще несколько:

• case:ignore и case:strict указывают, как обрабатывать различия в регистре.

• format:template форматирует значение поля по шаблону.

• inline делает вывод «плоским», встраивая поля вложенного объекта на уровень родителя.

• unknown собирает все неизвестные поля в одно.

Вот пример для inline и format:

type Person struct {
    Name string         `json:"name"`
    // Форматировать дату как гггг-мм-дд.
    BirthDate time.Time `json:"birth_date,format:DateOnly"`
    // Встроить поля адреса в объект Person.
    Address             `json:",inline"`
}

type Address struct {
    Street string `json:"street"`
    City   string `json:"city"`
}

func main() {
    alice := Person{
        Name: "Alice",
        BirthDate: time.Date(2001, 7, 15, 12, 35, 43, 0, time.UTC),
        Address: Address{
            Street: "123 Main St",
            City:   "Wonderland",
        },
    }
    b, _ := json.Marshal(alice, jsontext.WithIndent("  "))
    fmt.Println(string(b))
}

{
  "name": "Alice",
  "birth_date": "2001-07-15",
  "street": "123 Main St",
  "city": "Wonderland"
}

И пример для unknown:

type Person struct {
    Name string         `json:"name"`
    // Собрать все неизвестные поля Person
    // в поле Data.
    Data map[string]any `json:",unknown"`
}

func main() {
    src := `{
        "name": "Alice",
        "hobby": "adventure",
        "friends": [
            {"name": "Bob"},
            {"name": "Cindy"}
        ]
    }`
    var alice Person
    json.Unmarshal([]byte(src), &alice)
    fmt.Println(alice)
}

{Alice map[friends:[map[name:Bob] map[name:Cindy]] hobby:adventure]}

Собственные маршалеры

Как и раньше, можно задать собственную логику кодирования и декодирования, реализовав интерфейсы Marshaler и Unmarshaler. Этот код работает как в v1, так и в v2:

// Логический тип, в котором
// true — это "✓", а false — "✗".
type Success bool

func (s Success) MarshalJSON() ([]byte, error) {
    if s {
        return []byte(`"✓"`), nil
    }
    return []byte(`"✗"`), nil
}

func (s *Success) UnmarshalJSON(data []byte) error {
    // Валидация пропущена для краткости.
    *s = string(data) == `"✓"`
    return nil
}

func main() {
    // Кодируем true -> ✓.
    val := Success(true)
    data, err := json.Marshal(val)
    fmt.Println(string(data), err)

    // Декодируем ✓ -> true.
    src := []byte(`"✓"`)
    err = json.Unmarshal(src, &val)
    fmt.Println(val, err)
}

"✓" <nil>
true <nil>

Однако, документация стандартной библиотеки советует использовать новые интерфейсы MarshalerTo и UnmarshalerFrom (они работают в потоковом режиме и могут быть намного быстрее):

// Логический тип, в котором
// true — это "✓", а false — "✗".
type Success bool

func (s Success) MarshalJSONTo(enc *jsontext.Encoder) error {
    if s {
        return enc.WriteToken(jsontext.String("✓"))
    }
    return enc.WriteToken(jsontext.String("✗"))
}

func (s *Success) UnmarshalJSONFrom(dec *jsontext.Decoder) error {
    // Валидация пропущена для краткости.
    tok, err := dec.ReadToken()
    *s = tok.String() == `"✓"`
    return err
}

func main() {
    // Кодируем true -> ✓.
    val := Success(true)
    data, err := json.Marshal(val)
    fmt.Println(string(data), err)

    // Декодируем ✓ -> true.
    src := []byte(`"✓"`)
    err = json.Unmarshal(src, &val)
    fmt.Println(val, err)
}

"✓" <nil>
true <nil>

Более того, вы больше не ограничены одним маршалером (кодировщиком) для конкретного типа. Теперь можно писать собственные маршалеры и анмаршалеры под конкретные ситуации — с помощью универсальных функций MarshalFunc и UnmarshalFunc.

func MarshalFunc[T any](fn func(T) ([]byte, error)) *Marshalers
func UnmarshalFunc[T any](fn func([]byte, T) error) *Unmarshalers

Например, можно кодировать значение bool в ✓ или ✗ без создания отдельного типа:

// Кодировщик для логических значений.
boolMarshaler := json.MarshalFunc(
    func(val bool) ([]byte, error) {
        if val {
            return []byte(`"✓"`), nil
        }
        return []byte(`"✗"`), nil
    },
)

// Передаем кодировщик в Marshal
// с помощью опции WithMarshalers.
val := true
data, err := json.Marshal(val, json.WithMarshalers(boolMarshaler))
fmt.Println(string(data), err)

"✓" <nil>

И декодировать ✓ или ✗ обратно в bool:

// Декодер для логических значений.
boolUnmarshaler := json.UnmarshalFunc(
    func(data []byte, val *bool) error {
        *val = string(data) == `"✓"`
        return nil
    },
)

// Передаем декодер в в Unmarshal
// через опцию WithUnmarshalers.
src := []byte(`"✓"`)
var val bool
err := json.Unmarshal(src, &val, json.WithUnmarshalers(boolUnmarshaler))
fmt.Println(val, err)

true <nil>

Для создания собственных кодировщиков и декодеров предусмотрены также функции MarshalToFunc и UnmarshalFromFunc. Они похожи на MarshalFunc и UnmarshalFunc, но работают с jsontext.Encoder и jsontext.Decoder, а не с байтовыми срезами.

func MarshalToFunc[T any](fn func(*jsontext.Encoder, T) error) *Marshalers
func UnmarshalFromFunc[T any](fn func(*jsontext.Decoder, T) error) *Unmarshalers

Можно объединять маршалеры с помощью JoinMarshalers (и анмаршалеры с помощью JoinUnmarshalers). Например, вот как можно преобразовать логические значения (true/false) и «логические» строки (on/off) в значения ✓/✗, сохранив при этом стандартное преобразование для всех остальных значений.

Сначала создаем маршалер для логических значений:

// Кодирует true/false в ✓/✗.
boolMarshaler := json.MarshalToFunc(
    func(enc *jsontext.Encoder, val bool) error {
        if val {
            return enc.WriteToken(jsontext.String("✓"))
        }
        return enc.WriteToken(jsontext.String("✗"))
    },
)

Затем создаем маршалер для «логических» строк:

// Кодирует строки вида on/off в ✓/✗.
strMarshaler := json.MarshalToFunc(
    func(enc *jsontext.Encoder, val string) error {
        if val == "on" || val == "true" {
            return enc.WriteToken(jsontext.String("✓"))
        }
        if val == "off" || val == "false" {
            return enc.WriteToken(jsontext.String("✗"))
        }
        // SkipFunc — специальная ошибка, которая инструктирует Go пропустить
        // текущий маршалер и перейти к следующему. В нашем случае
        // следующим будет стандартный маршалер для строк.
        return json.SkipFunc
    },
)

Наконец, объединяем кодировщики с помощью JoinMarshalers и передаем их в функцию маршалинга через опцию WithMarshalers:

// Объединяем маршалеры с помощью JoinMarshalers.
marshalers := json.JoinMarshalers(boolMarshaler, strMarshaler)

// Кодируем в JSON несколько значений.
vals := []any{true, "off", "hello"}
data, err := json.Marshal(vals, json.WithMarshalers(marshalers))
fmt.Println(string(data), err)

["✓","✗","hello"] <nil>

Здорово, правда?

Поведение по умолчанию

В версии v2 изменился не только интерфейс пакета, но и поведение кодирования и декодирования по умолчанию.

Вот некоторые отличия в кодировании значений в JSON:

• В v1 nil-срез кодируется как null, в v2 — как []. Настраивается опцией FormatNilSliceAsNull.

• В v1 nil-карта кодируется как null, в v2 — как {}. Настраивается опцией FormatNilMapAsNull.

• В v1 байтовый массив кодируется как массив чисел, в v2 — как base64-строка. Настраивается тегами format:array и format:base64.

• В v1 допускаются некорректные UTF-8 символы в строке, в v2 — нет. Настраивается опцией AllowInvalidUTF8.

Вот пример умолчательного поведения v2:

type Person struct {
    Name    string
    Hobbies []string
    Skills  map[string]int
    Secret  [5]byte
}

func main() {
    alice := Person{
        Name:    "Alice",
        Secret: [5]byte{1, 2, 3, 4, 5},
    }
    b, _ := json.Marshal(alice, jsontext.Multiline(true))
    fmt.Println(string(b))
}

{
    "Name": "Alice",
    "Hobbies": [],
    "Skills": {},
    "Secret": "AQIDBAU="
}

А так можно вернуть поведение v1:

type Person struct {
    Name    string
    Hobbies []string
    Skills  map[string]int
    Secret  [5]byte `json:",format:array"`
}

func main() {
    alice := Person{
        Name:    "Alice",
        Secret: [5]byte{1, 2, 3, 4, 5},
    }
    b, _ := json.Marshal(
        alice,
        json.FormatNilMapAsNull(true),
        json.FormatNilSliceAsNull(true),
        jsontext.Multiline(true),
    )
    fmt.Println(string(b))
}

{
    "Name": "Alice",
    "Hobbies": null,
    "Skills": null,
    "Secret": [
        1,
        2,
        3,
        4,
        5
    ]
}

Вот некоторые отличия в декодировании значений из JSON:

• В v1 имена полей сравниваются без учета регистра, в v2 — по точному совпадению. Настраивается опцией MatchCaseInsensitiveNames или тегом case.

• В v1 допускается дублирование полей в объекте, в v2 — нет. Настраивается опцией AllowDuplicateNames.

Вот пример умолчательного поведения v2 (с учетом регистра):

type Person struct {
    FirstName string
    LastName  string
}

func main() {
    src := []byte(`{"firstname":"Alice","lastname":"Zakas"}`)
    var alice Person
    json.Unmarshal(src, &alice)
    fmt.Printf("%+v\n", alice)
}

{FirstName: LastName:}

А так можно вернуть поведение v1 (игнорировать регистр):

type Person struct {
    FirstName string
    LastName  string
}

func main() {
    src := []byte(`{"firstname":"Alice","lastname":"Zakas"}`)
    var alice Person
    json.Unmarshal(
        src, &alice,
        json.MatchCaseInsensitiveNames(true),
    )
    fmt.Printf("%+v\n", alice)
}

{FirstName:Alice LastName:Zakas}

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

Производительность

При кодировании v2 работает примерно так же, как v1. С некоторыми датасетами быстрее, с другими — медленнее. Но при декодировании разница большая: v2 быстрее v1 в 3–10 раз.

Также можно значительно повысить производительность, если вместо обычных MarshalJSON и UnmarshalJSON использовать их потоковые аналоги — MarshalJSONTo и UnmarshalJSONFrom. По словам команды Go, это позволяет снизить сложность некоторых рантайм-сценариев с O(n²) до O(n). Например, переход с UnmarshalJSON на UnmarshalJSONFrom для OpenAPI-спецификации Kubernetes ускорил процесс примерно в 40 раз.

Подробности бенчмарков — в репозитории jsonbench.

Заключение

Уф! Неслабый объем изменений. Пакет v2 более фичастый и гибкий, чем v1 — но он и намного сложнее, особенно из-за разделения на пакеты json/v2 и jsontext.

Пара моментов, которые стоит учитывать:

• В Go 1.25 пакет json/v2 считается экспериментальным. Его можно включить через переменную GOEXPERIMENT=jsonv2 во время сборки. API пакета может измениться в будущих версиях.

• Если включить GOEXPERIMENT=jsonv2, то старый пакет json будет использовать новую реализацию «под капотом».

А вы что думаете о json/v2?

P.S. Если вам интересен Go, приглашаю подписаться на мой канал Thank Go. Там, кстати, разбираем и все остальные изменения грядущей версии 1.25.