Go 1.27 JSON декодирование: encoding/json/v2 на практике

Что изменилось в Go 1.27: три реализации JSON

После многолетней работы сообщества и экспериментального периода, начавшегося с go-json-experiment, Go 1.27 предлагает три различных варианта JSON:

1. Оригинальный движок v1. Доступен, но только если явно отказаться от нового через GOEXPERIMENT=nojsonv2 go build. В будущих релизах этот флаг будет удалён. Для большинства команд этот путь неактуален.

2. encoding/json на базе движка v2 - новый вариант по умолчанию. Если ничего не менять, существующий код Go на версии 1.27 использует новый движок v2 под знакомым API encoding/json. Те же сигнатуры функций, тот же путь импорта, то же поведение - просто быстрее для многих нагрузок. Изменения в коде не нужны.

3. Прямое использование encoding/json/v2. Новый пакет с новым API и более строгой семантикой по умолчанию. Здесь сосредоточены все преимущества v2, а также часть изменений в поведении по сравнению с v1.

Вот как выглядит разница в импортах на практике:

// Go 1.27 stdlib - API v1, движок v2 внутри
// Изменения в коде не нужны. Существующий код просто работает быстрее.
import "encoding/json"

var result Order
err := json.Unmarshal(data, &result)

// Прямой API v2 - новый пакет, новая семантика
import jsonv2 "encoding/json/v2"

var result Order
err := jsonv2.Unmarshal(data, &result) // то же имя функции, другой пакет и поведение

Это различие важно при планировании миграции. Если код импортирует encoding/json, в Go 1.27 он получит бесплатное ускорение без изменений. Если нужны RejectUnknownMembers, потоковая обработка через UnmarshalRead или строгая проверка UTF-8 и дублирующихся ключей - потребуется явно импортировать encoding/json/v2.

Почему движок v2 архитектурно отличается

В движке v1 были известные архитектурные проблемы. Кастомные реализации MarshalJSON/UnmarshalJSON вызывали квадратичную деградацию производительности при рекурсивных вызовах, потому что JSON-значения парсились дважды. Кодировщик v1 принимал невалидный UTF-8 и дублирующиеся ключи объектов - это проблемы корректности, а не только производительности. Нечувствительное к регистру сопоставление имён в v1 было реализовано неэффективно и создавало потенциальную уязвимость.

Движок v2 разделяет синтаксические задачи (encoding/json/jsontext) и семантические (encoding/json/v2). jsontext.Decoder действительно потоковый - он обрабатывает токены в фиксированном объёме памяти независимо от размера документа. Decoder.Decode из v1 буферизировал JSON-значения целиком перед обработкой.

Почему json/v2 может быть быстрее - а иногда нет

В примечаниях к выпуску Go 1.27 сказано: "производительность декодирования значительно выше" и "производительность кодирования в целом на паритете". Оба утверждения правильны по направлению, но ни одно не передаёт полную картину.

Что показали предрелизные бенчмарки. Проект go-json-experiment/jsonbench измерял движок v2 на фоне v1 с использованием Go 1.23.5 и экспериментального снапшота v2 января 2025 года - не релиза Go 1.27. Числа: от 2,7x до 10,2x быстрее для декодирования конкретных типов, от 2,3x до 5,7x быстрее для декодирования типа interface. Значение 10x встречается в бенчмарках RawValue (только декодер), где исключена стоимость рефлексии. Это направленные индикаторы возможностей нового движка, а не производственные прогнозы для вашей нагрузки.

Что реально даёт Go 1.27. Daniel Lemire провёл независимые бенчмарки в августе 2026 года на Go 1.27.0, используя реальные наборы данных JSON (twitter.json - 632 КБ, citm_catalog.json - 1,73 МБ, canada.json - 2,25 МБ) на оборудовании Apple M4 Max и Intel Xeon Gold 6548N.

Для legacy-API encoding/json на движке v2 (то, что вы получаете бесплатно в Go 1.27 без изменений):

• twitter.json, декодирование в any: 172 МБ/с -> 203 МБ/с (+18%)
• citm_catalog.json, декодирование в any: 186 МБ/с -> 241 МБ/с (+30%)
• canada.json, декодирование в any: 128 МБ/с -> 106 МБ/с (-17%)

