Интеграция с фреймворками (net/http)

Разберём сам факт до конца. Первый аргумент возврата NewNoteServiceHandler — путь /notes.v1.NoteService/ — строка, под которой зарегистрированы все процедуры сервиса; второй — http.Handler, который принимает каждый вызов, разбирает протокол (Connect, gRPC или gRPC-Web — механика четвёртого урока) и диспатчит на ваш implementation. Связка connect net http буквальна до конца: так как это http.Handler, к нему применимо всё, что вы знаете о net/http, и это не метафора, а буквальная замена компонентов: http.Server с TLS-конфигом из тринадцатого урока обслуживает RPC-вызовы тем же кодом, что и статику; middleware из любого учебника по Go оборачивают его без единой правки; httptest.NewServer из шестнадцатого урока поднимает его для тестов той же строкой, что и обычный роутер. Обратная сторона той же медали: ограничения net/http тоже ваши — таймауты сервера, лимиты заголовков, поведение при паниках, модель горутин на соединение. В gRPC-мире интеграция с обычным HTTP-миром — проект: grpc-go живёт в своей горутине с своим транспортом, и совместный mux требует cmux или отдельных портов. В connect-мире вопрос «как поставить RPC рядом с health-check и метриками» — это одна пара mux.Handle. Именно за это свойство Connect ценят в командах со смешанной инфраструктурой: RPC-сервис не требует изменений в платформе, которая уже гоняет HTTP.

Стандартный http.ServeMux после Go 1.22 вырос из игрушки в рабочий инструмент, и для многих сервисов этого достаточно: паттерны с методом (GET /healthz), сегменты-подстановки (/users/{id} и r.PathValue("id")), завершающий слэш-суффикс {path...} для префиксов. Если ваш сервис — RPC плюс пара служебных роутов, депенденси не нужен: ServeMux лёгок, предсказуем и уже в рутине. chi приходит, когда нужен настоящий роутинг-стек: группы роутов с middleware на группу, вложенные маршруты, сотни роутов с общими префиксами, комбинаторика middleware по поддеревьям. Echo — когда команда уже живёт в его экосистеме: те же группы, свой контекст запроса, свои хелперы ошибок, обширная коллекция middleware. Важно понимать цену выбора: всё это — роутеры поверх net/http, они принимают http.Handler и отдают http.Handler, поэтому connect-хендлер садится в них нативно, без адаптеров — интеграция connect сводится к одному вызову в каждом фреймворке. Отдельный жанр — REST-соседи RPC: на том же mux удобно держать несколько публичных GET-роутов для простых клиентов; полноценный REST-шлюз над proto-схемой — тема двадцать первого урока, там же сравнение с grpc-gateway, а сейчас — только соседи по роутеру.

Middleware net/http — это функция вида func(http.Handler) http.Handler: принимает следующий обработчик, возвращает обёрнутый. Внутри — замыкание с вашей логикой до и после next.ServeHTTP: до — подготовка (таймер, контекст, лимиты), после — фиксация (лог, метрика), вокруг — защита (recover). Композиция — матрёшка: withLogging(withRecovery(mux)) означает, что logging снаружи, recovery внутри, mux в центре; запрос проходит logging → recovery → mux, ответ — обратно. Порядок — это контракт, как у WithInterceptors из седьмого урока: внешний слой видит весь жизненный цикл запроса, включая то, что внутренние слои сделали с ответом. Классическая пара — recovery внутри logging: тогда лог-строка пишется и для паниковавших запросов, после того как recovery их погасил и вернул 500. Поменяйте порядок — и запрос с паникой останется без лог-строки: внешний recovery погасит её раньше, чем logging увидит запрос. Дежурная коллекция middleware: logging с длительностью, recovery с честным 500, лимит тела http.MaxBytesReader, таймаут через http.TimeoutHandler (с оговоркой для стримов — ниже), заголовки безопасности. Всё это живёт на уровне HTTP: middleware не знает ни процедур, ни сообщений — он видит пути и статусы, и это нормальная точность для его задач.

