Gateway и REST: аннотации google.api.http, пределы транскодинга, gRPC-Web и альтернатива ConnectRPC

Аннотации компилируются в прокси

Прежде чем писать рукописный REST-адаптер для gRPC-сервиса, спросите себя: что произойдёт, когда появится шестидесятый RPC? Именно этот вопрос делает генерируемый подход первым кандидатом для изучения.

Внешние потребители не поставят protoc. Стандартный ответ оставляет gRPC внутри и компилирует REST-фасад из того же контракта — аннотации google.api.http на каждом RPC:

import "google/api/annotations.proto";

service Orders {
  rpc GetOrder(GetOrderRequest) returns (Order) {
    option (google.api.http) = { get: "/v1/orders/{order_id}" };
  }
  rpc CreateOrder(CreateOrderRequest) returns (Order) {
    option (google.api.http) = { post: "/v1/orders", body: "*" };
  }
}

Правила привязки механические: переменные шаблона пути вроде order_id привязываются к одноимённому полю сообщения запроса; для GET каждое оставшееся скалярное поле становится принимаемым query-параметром; body: "*" отображает весь JSON-боди на сообщение запроса при записи. Из этого protoc-gen-grpc-gateway генерирует реверс-прокси — runtime.ServeMux, который сам по себе просто http.Handler, так что применимо всё из юнита про HTTP: оборачивайте в middleware, монтируйте под путём, ограничивайте по времени.

gw := runtime.NewServeMux()
// Дозванивается до gRPC-бэкенда; JSON на входе, protobuf по HTTP/2, JSON на выходе.
err := orderspb.RegisterOrdersHandlerFromEndpoint(ctx, gw, "orders:50051", dialOpts)
// Строка, которой не хватило в крючке, — никогда не проксируй без бюджета:
srv := &http.Server{Addr: ":8080", Handler: withTimeout(gw, 5*time.Second)}

На каждый запрос gateway делает: декодирует JSON в сгенерированную структуру запроса, вызывает RPC через настоящее клиентское gRPC-соединение (интерсепторы и клиентская балансировка прилагаются), кодирует ответ обратно в JSON. Есть и in-process-вариант — RegisterOrdersHandlerServer, вызывающий вашу серверную реализацию напрямую без дозвона; он экономит хоп, но обходит клиентские интерсепторы и статистику, поэтому большинство продакшен-схем держат настоящее соединение. Те же аннотации питают protoc-gen-openapiv2: публичный OpenAPI-документ генерируется из контракта, а не дрейфует от него.

Что отказывается переводиться: стримы, ошибки, дедлайны

Транскодинг честен с unary-вызовами и уклончив со всем остальным. Серверный стриминг технически работает: gateway отдаёт NDJSON-чанки (Newline-Delimited JSON — последовательность независимых JSON-объектов, разделённых переводом строки), каждый завёрнут в конверт result — это не JSON-массив, что ломает любого клиента, зовущего response.json() в ожидании одного объекта. Клиентский и bidi-стриминг не отображаются на request/response-REST вовсе; если они нужны браузеру, эндпоинту нужен другой дизайн — вебсокеты, gRPC-Web или Connect, а не аннотация gateway.

Ошибкам нужна таблица перевода, потому что два мира не согласны, что такое статус. Gateway поставляет дефолтный маппинг — InvalidArgument в 400, NotFound в 404, PermissionDenied в 403, Unavailable в 503, DeadlineExceeded в 504, Internal и Unknown в 500 — и кладёт в тело JSON google.rpc.Status. В день, когда публичному API понадобится собственный конверт ошибок, вы ставите runtime.WithErrorHandler и владеете маппингом сами; сделайте это осознанно один раз, а не по эндпоинту за раз.

Дедлайны — это крючок. REST-клиенты не шлют grpc-timeout; они просто вешают трубку, а повесивший трубку HTTP-клиент не отменяет автоматически вышестоящий RPC, если контекст запроса не прокинут насквозь, — и даже тогда неотвечающий бэкенд держит горутину, пока что-то её не ограничит. Gateway уважает входящий заголовок Grpc-Timeout, если он есть (от публичных клиентов — почти никогда), и поддерживает дефолт через runtime.DefaultContextTimeout или обычные таймауты http.Server/middleware. Правило, которое спасло бы крючок: прокси перед gRPC обязан порождать дедлайны, а не только пересылать их, потому что его публичные вызыватели не пришлют бюджет никогда.

Выбор топологии: gateway, gRPC-Web или Connect

Типовая продакшен-топология теперь видна целиком: сервисы говорят друг с другом на gRPC — скомпилированные контракты, распространяемые дедлайны, стримы, — а публичный край держит сгенерированный gateway, говорящий на REST и JSON с теми, кому .proto-файл в руки не дашь. Внутренние команды получают строгий контракт; внешние потребители — curl, OpenAPI-документацию и middleware с API-ключами на обычном http.Handler.

Браузеры всё усложняют. Браузерный fetch не умеет читать HTTP/2-трейлеры — а gRPC кладёт grpc-status ровно туда, — поэтому нативный браузерный gRPC невозможен независимо от поддержки HTTP/2. gRPC-Web (протокол-прослойка, перекладывающий статус из трейлеров в тело или заголовки) — обходной протокол: статус переезжает в тело или заголовки, а прокси (фильтр grpc_web у Envoy или gateway) переводит в настоящий gRPC. Работает — ценой ещё одной движущейся детали на каждом браузерном пути.

ConnectRPC — честная современная альтернатива всему этому бутерброду: один сервер говорит на трёх протоколах на одном порту — gRPC для существующих внутренних клиентов, gRPC-Web для браузеров без прокси и протокол Connect, где unary-вызов — обычный HTTP POST с JSON-телом, который можно дёрнуть curl-ом, а ошибки живут в теле ответа, не в трейлерах. Тот же .proto, другой сгенерированный рантайм. Размен — возраст экосистемы: у grpc-gateway десятилетие продакшен-шрамов, Connect моложе и беднее инструментами — но для новой Go-системы, которой нужны браузеры и curl-доступность, он вычёркивает gateway и Envoy-фильтр из архитектурной диаграммы.

Какой бы край вы ни выбрали, protobuf-first-поток оказывает тихое проектное давление, которое стоит назвать вслух: аннотации заставляют формулировать каждую операцию как путь ресурса и глагол, с явными сообщениями запроса и ответа. Команды, начинающие с REST, часто пропускают это моделирование и отращивают суп из глаголов; команды, компилирующие REST из контракта, получают ресурсную дисциплину, навязанную тулчейном.