Регрессия на canada.json важна: этот набор данных содержит геометрию с глубокими числовыми массивами. Не каждая нагрузка выигрывает от нового движка.

Переход на прямой API json/v2 даёт ещё 1,8x - 2x ускорения декодирования поверх прироста от legacy-API для типа any, что в итоге составляет примерно 1,5x - 2,3x по сравнению с оригинальным движком v1.

История с кодированием другая. Официальное заявление "в целом на паритете" не подтверждается для кодирования (marshaling) типизированных структур в тестах Lemire. Кодирование типизированных структур с json/v2 примерно в 1,5 раза медленнее оригинального движка v1. Кодирование any в 1,2x - 3x быстрее с v2.

Вывод: прирост при декодировании реален. Поведение при кодировании зависит от нагрузки. Если ваш сервис активно генерирует ответы с типизированными структурами и критичен по задержкам - тщательно измерьте, прежде чем предполагать, что v2 улучшит всё.

Более строгое поведение: что v2 применяет по умолчанию

Переход на прямую семантику json/v2 изменяет обработку граничных случаев, которые v1 принимал молча.

Дублирующиеся ключи в JSON-объекте - v2 отклоняет их по умолчанию. v1 принимал дубли и использовал последнее значение. Если источник данных присылает невалидный JSON с дублирующимися ключами, v2 вернёт ошибку там, где v1 молча справлялся.

Невалидный UTF-8 - v2 отклоняет невалидный UTF-8 в строках. v1 принимал. Это гарантия корректности, но любой источник, присылающий JSON с небезопасным UTF-8, начнёт падать с ошибками.

Чувствительное к регистру сопоставление имён - v2 по умолчанию сопоставляет имена полей структур с учётом регистра. v1 был нечувствителен к регистру. Это затрагивает любой код, полагавшийся на нечёткое сопоставление полей. Восстановить поведение v1 можно через MatchCaseInsensitiveNames(true), но это стоит производительности.

Неизвестные поля - и v1, и v2 по умолчанию молча игнорируют неизвестные JSON-поля. В v2 можно включить строгое отклонение:

import jsonv2 "encoding/json/v2"

opts := jsonv2.RejectUnknownMembers(true)
if err := jsonv2.UnmarshalOptions(opts, data, &result); err != nil {
    // неизвестное поле в JSON - ошибка, а не молчаливый пропуск
    return err
}

Для B2B-интеграций RejectUnknownMembers полезен. Если партнёрский API начнёт присылать новые поля, которые ваша структура не обрабатывает, молчаливый пропуск означает, что изменение можно не заметить совсем. При включённом отклонении вы получите явную ошибку, которая заставит явно решить, что делать.

Потоковая обработка JSON: UnmarshalRead и UnmarshalDecode

API json/v2 добавляет функции, работающие напрямую с io.Reader, а не байтовыми срезами. Для HTTP-сервисов это важно.

UnmarshalRead декодирует из io.Reader и, что принципиально, отклоняет данные после JSON-значения. Паттерн v1 с json.NewDecoder(r).Decode(&v) молча игнорирует всё после первого JSON-значения - частый источник тонких ошибок при получении некорректных HTTP-ответов.

import (
    jsonv2 "encoding/json/v2"
    "net/http"
)

func parseResponse(resp *http.Response) (*Order, error) {
    var order Order
    if err := jsonv2.UnmarshalRead(resp.Body, &order); err != nil {
        return nil, err
    }
    return &order, nil
}

UnmarshalDecode - выбор для потоков событий, NDJSON (JSON с разделением переносом строки) или любого сценария, где нужно последовательно читать несколько JSON-значений из одного ридера. Принимает jsontext.Decoder, что даёт детальный контроль над настройками декодирования.

Сам jsontext.Decoder по-настоящему потоковый - обрабатывает токены в фиксированном объёме памяти независимо от размера документа. Это реальное улучшение по сравнению с Decoder из v1, который буферизировал JSON-значения целиком перед передачей на семантический уровень.

Кастомное декодирование через UnmarshalerFrom и WithUnmarshalers

Когда нужна кастомная логика декодирования - нестандартные форматы дат, доменные типы, условный парсинг - v2 предлагает два механизма.

