JSON API: парсим и отдаём JSON

Ответ JSON-ом — три строки, и порядок в них жёсткий. Сначала w.Header().Set("Content-Type", "application/json") — заголовки можно менять только до первой записи в w. Потом w.WriteHeader(http.StatusCreated) — отправка статус-строки и заголовков клиенту; с этого момента заголовки заморожены, а повторный WriteHeader приводит к строке «superfluous WriteHeader» в логе сервера. Наконец json.NewEncoder(w).Encode(note) — энкодер получает ResponseWriter как io.Writer и пишет сериализованный объект прямо в сеть, без полной копии в памяти. Статус 201 Created — не украшение: он означает «ресурс создан», и клиентские библиотеки, генераторы типов и мониторинг читают его как сигнал. Пропустите WriteHeader — Go отправит 200 по умолчанию, и REST-контракт «создано» потеряется. Пропустите Set Content-Type — самая дорогая из ошибок урока, о ней отдельная врезка ниже. Сам Encode, кроме объекта, дописывает в конец один символ переноса строки — деталь, которая всплывёт в тестах.

Входящий JSON читает json.NewDecoder(r.Body): декодер наворачивается на поток тела и раскладывает значения в структуру через Decode(&req). Три факта, которые экономят часы. Первый: Decode читает ровно одно JSON-значение — если клиент прислал два объекта подряд, второй останется в теле непрочитанным; для API это нормально, но знать стоит. Второй: пустое тело возвращает io.EOF — ту же ошибку, что и битый JSON, и обе ветки ведут в один ответ 400. Третий: Decode не закрывает тело запроса, и закрывать его в хендлере не нужно — документация net/http прямо снимает эту заботу с хендлера: Server закроет Body сам. Привычка из клиентского кода, где resp.Body закрывает вызывающий, на серверной стороне не работает. Ошибка Decode — почти всегда вина клиента, и код ответа соответствующий: 400 Bad Request, ровно как на битом id из пути в уроке про параметры.

Content-Length в заголовке запроса обещает размер, но обещание не гарантия: при chunked-кодировке заголовка нет вообще, а прокси и шлюзы умеют менять тело. Хендлер, который доверяет Decode без лимита, предлагает злоумышленнику отправить гигабайт JSON и съесть столько же памяти. Стандартное лекарство — http.MaxBytesReader(w, r.Body, 1<<20): обёртка над телом с потолком в 1 048 576 байт; запись 1<<20 — идиоматичное «один мегабайт», а число выбирается по самому большому легитимному запросу вашего API. При превышении Read возвращает ошибку «http: request body too large», а с Go 1.19 она имеет тип *http.MaxBytesError и ловится через errors.As. Тонкость из исходников: сервер при превышении помечает соединение на закрытие (Connection: close) и рвёт его после вашего ответа — статус при этом выбираете вы, автоматического 413 у сервера нет.

Спор, который делит команды на два лагеря. Стриминговая пара NewEncoder/NewDecoder не держит ответ в памяти целиком: байты уходят в сеть по мере сериализации, и для больших выгрузок это единственный вариант без лишних копий. Против — json.Marshal и Unmarshal: []byte перед глазами, его можно обогатить перед записью, залогировать, сравнить в тесте без HTTP-слоя, положить в кэш. Моё правило: в хендлере — Encoder, потому что ответ пишется один раз и целиком; когда []byte нужен второй раз — Marshal. «Второй раз» — это ответ-конверт {"data": ..., "meta": ...} вокруг marshal-нутых данных, кэширование сериализованного результата, дублирование в лог для отладки. Граница нарушения понятна: маршихэл ради трёх строк ответа — лишняя аллокация и шум. Если теги, omitempty и вложенные структуры у вас со времён урока про JSON продвинутого курса не всплывали — загляните: encoding/json внутри хендлера ведёт себя точно так же.