Седьмой урок построил карту, тринадцатый закрепил её в FAQ — теперь она стала кодом, и стоит сформулировать правило одной строкой: то, что про HTTP, — в middleware; то, что про вызов RPC, — в интерсептор. В middleware: recovery (защита всего процесса HTTP, включая соседей по mux), логирование на уровне путей и статусов, редиректы, заголовки ответа, CORS для браузерной границы из девятого урока, лимиты соединений. В интерсепторах: аутентификация и авторизация с req.Spec().Procedure, логирование с процедурой и кодом, метрики вызовов из семнадцатого урока, ретраи и трассировка на клиенте. Два критерия помогают решать пограничные случаи. Критерий видимости: если логике нужна процедура или сообщение — интерсептор, middleware их не видит. Критерий стороны: интерсепторы работают и на клиенте (клиентская луковица из седьмого урока), middleware — только на сервере; логика, нужная обоим концам, живёт в интерсепторе. Пограничный жанр — таймауты: per-call дедлайн ставит клиент контекстом из пятого урока, сервер его уважает автоматически; общий таймаут HTTP — http.TimeoutHandler, но для стримов из восьмого урока он вреден: длинный bidi-поток убьётся по таймеру даже при активном обмене, поэтому глобальный таймаут либо ставят только на unary-подобные пути, либо держат дедлайны на уровне контекста вызова.

Посадка в популярные роутеры — по одному вызову, потому что все они живут на http.Handler. chi: r.Handle(path, handler) или r.Mount(prefix, handler) для поддерева; middleware chi — через r.Use(withLogging, withRecovery) — и connect-хендлер оказывается внутри всей цепочки автоматически. Echo: e.Any(path, echo.WrapHandler(handler)) — обёртка из коробки; с middleware echo.WrapMiddleware если хотите вклинить echo-хендлер в общий слой. Gin: r.Any(path, gin.WrapH(handler)) — симметричная обёртка. Во всех трёх случаях путь RPC-хендлера берётся у генератора, как и со стандартным mux, и клиенты не замечают, на каком роутере живёт сервер. Честный разговор про fiber: он не построен на net/http — fiber стоит на fasthttp, другой реализации HTTP с другими интерфейсами; connect-хендлер в него не вставляется напрямую, нужен адаптер fasthttp-to-net/http с конвертацией контекста, а это трение, дублирование и риск в горячем пути. Практический вывод курса: connect-сервис держите на net/http-стеке (чистый ServeMux, chi, echo, gin — что угодно из http.Handler-мира), а fiber — для сервисов, где Connect не участвует. Ключевая фраза для поиска в доках — connect middleware: раздел интеграции показывает ровно эти обёртки для каждого фреймворка.

Реальный бэкенд — не один сервис, и mux справляется с этим без церемоний: NewNoteServiceHandler и, скажем, NewUserServiceHandler монтируются рядом, у каждого свой путь из имени пакета — /notes.v1.NoteService/ и /users.v1.UserService/ — маршрутизация автоматична, как и для версий из восемнадцатого урока, которые вы можете смонтировать тут же третьей и четвёртой парой. Префикс появляется, когда деплой-топология требует общего сегмента пути: API-шлюз снимает свой префикс, или все RPC живут под /rpc, или версия деплоя видна в пути. Инструмент — http.StripPrefix: внешний mux маршрутизирует по префиксу и срезает его перед внутренним mux, где хендлеры зарегистрированы под своими родными путями; критично, чтобы базовый URL клиентов содержал тот же префикс, иначе внешний mux не найдёт путь. Обратный вариант — mount без StripPrefix: если внутренний хендлер умеет жить с префиксом (chi Mount так делает сам), обёртка не нужна. Практический совет: один префикс на всю RPC-плоскость проще, чем разные, — тогда ingress-правила из двадцать второго урока будут однострочными, а дашборды метрик из семнадцатого будут читать procedure без сюрпризов. Помните также, что mux.ServeHTTP линейно перебирает паттерны — на сотнях роутов это не проблема, но измеряйте, если подозреваете маршрутизацию в профиле CPU.