Интерфейс UnmarshalerFrom позволяет типу реализовать собственное декодирование с полным доступом к jsontext.Decoder:

type CustomDate struct {
    time.Time
}

func (d *CustomDate) UnmarshalJSONFrom(dec *jsontext.Decoder) error {
    var s string
    if err := jsonv2.UnmarshalDecode(dec, &s); err != nil {
        return err
    }
    t, err := time.Parse("2006-01-02", s)
    if err != nil {
        return err
    }
    d.Time = t
    return nil
}

WithUnmarshalers позволяет внедрить кастомное декодирование для конкретных типов без изменения самих типов - полезно при работе с типами, которыми вы не владеете:

opts := jsonv2.WithUnmarshalers(
    jsonv2.UnmarshalFromFunc(func(dec *jsontext.Decoder, t *time.Time) error {
        var s string
        if err := jsonv2.UnmarshalDecode(dec, &s); err != nil {
            return err
        }
        parsed, err := time.Parse(time.RFC3339, s)
        if err != nil {
            return err
        }
        *t = parsed
        return nil
    }),
)
err := jsonv2.UnmarshalOptions(opts, data, &result)

Это заменяет паттерн v1 с реализацией UnmarshalJSON([]byte) error, который вынуждал повторно парсить переданные необработанные байты - проблема двойного парсинга, приводившая к квадратичному поведению в v1.

Бенчмарки JSON для вашего реального проекта

Приведённые выше числа - из jsonbench, Lemire или любого другого источника - получены на конкретном оборудовании, конкретных наборах данных и конкретных структурах типов. Они не предскажут, что произойдёт в вашем сервисе.

Если парсинг JSON - реальная статья затрат в вашей системе, измерьте его самостоятельно. Вот шаблон:

func BenchmarkUnmarshalOrder(b *testing.B) {
    data := []byte(`{"id": 42, "items": [{"sku": "X1", "qty": 3}], "total": 1234.56}`)
    b.ReportAllocs()
    for b.Loop() {
        var order Order
        _ = json.Unmarshal(data, &order)
    }
}
// Запуск: go test -bench=. -benchmem -count=10 | benchstat -

Три вещи, которые нужно сделать правильно:

Используйте b.ReportAllocs(). Количество выделений памяти часто важно так же, как пропускная способность. Меньше выделений - меньше давления на GC, что в высоконагруженных сервисах важнее, чем сырые цифры пропускной способности.

Используйте -count=10 и benchstat. Единственный запуск бенчмарка - шумный. benchstat вычисляет статистическую сводку по нескольким запускам и показывает, реальна ли разница или находится в пределах погрешности. Установить: go install golang.org/x/perf/cmd/benchstat@latest.

Используйте реальные данные нагрузки. Разница между 100-байтовой плоской структурой и 10 КБ вложенного документа нелинейна. Если сервис обрабатывает ERP-нагрузку со структурами из 50 полей и вложенными массивами - бенчмаркируйте именно её, а не синтетический {"id": 1}.

Что на самом деле показывают результаты бенчмарков

Когда вы запускаете бенчмарки своего сервиса, вы измеряете пересечение нескольких факторов: размер документа, глубина вложенности, соотношение строковых и числовых полей, доля interface-типов против конкретных типов в структуре, паттерны выделений памяти.

Документы с преобладанием строк существенно выигрывают от улучшенного повторного использования памяти в движке v2. Числовые документы (как данные геометрии canada.json в тесте Lemire) могут не выиграть совсем. Поля с interface-типами (any, interface{}) получают наибольший относительный прирост при прямом использовании API v2.

ByteDance внутренне сообщает, что обработка JSON занимает около 10% CPU в их типичных сервисах и свыше 40% в экстремальных случаях - но это данные от вендора, строящего Sonic, и их "экстремальные" случаи нерепрезентативны для большинства B2B-бэкендов. Актуальный вопрос не "сколько JSON стоит в ByteDance", а "что показывает профилирование вашего сервиса".

Быстрая проверка профиля перед любой оптимизацией JSON:

go test -cpuprofile=cpu.out -bench=.
go tool pprof -top cpu.out | grep -i json

Если JSON не входит в топ-10 функций по CPU-времени - оптимизировать его скорее всего бессмысленно.

Влияние на B2B, ERP и высоконагруженные системы

