JSON: кодирование и декодирование

JSON — JavaScript Object Notation — текстовый формат обмена данными: объекты в фигурных скобках, пары «ключ: значение», массивы в квадратных, строки в кавычках, числа, true/false и null. Но для Go важнее другое: JSON — это БАЙТЫ. Обычные байты UTF-8, о которых мы говорили в прошлом уроке, просто с договорённостью о том, что они значат: где кончается ключ, где начинается значение, что считать массивом. Прошлый урок дал вам os.ReadFile и контракт io.Reader — доставку байтов; этот урок даёт форму — упаковку значений в байты и обратно. Запрос «json go» на деле распадается на три навыка: кодировать значение в JSON (json.Marshal), декодировать JSON в значение (json.Unmarshal) и управлять формой текста (struct tags, omitempty, Encoder, Decoder). Этим трём навыкам и посвящён урок.

Почему вообще нужен формат вроде JSON? Срезы и структуры живут в памяти процесса и умирают вместе с ним; передать их по сети или сохранить на диск «как есть» нельзя — память процесса не транспорт. Нужна последовательность байтов, по которой получатель соберёт ту же структуру. Это называется сериализацией: упаковка значения в байтовую последовательность. Десериализация — обратная поездка: байты в значение. В Go за обе поездки отвечает один пакет — encoding/json, а маршалером и анмаршалером называют именно его функции: marshal — кодировать, unmarshal — декодировать; «marshal unmarshal» — пара, которую вы будете гуглить всю карьеру, и она же — ключевые слова этого урока.

Договоримся о честности песочницы сразу, как в прошлом уроке. Резервный движок знает только fmt, strings, strconv, math, sort, errors и time — encoding/json в этом списке нет, и мы зафиксируем точный текст отказа. Основной движок (yaegi) исполняет пакет честно: json.Marshal и json.Unmarshal с тегами, omitempty, Encoder и Decoder, RawMessage — всё работает, вывод детерминирован, каждый раннер урока прогнан трижды. А тот единственный полигон, который доступен обоим движкам, построен руками: JSON — просто текст, и его можно собрать из строки без всяких пакетов, чем мы и займёмся в первом раннере.

json.Marshal(v) принимает значение любого типа и возвращает пару (b []byte, err error). Первое, что надо запомнить: результат — СРЕЗ БАЙТОВ, а не строка; JSON у нас байтовый, помните первый блок? Чтобы увидеть текст, нужна конверсия string(b) — та же, что у os.ReadFile в прошлом уроке. Второе: err обязателен к проверке. Marshal почти не ошибается на обычных данных (структуры, срезы, карты, числа, строки), но падает на том, что не умеет представить: канал, функция, комплексное число — для них вернётся UnsupportedTypeError, и молча проглоченная ошибка оставит вас с nil-срезом.

Для структур порядок полей и имена ключей решают struct tags — маленькие аннотации после объявления поля. Тег json:"name" говорит: «в JSON это поле зовётся name, не Name». Без тега Marshal использует имя поля как есть — с большой буквы; поэтому теги ставят почти всегда: API-контракты живут в нижнем регистре, а Go требует, чтобы поля были ЭКСПОРТИРУЕМЫМИ (с большой буквы) — неэкспортируемое поле Marshal молча пропустит, в JSON оно не попадает никогда, ведь пакет не может читать чужие приватные данные за пределами своего пакета. Два специальных значения тега: минус json:"-" полностью исключает поле из вывода, а через запятую идут опции — json:"name,omitempty" значит «зовётся name и прячется, когда пусто».

Теги читает рефлексия — reflect, десятый и восемнадцатый уроки курса уже дали вам её инструменты: Marshal не знает ничего о вашем типе на этапе компиляции, он в рантайме спрашивает у reflect.TypeOf поля, их теги и значения. Это же объясняет, почему тег — не комментарий: опечатка в json:\"nane\" не сломает компиляцию, поле просто выйдет под именем Name, и найти такой баг без теста непросто. И почему теги обязательны в виде строкового литерала: они разбираются парсером reflection-пакета по строгому формату имя,опция1,опция2.

