HTTP-транспорт

Вспомни луковицу из первого урока: транспорт — внешний слой, привязанный к протоколу. В пакете transport/http (в коде его обычно импортируют с алиасом kithttp) транспорт go kit сводится к трем сигнатурам. NewServer(endpoint, decode, encode, options...) принимает endpoint и две функции, возвращая Server — обычный http.Handler. DecodeRequestFunc — func(context.Context, http.Request) (interface{}, error): декодер превращает HTTP-запрос в request-структуру, которую ждёт адаптер. EncodeResponseFunc — func(context.Context, http.ResponseWriter, interface{}) error: энкодер сериализует response-структуру в ответ. Всё. Ни роутера, ни миддлварь-цепочки, ни магии привязок: транспорт — это три функции, и ровно они единственные в проекте знают про тело запроса и заголовки. Такой размен — многословность за явность — и есть фирменный стиль go kit http: замени gRPC — поменяются три функции, сервис и endpoint'ы останутся нетронутыми.

Заглянем в server.go пакета transport/http — там меньше сотни строк, и полезно понимать путь запроса. ServeHTTP берёт r.Context(), прогоняет через ServerBefore-функции (о них ниже), затем вызывает декодер: получил request — передал его в endpoint вместе с контекстом; ошибка декодера — сразу в error encoder, endpoint не зовётся. Дальше ответ попадает в энкодер, а его ошибка уходит в ServerErrorHandler — обычно в логгер, потому что заголовки уже уехали и клиенту сказать нечего. Четыре серверных опции дополняют картину: ServerBefore добавляет в контекст значения из запроса — путь, заголовки, auth; ServerAfter срабатывает после ответа — туда лягут метрики и трейсинг в уроках 07–08; ServerErrorEncoder подменяет то, как ошибка превращается в HTTP-ответ; ServerErrorHandler ловит ошибки энкодера. Правило чтения простое: NewServer — это конвейер декодер → endpoint → энкодер с четырьмя хуками по краям, и все хуки транспортные, к домену отношения не имеют.

Декодер получает *http.Request и возвращает request-структуру — вот и весь контракт. Что здесь легально: json.NewDecoder(r.Body).Decode(&req) для POST-тел, r.URL.Query() для GET-параметров, переменные маршрута, если роутер их умеет, заголовки — например, Authorization, который потом уйдёт в контекст. Три практики, которые сэкономят нервы. Первая: тело читается один раз — декодер обязан, а не «может» прочитать r.Body до конца, иначе keep-alive-соединения начнут гнить; json.NewDecoder делает это сама. Вторая: возвращай примитивные структуры ровно того типа, что ждёт адаптер из урока 02 — любой mismatch выстрелит паникой assertion, и это будет твоя вина, не go-kit. Третья: ошибки декодера — это транспортный сбой, они идут по error-каналу и по умолчанию превращаются в 500; кастомизируем это на следующем уроке кодеков. Для GET-эндпоинтов тело пустое — декодер просто собирает структуру из query, и это нормально: декодер — не ритуал JSON, а переводчик HTTP в домен.

Энкодер симметричен: получает response-структуру и пишет её в http.ResponseWriter. Базовая форма — три строки: выставить Content-Type: application/json; charset=utf-8 и вернуть json.NewEncoder(w).Encode(response). Заученная ловушка HTTP здесь прячется в порядке операций: первый же вызов, который пишет в тело, триггерит неявный WriteHeader(200) — после этого менять заголовки бессмысленно, они уже отправлены. Поэтому Set — всегда до Encode, а явный WriteHeader — только если хочешь статус отличный от 200. Ошибка, которую возвращает энкодер, — отдельная история: когда Encode падает (клиент отвалился, срез по конвейеру), заголовки уже ушли, сообщить клиенту нечего — ошибка попадает в ServerErrorHandler и логируется. Статус по умолчанию 200 устраивает счастливый путь; несчастливый — следующий раздел, и там появится таблица codeFrom.

Сведём всё, что знает транспорт go kit об ошибках, — тут три принципиально разных маршрута. Первый: ошибка декодера — сломанный JSON, недостающий параметр; она возвращается из DecodeRequestFunc, endpoint не вызывается, а ответ формирует error encoder. По умолчанию работает DefaultErrorEncoder: статус 500 и текст ошибки в text/plain — нечестно для плохого запроса, поэтому следующий урок посвятим собственному ErrorEncoder через опцию ServerErrorEncoder. Второй: бизнес-ошибка из response-структуры — Failed() != nil; её ловит наш encodeResponse и кодирует через encodeError со статусом из codeFrom. Третий: err endpoint'а — инфраструктурный сбой; он тоже уходит в error encoder, и это правильно: база недоступна — клиенту честный 500, а breaker'у на клиентской стороне — сигнал. Сравни с gin, где c.JSON и c.Abort размазаны по хендлерам: здесь кодирование ошибки — функция с таблицей статусов, единая для всех эндпоинтов. Такая дисциплина делает поведение API предсказуемым: одинаковые ошибки — одинаковые ответы на любом транспорте.

NewServer возвращает http.Handler — значит, go-kit не отбирает маршрутизацию, и это решение FAQ, а не случайность. Стандартный http.NewServeMux тянет простые проекты; gorilla/mux и chi добавляют переменные пути и middleware уровня роутера; gin можно смонтировать обёрткой его хендлера, если команда уже на нём живёт. Два практических замечания. Методы: mux.Handle не ограничивает метод — POST/GET различаются на уровне роутера (gorilla: r.Methods("POST")), иначе декодер JSON встретит GET с пустым телом и честно вернёт ошибку декодера. Переменные пути: если нужен /profiles/{id}, бери роутер с параметрами и передавай их в request-структуру из декодера — домен и endpoint по-прежнему не видят URL. Пара NewServer + чужой роутер — типовой гибрид больших проектов: go-kit отвечает за слои и обёртки, роутер — за маршруты. В уроке 13 тот же endpoint посадим на gRPC, и станет видно, зачем всё это разделение.

Осталось два хука, на которые в этом уроке только смотрим. ServerBefore принимает RequestFunc — функцию func(ctx context.Context, r *http.Request) context.Context — и вызывается до декодера: здесь берут из запроса то, что относится к условиям вызова, а не к данным — заголовок Authorization, X-Request-ID, путь. Значение кладётся в контекст с ключом и едет вниз через endpoint в сервис. ServerAfter — зеркальный хук после ответа: func(ctx, response) — туда ложатся метрики и трейсы. Зачем это знать сейчас: чтобы не соблазниться положить данные запроса в декодере в ctx — данные едут в request-структуре, условия вызова — в контексте через ServerBefore. Практика появится по делу: идентификатор запроса — в уроке 06 про логи, спаны трейсинга — в 08, JWT — в 23. Сегодня достаточно прочитать опции в сигнатуре NewServer и не бояться их.

stringsvc отвечает по сети: POST /uppercase и GET /count работают, статусы честные, слои не слиплись. Но дефолты транспорта видны: плохой JSON уезжает с 500, а кодирование ошибок умещается в один case. Следующий шаг — урок 05-codeki: свой ErrorEncoder, аккуратные JSON-ошибки и правила кодеков. Освежить Basis можно в уроке 02-endpoint — теперь ты знаешь, кто вызывает адаптеры, — а карта курса лежит в уроке 01-filosofiya и на странице курса. Транспорт был последним недостающим слоем — дальше курс надевает на них наблюдаемость.