Для большинства B2B и ERP-интеграций история производительности JSON в Go 1.27 проста: обновитесь до Go 1.27, получите бесплатное улучшение декодирования и двигайтесь дальше. Прирост пропускной способности на 18%-30% при декодировании в тип any (по результатам Lemire на наборах twitter.json и citm_catalog.json) реален и ничего не стоит.

Более интересный вопрос для корпоративных Go-систем - не сырая скорость, а корректность.

B2B-интеграции ломаются определённым образом: партнёр добавляет или переименовывает поле, код молча игнорирует изменение, и вы не узнаёте об этом, пока бизнес-логика не упадёт глубже по цепочке. Опция RejectUnknownMembers в json/v2 даёт инструмент для перехвата этого на границе. Её можно включить в staging со строгим отклонением, а в production - в режиме только логирования, чтобы знать о дрейфе контрактов.

Для событийно-ориентированных систем, обрабатывающих большой объём сообщений - обработка заказов, обновление запасов, документооборот или конвейеры событий, на которых держится интернет маркетинг и его аналитика, - структурные улучшения потоковой обработки в json/v2 существенны. Обработка токенов в фиксированном объёме памяти через jsontext.Decoder позволяет обрабатывать большие потоки JSON-событий без буферизации всего документа. Для сервисов с миллионами запросов в день снижение давления на выделения памяти означает меньшую частоту пауз GC и более предсказуемые задержки.

Для малопоточных внутренних сервисов - API администратора с несколькими сотнями запросов в день - всё это нерелевантно. То же верно для типовых корпоративных проектов, которые любая веб студия сдаёт в срок: парсинг JSON там далеко не на критическом пути. Сначала профилируйте.

Где улучшение на 18%-30% реально важно: API-шлюз, обрабатывающий 50 000 операций декодирования JSON в секунду, будет обрабатывать примерно на 9 000 - 15 000 больше запросов в секунду бесплатно на Go 1.27, без изменений в коде. В таком масштабе накопительный эффект на стоимость инфраструктуры и перцентили задержек измерим - а на публичных эндпоинтах эти перцентили напрямую влияют на сигналы скорости, от которых зависит сео продвижение сайтов.

Где не важно: ночное пакетное задание, импортирующее 5 000 ERP-записей. Задержка здесь определяется записями в БД и сетевыми обращениями, а не парсингом JSON.

В Webdelo наш стандартный подход для Go-проектов - профилировать производственные нагрузки до принятия любых решений об оптимизации. Та же дисциплина действует и там, где нужна разработка сайтов под нагрузкой: сначала измерение, потом изменение кода. Производительность JSON становится актуальной, когда появляется в flame-графах pprof - и тогда мы бенчмаркируем на реальном формате данных, а не на синтетических. Мы работали над достаточным количеством B2B-интеграций и ERP-систем, чтобы знать: "JSON работает медленно" редко является узким местом, но когда так - это видно чётко.

Сторонние JSON-библиотеки: практическое сравнение

С появлением encoding/json/v2 в стандартной библиотеке аргументы в пользу сторонних JSON-библиотек сузились. Вот положение каждой из них.

Sonic

Sonic использует JIT-компиляцию и SIMD-инструкции для генерации машинного кода, специализированного под Go-тип во время выполнения. На amd64 и arm64 это самый быстрый доступный вариант - до 2,8x быстрее json/v2 для декодирования конкретных типов.

Компромиссы существенные. Sonic использует unsafe и не валидирует UTF-8 в JSON-строках. Если B2B-интеграция получает JSON от партнёров с данными не в ASCII, Sonic молча примет невалидный UTF-8, который json/v2 отклонил бы. Работает только на amd64 и arm64 - на других архитектурах автоматически происходит откат к stdlib, но кросс-платформенная согласованность теряется. Также есть зависимость от ABI времени выполнения: Go 1.24.0 не поддерживался (работает 1.24.1+), и будущие релизы Go могут вводить аналогичные окна совместимости.

Мы выбрали бы Sonic только при следующих условиях: профилирование выявило реальное узкое место в JSON, сервис работает исключительно на amd64 или arm64, команда принимает компромисс с UTF-8, и прирост производительности подтверждён на репрезентативных производственных данных.