Как Marshal кодирует базовые типы: строки — в кавычках (с нюансами, о которых ниже), числа — как есть, bool — true/false, nil-указатель и nil-интерфейс — null, срезы и массивы — массивы, карты — объекты, структуры — объекты с полями. Две неочевидные детали: срез байтов []byte кодируется СТРОКОЙ base64 ([]byte("hi") превратится в "aGk=") — это способ перевезти бинарные данные в текстовом формате; а ключи карты выводятся В ОТСОРТИРОВАННОМ порядке —.Marshal сортирует их, чтобы одинаковые данные давали одинаковые байты, что критично для кешей и подписей.

Опция omitempty в теге — самый частый гость после имени: json:"email,omitempty". Правило простое: если поле имеет НУЛЕВОЕ значение своего типа, оно не попадает в JSON вообще. Список нулевых значений стоит выучить: false для bool, 0 для любых чисел, "" для строк, nil для указателей, интерфейсов, срезов и карт (важно: nil-срез и ПУСТОЙ срез make([]T, 0) — не одно и то же для Marshal без omitempty — первый выйдет null, второй []; с omitempty спрячутся оба). Ключевое исключение, о которое спотыкаются все: omitempty НЕ РАБОТАЕТ для структур. Структура с нулевыми полями — не «нулевое значение» в смысле encoding/json, и поле-структура выйдет целиком со всеми нулями внутри. Хотите прятать опциональную структуру — делайте её указателем: nil-указатель omitempty прячет, а значение — выводит.

Зачем это нужно? Чтобы контракт ответа был предсказуемым и компактным. Поле «опции не заданы» в JSON с omitempty просто отсутствует — клиент по наличию ключа понимает, было ли значение; без omitempty пришлось бы везде таскать "status": "" и "count": 0, различая «пусто» и «не прислали» по соглашениям вместо фактов. Обратная сторона: ноль — иногда валидное значение. Поле Температура со значением 0 и omitempty исчезнет из ответа, и получатель не отличит «ноль градусов» от «датчик не отвечал» — в таких случаях omitempty не ставят или переходят на указатель.

Где вы уже это видели: в курсе Gin урок про JSON-ответы — там omitempty-форма собиралась для HTTP-хендлеров, и правило «структуры не прячутся, указатели — да» разбиралось на Todo-списке. Здесь, в стандартной библиотеке, механика та же до последней буквы: c.JSON внутри зовёт ровно тот json.Marshal, который вы вызываете руками. Связка полезная: научившись здесь, вы уже знаете, почему gin-ответ выглядит именно так.

Обратная поездка — json.Unmarshal(data []byte, v any) error. Два правила, на которых держится вся функция. Первое: v передаётся ПО АДРЕСУ — Unmarshal должен записать результат в вашу переменную, поэтому вызов всегда выглядит как err := json.Unmarshal(b, &p); забыли амперсанд — компилятор пропустит (any принимает всё), но поля останутся нулями: функция заполнила копию, которую тут же выбросила. Второе: data — это []byte, и здесь мост из прошлого урока замыкается: os.ReadFile вернул data []byte из файла конфигурации — Unmarshal превращает эти байты в структуру; это самая частая связка в реальных программах, и она стоит двух строк.

Сверка имён: Unmarshal идёт по JSON-ключам и ищет совпадающее поле адресата — сначала точное совпадение с тегом, потом с именем поля. JSON-ключ, для которого поля нет, МОЛЧА ИГНОРИРУЕТСЯ — это осознанное решение encoding/json: API добавляет новые поля, старые клиенты не падают. Но и опечатка в ожидаемом поле молча даст нулевое значение — строгую проверку формы делают отдельными библиотеками или через Decoder с DisallowUnknownFields, о котором поговорим в блоке про поток. Поле, отсутствующее в JSON, остаётся с нулевым значением — Unmarshal никогда не обнуляет то, что вы уже записали в структуру до вызова: он обновляет только то, что нашёл.

