grpc-gateway

gRPC-Gateway — плагин для protoc и Go-библиотека из проекта grpc-ecosystem, которая читает определения gRPC-сервисов, аннотированных опциями google.api.http в .proto-файлах, и генерирует реверс-прокси HTTP/JSON-сервер, транслирующий RESTful HTTP-запросы в gRPC-вызовы. Добавив option (google.api.http) = { get: "/v1/users/{id}" } к RPC-методу в Protobuf-определении, разработчики могут обслуживать как gRPC-эндпоинт (используемый внутренними Go-микросервисами), так и REST-эндпоинт (для веб-браузеров или сторонних клиентов) из единой реализации сервиса без написания кода трансляции вручную. Сгенерированный код шлюза использует стандартный пакет net/http и естественно интегрируется с маршрутизаторами Gin, Echo или Chi для добавления middleware аутентификации, ограничения частоты запросов и трассировки OpenTelemetry. gRPC-Gateway поддерживает тела запросов/ответов в Protobuf и JSON, query-параметры, path-параметры и HTTP-заголовки, отображаемые на gRPC-метаданные, покрывая всю поверхность трансляции REST-в-gRPC. Для архитектур Golang-микросервисов, предоставляющих как внутренние gRPC API, так и публичные REST API, gRPC-Gateway устраняет необходимость поддерживать две отдельные реализации серверов и два набора определений типов запросов/ответов.

Как это работает

grpc-gateway — HTTP/2-based RPC с Protocol Buffers (.proto) как языком схемы. protoc + protoc-gen-go-grpc генерируют Go-server + client stubs из .proto-файлов. Streaming-варианты (unary, server-streaming, client-streaming, bidi). Reflection для introspection (grpcurl). Connect-go (альтернатива Buf) даёт gRPC-совместимые HTTP/1 + HTTP/2 серверы — interoperable с gRPC-клиентами. gRPC-Gateway экспонирует gRPC-сервисы как REST + OpenAPI.

Когда применять

gRPC — для internal service-to-service, когда важны latency + schema-дисциплина; типизированные контракты ловят много багов на compile time. В паре с Buf — для build + lint proto-файлов. Для публичных API — gRPC-Gateway или Connect для REST/HTTP рядом. Для browser-to-server Connect-go чище, чем gRPC-Web. Избегайте gRPC для одноразовых скриптов или крошечных сервисов — REST проще.

Типичные ошибки

Ловушки grpc-gateway: регенерация proto-файлов без коммита (CI ломается из-за отсутствия сгенерированного кода); breaking changes в .proto без bump версии (клиенты валятся непонятным образом); огромные proto-пакеты, затрагивающие каждый сервис на изменение; игнор context.Context deadlines (вызовы висят навеки).

Связанные понятия

• gRPC и Protobuf
• Protobuf и protoc
• gRPC сервер и клиент
• Streaming RPC