segmentio/encoding

Замена encoding/json с тем же API. До 1,9x быстрее декодирование по сравнению с json/v2 в бенчмарках, до 2,0x быстрее для обработки raw-значений. Использует unsafe. Не поддерживает потоковое кодирование и декодирование.

Для команд, которым нужно больше производительности, чем даёт стандартная библиотека, и не хочется сложности JIT-подхода Sonic, segmentio - разумный выбор. API идентичен encoding/json, поэтому миграция механическая.

easyjson

easyjson генерирует Go-код во время сборки, обрабатывающий кодирование и декодирование без рефлексии. Сгенерированный код быстрый - заявленные 4-5x по сравнению с encoding/json v1, хотя бенчмарки зависят от нагрузки.

Цена: нужно запускать easyjson -all . для генерации файлов, коммитить сгенерированный код и перезапускать генерацию при изменении структур. Это реальная нагрузка на сопровождение, особенно для развивающихся схем. Для B2B-интеграции, где JSON-схема меняется при обновлении API партнёра, сгенерированный код нужно держать в синхронизации.

easyjson хорош для стабильных высокообъёмных схем: фиксированные форматы сообщений, фиксированные типы событий или высоконагруженные горячие пути с предсказуемой структурой. Последний релиз - март 2026, активно поддерживается.

goccy/go-json

Быстрее json/v2 для декодирования конкретных типов (от 1,3x до 1,8x), использует unsafe, API совместим с encoding/json. Оговорка по корректности существенная: набор тестов jsonbench документирует недетерминированные сбои, включая SliceEnd opcode not implemented и invalid character ',' after object key в некоторых сценариях кодирования interface-типов.

Недетерминированные сбои особенно опасны в production. Воспроизводимый баг - отлаживаемый. Тот, что проявляется эпизодически на конкретных паттернах данных, - нет. Мы бы не использовали goccy/go-json в production B2B-системе, пока эти проблемы не будут устранены и верифицированы в тестовом наборе библиотеки.

json-iterator/go

Архивирована владельцем 15 декабря 2025 года. Репозиторий доступен только для чтения. Не используйте для новых проектов. Если у вас есть существующий код на json-iterator - он продолжит компилироваться, но вы накапливаете технический долг без поддержки upstream.

GJSON и jsonparser

Это выборочные парсеры - позволяют извлекать конкретные поля из JSON без десериализации всего документа. API принципиально отличается от encoding/json. GJSON или jsonparser используют, когда нужно прочитать 2-3 поля из 200-польного JSON и выделять полную структуру расточительно.

Они не замена Unmarshal. Для полной десериализации документа используйте json/v2 или одну из библиотек выше.

Какую JSON-библиотеку мы выбрали бы для нового корпоративного Go-проекта

Для нового Go-проекта в 2026 году - B2B-интеграции, ERP-бэкенда, корпоративного API или высоконагруженного сервиса - наш выбор по умолчанию: encoding/json/v2 с прямым импортом v2. Не потому что это самый быстрый вариант, а потому что он даёт лучшее сочетание гарантий корректности, стабильности стандартной библиотеки, отсутствия внешних зависимостей и хорошей производительности.

Гарантии корректности в корпоративных контекстах важнее сырой пропускной способности. Строгая валидация UTF-8, отклонение дублирующихся ключей и RejectUnknownMembers перехватывают проблемы интеграции на границе. Это функции, которые иначе пришлось бы строить вручную поверх v1.

Когда мы бы добавили Sonic: мы измерили реальное узкое место в JSON в production pprof, сервис работает на amd64 или arm64, команда явно приняла компромисс с UTF-8, и прирост производительности подтверждён на production-данных. Этот сценарий редок.

Когда мы бы использовали easyjson: фиксированная схема, высокий объём, требование к производительности чёткое и измеренное, и команда комфортно работает с генерацией кода на этапе сборки.

Пропустили бы: json-iterator (архивирован), goccy/go-json (риск корректности в production).

Миграция существующей B2B-системы на json/v2

Если у вас есть существующая система и нужно поэтапно принять семантику v2, путь миграции состоит из четырёх шагов.

Шаг 1: обновитесь до Go 1.27 и получите бесплатное ускорение. Импорты encoding/json теперь используют движок v2 с семантикой v1. Изменений в коде нет, частичное улучшение декодирования.