Типы при декодировании: JSON-число ложится в int, float64 или любой числовой тип поля — Unmarshal приведёт значение к типу поля (и вернёт ошибку UnmarshalTypeError, если «порт»: "восемьдесят" не лезет в int). JSON true/false — в bool, null — в nil для указателей, срезов, карт и интерфейсов (в число null не декодируется — останется нулевым). Битые байты — не-JSON вроде {broken — дают SyntaxError с позицией; ошибку проверяют всегда, nil-структура после провала разбора — классическая тихая беда.

Плоские формы скучны, и к счастью, Marshal/Unmarshal рекурсивны: поле-структура кодируется вложенным объектом, срез структур — массивом объектов, карта со структурами — объектом, у которого ключи карты стали ключами JSON. Правило одно: форма в JSON повторяет форму значения, на любую глубину. Теги работают на каждом уровне: у вложенной структуры — свои теги, и их имена видны в конечном тексте. Единственное ограничение — циклы: структура, которая ссылается сама на себя через значение, не кодируется (Marshal вернёт ошибку о неподдерживаемом значении); циклы через указатели тоже не разрулить — рекурсия должна кончаться в данных, а не в типе.

Срез структур — рабочая лошадка API: []Person с вложенными Address маршалится в массив объектов, и Unmarshal так же честно соберёт срез обратно, выделив память под каждый элемент сам. Карта — способ выразить «ключи заранее неизвестны»: map[string]int выйдет объектом с числами-значениями, и наоборот, объект с произвольными ключами удобно декодировать в карту, а не в структуру. Помните про сортировку: ключи карты в выводе всегда отсортированы — Marshal не оставит вам порядок вставки, как у срезов.

Выбор между структурой и картой — выбор между контрактом и гибкостью. Структура: поля известны, имена и типы проверяет компилятор, теги дают документацию; неправильные типы JSON ловятся в момент Unmarshal. Карта: форма динамическая — конфиг с произвольными секциями, результат парсера, «передай что угодно»; типы проверять приходится вручную через утверждения типов, а числа в any живут как float64. Зрелый код часто комбинирует: верхний уровень — структура с известными полями, одно из полей — map[string]any или json.RawMessage для части, чья форма меняется.

Что Marshal делает с не-ASCII текстом? Ничего: кириллица, эмодзи и любой валидный UTF-8 выходят КАК ЕСТЬ — сырыми байтами. json.Marshal("привет") даст четырнадцать байт с кавычками, где сами буквы — те самые по два байта из прошлого урока; len(string(b)) посчитает их честно. Юникод-эскейпы вида \u043f Marshal для кириллицы не генерирует — если вы их видели в ответах API, это либо другой язык, либо ручная обработка. Отсюда практическое правило: JSON с кириллицей весит больше, чем «выглядит», — счёт ведётся в байтах, и Content-Length вычисляется по len(b), а не по количеству знаков.

А вот три символа — <, > и & — Marshal экранирует ВСЕГДА по умолчанию: < станет \u003c, > — \u003e, & — \u0026. Зачем: если JSON вклеивается в HTML-страницу сырыми байтами (шаблонизаторы, inline-скрипты), строка без экранирования могла бы вынести за пределы JSON-литерала тег <script> — это вектор атаки под названием XSS. Экранирование не меняет смысла данных: любой JSON-парсер развернёт \u003c обратно в <. Для обычных API это не мешает вообще.

Когда байты важны — например, вы считаете хеш тела для кеша или клиенту нужен точный текст — экранирование отключают, и делается это не функцией Marshal, а Encoder'ом: enc := json.NewEncoder(w) создаёт энкодер, пишущий JSON прямо в Writer w; метод enc.SetEscapeHTML(false) выключает HTML-эскейпы, а enc.Encode(v) кодирует значение и дописывает в конец перевод строки — единственная байтовая разница помимо экранирования. В Gin вы это уже видели: c.PureJSON — это именно Encoder с SetEscapeHTML(false) против обычного c.JSON; теперь вы знаете, что под капотом. Метод Encode принимает любой io.Writer — буфер в памяти, файл из прошлого урока, сетевое соединение: контракт Reader/Writer снова экономит целый слой кода.

json.Unmarshal работает с готовым []byte: весь JSON должен лежать в памяти до вызова. json.Decoder — второй способ декодирования: dec := json.NewDecoder(r) принимает ЛЮБОГО io.Reader и читает значение МЕТОДОМ dec.Decode(&v) — по одному за вызов, подтягивая байты из источника по мере необходимости. Зачем второй способ? Три причины. Первая — поток из нескольких значений: источники вроде NDJSON (по одному JSON-объекту на строку) и JSON-стримов отдают НЕ один документ, а конвейер документов подряд — {"n":1}{"n":2}: Unmarshal съест только первый и подавится вторым, а Decoder прожуёт их циклом: for { err := dec.Decode(&v); if err != nil { break } } — выход из цикла по ошибке, которая в конце потока и есть io.EOF, штатный сигнал конца из прошлого урока.

Вторая причина — память и латентность: Decoder не держит весь документ целиком, он читает ровно столько байтов, сколько нужно для следующего значения; гигабайтный лог JSON-строками можно обрабатывать построчно-потоково, не грузя файл в память, — в связке с bufio.Scanner из прошлого урока это стандартный жанр обработки больших выгрузок. Третья — настройки: у Decoder есть методы вроде dec.DisallowUnknownFields(), превращающий молчаливое игнорирование незнакомых полей в ошибку, — строгий режим для контрактов, где опечатка в ключе должна быть громкой, а не тихой.

Когда какой способ выбирать — правило простое. Один JSON-объект, уже лежащий в байтах (os.ReadFile, []byte из ответа, который вы всё равно прочитали целиком) — Unmarshal: одна строка, ноль церемоний. Поток из многих значений, источник без конца (сеть), документ слишком велик для памяти или нужны строгие настройки — Decoder. У Encoder/Decoder есть и младший брат: json.MarshalIndent(v, "", " ") — тот же Marshal с отступами для людей: логи, диффы, отладочные дампы. Для машинных ответов отступы — просто лишние байты.

Последний инструмент урока — json.RawMessage. По определению это просто синоним []byte, но с двумя суперспособностями: при МАРШАЛИНГЕ RawMessage вставляется в вывод КАК ЕСТЬ, сырыми байтами, без повторного кодирования; при ДЕКОДИРОВАНИИ RawMessage забирает кусок JSON целиком, не разбирая его. Классический паттерн — конверт: обёртка с известными полями kind и body, где форма body зависит от kind. Структура объявляет Body json.RawMessage, Unmarshal разбирает только конверт, а вы, посмотрев на e.Kind, отправляете e.Body на второй Unmarshal — уже в конкретный тип. Один разбор — два прохода, каждый со своей формой.

Зачем не map[string]any? Карта разбирает ВСЁ сразу и прячет типы за float64 и утверждениями; RawMessage сохраняет точные байты — их можно передать дальше, положить в другую структуру, залогировать дословно или разобрать лениво, только когда ветка кода действительно понадобилась (не разбирали — не платили). Это техника «отложенного решения», и в больших системах она экономит и время, и нервы: парсер конвертов не знает о тысяче видов body, а каждый обработчик знает только свою.

Граница применимости честная: RawMessage — инструмент для ДВУХЭТАПНОГО разбора и прозрачной пересылки. Если форма известна заранее — структура проще и надёжнее; если форма неведома и нужна возня с полями — карта честнее. RawMessage занимает нишу между ними: форма известна ПОЗЖЕ, а не никогда. И маленькая деталь на память: RawMessage в структуре с omitempty не прячется — nil-срез выйдет как null; если пустой конверт должен быть без body, чистите поле руками или используйте указатель *json.RawMessage.

Соберём урок в одну карту. Кодирование: json.Marshal — значение в []byte, теги называют ключи, omitempty прячет нулевые (но не структуры), неэкспортируемое поле не выходит вовсе, ключи карт сортированы, []byte превращается в base64. Декодирование: json.Unmarshal — байты в значение по адресу, незнакомые ключи молча мимо, типы приводятся к типам полей, а в map[string]any всё живёт динамикой с float64-числами. Поток: Encoder пишет в Writer (SetEscapeHTML(false) для точных байтов, \n в конце), Decoder читает из Reader по одному значению до io.EOF. Отложенный разбор: json.RawMessage хранит сырые байты между двумя проходами. И весь урок держится на прошлом: JSON — байты UTF-8, os.ReadFile их доставляет, контракт io.Reader делает их потоком.

Двадцать второй урок — HTTP-клиент: http.Get, http.Client, таймауты и чтение ответа. Связка самая прямая в курсе: тело ответа — это io.Reader, и живой жанр «запросил API — декодируй ответ» собирается из двух уроков подряд: resp.Body отдаёт байты, json.Decoder или Unmarshal превращает их в структуры. Вы уже умеете вторую половину; скоро появится первая. А если хочется увидеть JSON в роли сервера — урок про JSON-ответы в Gin показывает ту же encoding/json с другой стороны очереди: теги, omitempty и PureJSON на настоящих хендлерах.

До встречи на странице курса. Если захочется освежить байтовую базу — урок про файлы и ввод-вывод: os.ReadFile, поток и EOF — то, во что JSON упирается с обеих сторон. А если станет интересно, как Marshal вообще видит ваши поля и теги — урок про рефлексию: reflect.TypeOf, reflect.Value и StructTag — три инструмента, из которых encoding/json собран внутри.