REST-шлюз и HTTP-совместимость

Механика grpc-gateway: в proto рядом с rpc пишется аннотация google.api.http — какой HTTP-метод и путь соответствует процедуре и как поля сообщения раскладываются по пути, query и телу. Генератор protoc-gen-grpc-gateway выдаёт runtime-код: http-роутер, который принимает HTTP-запрос с JSON, собирает из него protobuf-сообщение и делает gRPC-вызов к бэкенду. То есть gateway — полноценный реверс-прокси: свой процесс или sidecar, свой порт, свои таймауты, своя схема ошибок, которую надо трансформировать в HTTP-статусы и не дать ей расползтись с реальностью бэкенда. Практическая деталь: gateway-роутер можно держать и в том же процессе, что и gRPC-сервер — mux соседствует с grpc-сервером через отдельные порты, но это не отменяет второй кодогенерации и второй схемы ошибок. Бонусы честные: точный контроль REST-контракта — красивые пути вроде /v1/notes/42, кастомные префиксы, версии в пути; и генерация swagger/OpenAPI из тех же аннотаций для внешних партнёров. Цена тоже честная: второй стек кодогенерации в CI, второй артефакт в деплое, лишний хоп латентности, стримы gateway не проксирует — только unary, и двойная схема ошибок, которую надо синхронизировать руками. Это инструмент слоя перевода, и использовать его стоит тогда, когда слой перевода действительно нужен.

Connect переворачивает задачу: шлюз не нужен, потому что HTTP — родная среда протокола. connect rest — это когда тот же хендлер принимает обычный POST с JSON: путь процедуры /notes.v1.NoteService/GetNote, тело — сообщение в protojson, ответ — JSON обратно. curl-однострочник вместо клиента, монитор без рантайма, быстрый дебаг на проде — без единой аннотации и без прокси. Ошибки шестого урока уже замаплены на HTTP-статусы: not_found приедет 404-м, unauthenticated — 401-м, resource_exhausted — 429-м, с JSON-телом, где код и сообщение читаются глазами. Браузерный клиент из девятого урока говорит тем же протоколом — connect-web ходит прямо на хендлер, CORS настраивается middleware из девятнадцатого урока; gRPC-шлюзу для браузера понадобился бы ещё и grpc-web-прокси. protojson-нюансы из восемнадцатого урока в силе: int64 и 64-битные целые — строки, enum — строковые имена, camelCase по умолчанию, json_name переименовывает поля в JSON. Отдадим должное: путей вида /v1/notes/42 здесь нет — пути процедурные; это плата за отсутствие аннотаций, и о компенсациях ниже. Ещё одна приятность жанра: запрос можно повторить той же командой из истории shell — идемпотентные чтения не создают дублей, а ответ виден прямо в терминале вместе со статусом; дежурный решает инцидент, не разворачивая клиентов. Платформенный бонус: тот же JSON-жанр слушают мониторы и smoke-тесты пайплайна — им не нужен protobuf-рантайм, только curl и адрес.

POST на чтение режет кэширование: браузер, CDN и обратный прокси по умолчанию не кэшируют POST. Connect даёт управляемый ответ: в proto у процедуры ставится option idempotency_level = NO_SIDE_EFFECTS — и для Connect-жанра клиент начинает слать GET с сообщением, закодированным в query-строке, а хендлер принимает его без дополнительных флагов: генерация, клиент и сервер читают опцию из дескриптора. GetNote становится честным GET /notes.v1.NoteService/GetNote?noteId=42 — HTTP-кэши между клиентом и сервером работают по стандартным правилам, повторная отправка безопасна по определению. Ограничения умные. Первое: работает только Connect-жанр — gRPC и gRPC-Web в принципе не знают GET-вызовов и продолжают POST. Второе: query-кодирование накладывает размерные пределы URL, поэтому NO_SIDE_EFFECTS ставят на лёгкие read-процедуры с простыми полями, а не на запросы с большими фильтрами и вложенными структурами. Третье: идемпотентность — семантическое заявление, а не магия; PutNote с естественной идемпотентностью можно пометить тоже, если повтор возвращает тот же результат. Это противовес аннотациям gateway: не кастомный путь, а стандартный процедурный GET с кэшируемостью.

JSON-слой Connect — не своя выдумка, а protojson-канон protobuf: camelCase-имена по умолчанию, json_name из восемнадцатого урока переименовывает поле для JSON, 64-битные целые — строки, потому что JavaScript не умеет точные int64, enum — строковые имена, bytes — base64, отсутствующее поле — отсутствие ключа, а не null. REST-клиент на python-requests читает ответ без сюрпризов, если его автор помнит про int64-строки; ошибка приходит HTTP-статусом и JSON-телом с кодом — те же коды, что gRPC-клиент видит в заголовках grpc-status. Сравнение с gateway честное: у gateway трансляция ошибок настраивается руками и часто расползается с реальностью бэкенда после рефакторингов; у Connect это один код-путь в хендлере, который обслуживает все жанры сразу. curl-режим делает JSON-слой ещё и инструментом диагностики: любой ответ читается глазами без декодера, и тот же вызов, что в шпаргалке дежурного, служит контрактом для монитора. Если нужны документы API — пятнадцатый урок показывал генерацию OpenAPI из дескрипторов, без аннотаций. Отдельный жанр задач — отладка чужих интеграций: партнёр присылает скриншот ответа, и JSON-канон позволяет понять глазами, что поле пришло строкой, а не числом, без декодера и без repro-скрипта; в gRPC-мире для того же понадобился бы дамп трафика с декодированием.

Честный ответ на «зачем тогда grpc-gateway»: когда внешний REST-контракт уже существует и его нельзя менять. Партнёрская интеграция со спекой GET /v1/notes/{id}?include=tags, платформенная политика «публичные API только в /v1», OpenAPI-документ, сгенерированный из аннотаций и розданный клиентам, — в этих случаях gateway легален и полезен: он ставит слой перевода между стабильным REST-контрактом и живущей своей жизнью proto-схемой. Второй легальный случай — тяжёлые требования к путям и методам, которые опциями proto не выразить. Гибрид тоже рабочий: connect-хендлер на общем mux из девятнадцатого урока обслуживает RPC и браузерных клиентов, а gateway смонтирован рядом на те две-три процедуры, у которых есть внешний REST-контракт; либо ещё проще — пара обычных http.HandlerFunc-роутов рядом с RPC, если внешний контракт тривиален, с r.PathValue для сегментов пути. Такие соседи-роуты живут под тем же TLS и тем же логированием, что и RPC, и не требуют нового ingress-правила. Антипаттерн один: тянуть gateway ради «чтобы был», когда реальных REST-клиентов ноль — тогда это второй артефакт, второй порт и вторая схема ошибок без единой пользы.

HTTP-поверхность закрыта с двух сторон: из коробки — процедурные JSON-вызовы и GET-кэширование, по требованию — gateway под внешний контракт. Дальше — деплой: Docker, ingress, HTTP/2 на границе и TLS, где JSON-поверхность и gRPC-жанры встречаются с реальным трафиком. Для повторения: жанры и маршрутизация по Content-Type — в четвёртом уроке, ошибки и статусы — в шестом, браузерный клиент и CORS — в девятом, json_name и совместимость схемы — в восемнадцатом, mux и http.HandlerFunc-соседи — в девятнадцатом. Программа всех двадцати пяти уроков — на странице курса.