Шаг 2: используйте DefaultOptionsV1() при вызове API v2. Это слой совместимости, который делает v2 идентичным по поведению v1. Безопасный первый шаг - именно так и работает encoding/json внутри Go 1.27.

import (
    jsonv2 "encoding/json/v2"
    jsonv1 "encoding/json"
)

// Поведение идентично encoding/json, но через API v2
jsonv2.Unmarshal(data, &v, jsonv1.DefaultOptionsV1())

// Включайте поведение v2 по одному
jsonv2.Unmarshal(data, &v, jsonv1.DefaultOptionsV1(),
    jsonv2.RejectUnknownMembers(true))

Шаг 3: используйте jsonsplit для обнаружения поведенческих различий. Пакет jsonsplit предоставляет AutoDetectOptions, который запускает семантику v1 и v2 параллельно и логирует случаи, когда они дают разный результат. Это бесценно для поиска мест, где существующие данные полагаются на поведение v1 (нечувствительность к регистру, дублирующиеся ключи, невалидный UTF-8) - до перехода на умолчания v2. Можно запускать в теневом режиме в production без изменения поведения.

Шаг 4: принимайте семантику v2 там, где она добавляет ценность. Как только вы знаете, какие пути кода чисты - включайте RejectUnknownMembers на границах API, переключайте парсинг HTTP-ответов на UnmarshalRead и убирайте переопределение DefaultOptionsV1() для этих путей.

Ключевой принцип: более поздние опции переопределяют более ранние. Поведение v2 можно включать по одному, в управляемом развёртывании. Миграция "всё сразу" не нужна.

Изменения поведения, которые могут сломать существующий код

Перед миграцией проверьте кодовую базу на эти конкретные паттерны:

• Nil-срезы и nil-отображения: v1 кодирует их как null; v2 - как [] и {}. Любой код, проверяющий null в JSON-выводе, требует проверки.
• Нечувствительное к регистру сопоставление полей: v1 сопоставлял "OrderID" с полем структуры orderID. v2 по умолчанию требует точного соответствия регистру. Если партнёры присылают непоследовательный регистр - нужно явно добавить MatchCaseInsensitiveNames(true).
• Удалённые опции v2: если вы использовали экспериментальный v2 в период GOEXPERIMENT - обратите внимание, что теги структур format и unknown, опция кодирования DiscardUnknownMembers и sentinel-ошибка SkipFunc были удалены до Go 1.27. Тег структуры inline переименован в embed.

Заключение

Изменения JSON в Go 1.27 существенные. Бесплатное ускорение от обновления до Go 1.27 без изменений кода реально - улучшение на 18% - 30% для декодирования в тип any на типичных JSON-данных. Прямой API json/v2 даёт больше: декодирование в 1,5x - 2,3x быстрее по сравнению с оригинальным движком v1, плюс более строгие гарантии корректности.

Но история с кодированием сложнее. Для кодирования типизированных структур json/v2 может быть в 1,5 раза медленнее оригинального движка v1. Официальное заявление "на паритете" не справедливо для всех нагрузок. Измерьте свой конкретный случай.

Для новых Go-проектов в 2026 году encoding/json/v2 - правильный выбор по умолчанию: не потому что он универсально быстрее, а потому что обеспечивает корректность, поддержку стандартной библиотеки и хорошую производительность без внешних зависимостей. Sonic и easyjson обоснованы в конкретных, измеренных сценариях. json-iterator архивирован и не должен использоваться для новой работы.

Общий урок тот же, что применим к большинству решений по производительности в корпоративных Go-системах: сначала профилируйте, затем бенчмаркируйте свою реальную нагрузку, затем принимайте решение. Улучшение декодирования на 30% существенно при 50 000 запросов в секунду и нерелевантно в ночном пакетном задании.

Если вы строите или оптимизируете Go-систему - B2B-интеграцию, ERP-бэкенд, высоконагруженный API - и хотите команду, которая делала это в production, Webdelo строит Go-системы для B2B и корпоративных клиентов с 2006 года. Мы не оптимизируем спекулятивно. Мы профилируем, измеряем и принимаем решения на основе того, что данные показывают в вашей конкретной нагрузке.