Сценарий из тринадцатого урока: TLS терминируется на ingress, дальше к сервису едет plaintext HTTP. Тут ждёт подводный камень, который кусает всех, кто гоняет gRPC-жанры: grpc-клиент требует HTTP/2, а net/http по умолчанию говорит HTTP/2 только поверх TLS; plaintext-соединение сервер умеет только в HTTP/1.1 — и gRPC-вызовы за Terminating-TLS-балансировщиком падают с загадочными ошибками протокола. Connect-протокол из четвёртого урока неприхотлив — он работает и на HTTP/1.1, это осознанное свойство дизайна, — но если ваши жанры включают gRPC или gRPC-Web для старых клиентов, сервер должен уметь HTTP/2 без TLS. Ответ — h2c: пакет golang.org/x/net/http2/h2c, обёртка h2c.NewHandler(mux, &http2.Server{}) перед ListenAndServe. Она позволяет серверу принять HTTP/2-апгрейд или prior-knowledge соединение на plaintext-порту — и gRPC-жанры оживают за TLS-балансировщиком при одном условии: ingress обязан проксировать HTTP/2 внутрь, а не даунгрейдить до 1.1; это настройка ingress, и в двадцать втором уроке она займёт своё место в деплой-чек-листе. Запомните трио: TLS на границе, h2c внутри, HTTP/2-проксирование в ingress — стандартная топология gRPC-совместимых сервисов на Connect.

Последние два слоя интеграции — жизнь и смерть сервиса. Health-checks: на том же mux живут GET /healthz (жив ли процесс) и по желанию /readyz (готов ли принимать трафик) — обычные http.HandlerFunc без единой connect-строки; оркестратор пингует их, а RPC-плоскость остаётся чистой от служебных маршрутов. Готовность честнее всего связывать с реальными зависимостями: проверка коннекта к базе с таймаутом в полсекунды — но держите её лёгкой, readiness пингуют часто. Выключение: graceful shutdown — это гарантия, что деплой не рвёт активные вызовы. Схема: http.Server с h2c-обёрткой, сигнал SIGTERM ловится signal.NotifyContext, затем srv.Shutdown(ctx) — сервер перестаёт принимать новые соединения и ждёт активные до дедлайна контекста; для RPC-мира важна деталь: unary-вызовы успевают завершиться за типичный grace-период 15-30 секунд, а долгие bidi-стримы не закончатся сами — их гасит дедлайн, и клиент из пятого урока обязан переживать обрыв ретраем или переподключением; держите grace-период больше p99 длительности unary из семнадцатого урока — вот где метрики встречаются с деплоем. После Shutdown закрываются ресурсы: базы, кэши. Кейсы, когда Shutdown не спасает: незакрытые стримы без дедлайнов — ставьте таймаут на контекст стрима; клиенты без ретраев — деплой всё равно переживут благодаря балансировщику, выводящему поду из ротации до сигнала, — это связка readiness и деплоя, её разбор в двадцать втором уроке.

Интеграция закрыта со всех сторон: хендлер стоит на общем mux с healthz и метриками, middleware и интерсепторы делят границу ответственности, h2c открывает gRPC-жанры за TLS-ingress, graceful shutdown выключает сервис без разрыва вызовов. Дальше по курсу — миграция с gRPC на Connect: пошаговый план переезда существующего сервиса, где сегодняшняя тема станет фундаментом — хендлеры двух миров встанут на один mux на время перехода. Потом — REST-шлюз и HTTP-совместимость, деплой с ingress и HTTP/2 на границе. Для повторения: первый монтаж и структура проекта — в третьем уроке, три протокола и их требования к HTTP — в четвёртом, TLS-топология — в тринадцатом, httptest для проверки всей сборки — в шестнадцатом. Программа всех двадцати пяти уроков — на странице курса.