gRPC-Gateway и OpenAPI
gRPC-Gateway и OpenAPI
gRPC отлично работает между микросервисами, но браузеры и легаси-клиенты не умеют гонять HTTP/2-streams и protobuf-payload-ы. gRPC-Gateway решает это: генерирует REST-прокси перед gRPC-сервисом, читая аннотации в .proto. Один и тот же сервис доступен и как gRPC (для микросервисов), и как REST (для фронтенда, мобильных, curl).
Не всё пробрасывается один-в-один: server-streaming Gateway отдаёт как поток JSON-строк, а bidirectional выставит только в урезанном виде (поток JSON в запросе и поток в ответе, без настоящего дуплекса поверх HTTP/1.1) - если методы сервиса построены на двустороннем стриминге, для браузера придётся делать отдельный WebSocket-эндпоинт.
Установка
go install \
github.com/grpc-ecosystem/grpc-gateway/v2/protoc-gen-grpc-gateway@latest \
github.com/grpc-ecosystem/grpc-gateway/v2/protoc-gen-openapiv2@latest
# В go.mod
go get github.com/grpc-ecosystem/grpc-gateway/v2
Аннотации в .proto
import "google/api/annotations.proto";
import "google/api/field_behavior.proto";
import "google/protobuf/empty.proto";
service UserService {
rpc CreateUser(CreateUserRequest) returns (CreateUserResponse) {
option (google.api.http) = {
post: "/v1/users"
body: "*"
};
}
rpc GetUser(GetUserRequest) returns (GetUserResponse) {
option (google.api.http) = {
get: "/v1/users/{id}"
};
}
rpc UpdateUser(UpdateUserRequest) returns (UpdateUserResponse) {
option (google.api.http) = {
patch: "/v1/users/{id}"
body: "user"
};
}
rpc DeleteUser(DeleteUserRequest) returns (google.protobuf.Empty) {
option (google.api.http) = {
delete: "/v1/users/{id}"
};
}
}
message GetUserRequest {
string id = 1 [(google.api.field_behavior) = REQUIRED];
}
Файлы google/api/annotations.proto, http.proto и field_behavior.proto в поставку protoc не входят (в отличие от google/protobuf/*.proto). Их берут из репозитория googleapis: скопируйте эти три файла в google/api/ рядом с вашими .proto (каталог, который передаётся в protoc -I). Если используете buf, достаточно добавить зависимость buf.build/googleapis/googleapis в buf.yaml. Без этого protoc упадёт с File not found.
{id} в URL автоматически биндится в поле id request-message. body: "*" означает «всё тело запроса в request-сообщение». body: "user" - только конкретное поле.
Генерация прокси-кода
protoc -I . \
--go_out . --go_opt paths=source_relative \
--go-grpc_out . --go-grpc_opt paths=source_relative \
--grpc-gateway_out . --grpc-gateway_opt paths=source_relative \
--openapiv2_out . --openapiv2_opt logtostderr=true \
proto/user.proto
Создаются: user.pb.go, user_grpc.pb.go, user.pb.gw.go (REST-прокси), user.swagger.json (OpenAPI спецификация).
Запуск Gateway-сервера
func main() {
ctx := context.Background()
// 1. Запускаем gRPC-сервер на :50051
go runGRPCServer()
// 2. Запускаем REST gateway на :8080
mux := runtime.NewServeMux()
opts := []grpc.DialOption{grpc.WithTransportCredentials(insecure.NewCredentials())}
if err := pb.RegisterUserServiceHandlerFromEndpoint(ctx, mux, "localhost:50051", opts); err != nil {
log.Fatal(err)
}
log.Println("REST gateway on :8080, gRPC on :50051")
log.Fatal(http.ListenAndServe(":8080", mux))
}
<?php
declare(strict_types=1);
namespace App\Controller;
use Symfony\Component\HttpFoundation\JsonResponse;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\Routing\Attribute\Route;
use User\CreateUserRequest;
use User\GetUserRequest;
use User\UserServiceClient;
use const Grpc\STATUS_NOT_FOUND;
use const Grpc\STATUS_OK;
#[Route('/v1/users')]
final readonly class UserController
{
public function __construct(
private UserServiceClient $client,
) {}
#[Route('', methods: ['POST'])]
public function create(Request $request): JsonResponse
{
$payload = json_decode($request->getContent(), true, flags: JSON_THROW_ON_ERROR);
$req = (new CreateUserRequest())->setName($payload['name'] ?? '');
[$response, $status] = $this->client->CreateUser($req)->wait();
if ($status->code !== STATUS_OK) {
return new JsonResponse(['error' => $status->details], 400);
}
return new JsonResponse(['id' => $response->getUser()->getId()], 201);
}
#[Route('/{id}', methods: ['GET'])]
public function get(string $id): JsonResponse
{
$req = (new GetUserRequest())->setId($id);
[$response, $status] = $this->client->GetUser($req)->wait();
return match ($status->code) {
STATUS_OK => new JsonResponse([
'id' => $response->getUser()->getId(),
'name' => $response->getUser()->getName(),
]),
STATUS_NOT_FOUND => new JsonResponse(['error' => 'not found'], 404),
default => new JsonResponse(['error' => $status->details], 500),
};
}
}
В мире PHP плагина «grpc-gateway» нет - REST-фасад пишут руками. Стандартная стратегия: Symfony (или Slim) обслуживает HTTP, внутри контроллеров вызывает gRPC-stub. Это даёт полный контроль над форматом ошибок, аутентификацией и rate limiting. Symfony-контроллер выглядит так.
# pip install fastapi uvicorn grpcio
# REST-фасад руками: FastAPI обслуживает HTTP, внутри обработчиков зовёт gRPC-stub.
# Сам gRPC-сервер на :50051 поднимается отдельным процессом (см. урок про основы).
import grpc
from fastapi import FastAPI, HTTPException
from pydantic import BaseModel
import user_pb2 as pb
import user_pb2_grpc as pb_grpc
app = FastAPI(title="UserService Gateway", version="1.0.0")
channel = grpc.insecure_channel("localhost:50051")
client = pb_grpc.UserServiceStub(channel)
class CreateUserBody(BaseModel):
name: str = ""
@app.post("/v1/users", status_code=201)
def create_user(body: CreateUserBody) -> dict[str, str]:
try:
resp = client.CreateUser(pb.CreateUserRequest(name=body.name))
except grpc.RpcError as err:
raise HTTPException(status_code=400, detail=err.details()) from err
return {"id": resp.user.id}
@app.get("/v1/users/{user_id}")
def get_user(user_id: str) -> dict[str, str]:
try:
resp = client.GetUser(pb.GetUserRequest(id=user_id))
except grpc.RpcError as err:
match err.code():
case grpc.StatusCode.NOT_FOUND:
raise HTTPException(status_code=404, detail="not found") from err
case _:
raise HTTPException(status_code=500, detail=err.details()) from err
return {"id": resp.user.id, "name": resp.user.name}
# Запуск: uvicorn gateway:app --port 8080
Плагина «grpc-gateway» для этого стека тоже нет, фасад пишется руками. Есть и второй путь: сгенерированный protoc-gen-grpc-gateway прокси - отдельный Go-процесс, который общается с backend-ом по gRPC и не знает, на чём тот написан. Его можно поставить перед сервером на grpcio без единой строчки Go в проекте, если команда готова держать бинарник прокси.
Теперь работает и gRPC, и REST одновременно:
curl http://localhost:8080/v1/users -d '{"name":"Alice"}'
grpcurl -plaintext -d '{"name":"Alice"}' localhost:50051 user.UserService/CreateUser
REST ↔ gRPC mapping
| HTTP | gRPC | Где поля |
|---|---|---|
GET /v1/users/{id} | GetUser(GetUserRequest) | {id} → req.id, query → остальные |
POST /v1/users body {...} | CreateUser(CreateUserRequest) | body → req |
PATCH /v1/users/{id} body {...} | UpdateUser(UpdateUserRequest) | path + body |
DELETE /v1/users/{id} | DeleteUser(DeleteUserRequest) | path → req |
Status code mapping
gRPC-Gateway автоматически конвертирует gRPC-коды в HTTP-коды:
codes.NotFound→404codes.InvalidArgument→400codes.PermissionDenied→403codes.Unauthenticated→401codes.AlreadyExists→409codes.Internal→500codes.Unavailable→503
Можно настроить custom error handler через runtime.WithErrorHandler, чтобы возвращать клиентам JSON-формат вашей ошибки. Но сам код Gateway не придумывает - он берёт его из ответа сервиса, поэтому осмысленные статусы для REST-клиента начинаются с аккуратного status.Error в handler-е и общего error-interceptor-а.
OpenAPI генерация
user.swagger.json - стандартная OpenAPI v2 (Swagger) спецификация. Её можно открыть в Swagger UI:
# docker-compose.yml
services:
swagger:
image: swaggerapi/swagger-ui
ports: ["8081:8080"]
environment:
- SWAGGER_JSON=/spec/user.swagger.json
volumes:
- ./proto:/spec # protoc с --openapiv2_out . кладёт спеку рядом с .proto: ./proto/user.swagger.json
Получаете живую документацию с возможностью попробовать API из браузера. Поддерживает аннотации описаний прямо в .proto через google.api.field_behavior, google.api.field_info.
Versioning
URL-versioning через префикс - стандарт:
rpc CreateUser(CreateUserRequest) returns (CreateUserResponse) {
option (google.api.http) = {
post: "/v1/users"
body: "*"
};
}
При появлении v2 создаётся новый proto-пакет (package user.v2;) с путями /v2/users; сервис внутри может называться так же - UserService, версию задаёт пакет (так советует Google AIP-185). Старые клиенты на v1 продолжают работать. Через год-два v1 объявляют устаревшей, потом удаляют. Это мажорное версионирование API: номер версии меняется только при несовместимых изменениях.
API-first vs gRPC-first
Альтернативный подход - начать с OpenAPI YAML и сгенерировать Go-код через oapi-codegen:
oapi-codegen -generate types -package api openapi.yaml > api/types.gen.go
oapi-codegen -generate chi-server -package api openapi.yaml > api/server.gen.go
ℹ️ Что выбрать?
gRPC-first (gateway): основные клиенты - микросервисы, REST вторичен. API-first (oapi-codegen): основные клиенты - фронтенд и мобильные, REST первичен. Иногда в одном проекте используют оба подхода для разных частей.
Gateway для реальной нагрузки
mux := runtime.NewServeMux(
runtime.WithErrorHandler(customErrorHandler),
runtime.WithMarshalerOption(runtime.MIMEWildcard, &runtime.JSONPb{}),
runtime.WithIncomingHeaderMatcher(func(key string) (string, bool) {
// Какие HTTP headers пробрасываем в gRPC metadata
return runtime.DefaultHeaderMatcher(key)
}),
)
<?php
declare(strict_types=1);
namespace App\EventListener;
use Symfony\Component\EventDispatcher\Attribute\AsEventListener;
use Symfony\Component\HttpFoundation\JsonResponse;
use Symfony\Component\HttpKernel\Event\ExceptionEvent;
use const Grpc\STATUS_ALREADY_EXISTS;
use const Grpc\STATUS_INVALID_ARGUMENT;
use const Grpc\STATUS_NOT_FOUND;
use const Grpc\STATUS_PERMISSION_DENIED;
use const Grpc\STATUS_UNAUTHENTICATED;
use const Grpc\STATUS_UNAVAILABLE;
#[AsEventListener]
final readonly class GrpcErrorListener
{
public function __invoke(ExceptionEvent $event): void
{
$exception = $event->getThrowable();
$event->setResponse(new JsonResponse(
['error' => $exception->getMessage(), 'code' => $exception->getCode()],
$this->mapHttpStatus($exception->getCode()),
));
}
private function mapHttpStatus(int $grpcCode): int
{
return match ($grpcCode) {
STATUS_INVALID_ARGUMENT => 400,
STATUS_UNAUTHENTICATED => 401,
STATUS_PERMISSION_DENIED => 403,
STATUS_NOT_FOUND => 404,
STATUS_ALREADY_EXISTS => 409,
STATUS_UNAVAILABLE => 503,
default => 500,
};
}
}
В Symfony-гейте те же концерны решает стандартная инфраструктура: ExceptionListener под кастомный формат ошибок, nelmio/cors-bundle для CORS, symfony/rate-limiter для rate limit, monolog для логов. Прокидывание HTTP headers в gRPC metadata - явный код в контроллере или middleware.
OpenAPI-документация в Symfony-гейте генерируется через zircote/swagger-php с аттрибутами на контроллерах. Это даёт ту же выдачу, что и --openapiv2_out в gRPC-Gateway, но описание ведётся вручную:
<?php
declare(strict_types=1);
namespace App\Controller;
use OpenApi\Attributes as OA;
use Symfony\Component\HttpFoundation\JsonResponse;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\Routing\Attribute\Route;
#[OA\Info(version: '1.0.0', title: 'UserService Gateway')]
#[Route('/v1/users')]
final readonly class UserApiController
{
#[OA\Post(
path: '/v1/users',
summary: 'Create user',
requestBody: new OA\RequestBody(
required: true,
content: new OA\JsonContent(properties: [
new OA\Property(property: 'name', type: 'string'),
]),
),
responses: [
new OA\Response(response: 201, description: 'created'),
new OA\Response(response: 400, description: 'invalid'),
],
)]
#[Route('', methods: ['POST'])]
public function create(Request $request): JsonResponse
{
// ...
return new JsonResponse(['ok' => true], 201);
}
}
Запуск генератора: vendor/bin/openapi src/Controller --output public/openapi.json. Файл подхватывает любой Swagger UI - получаете живую документацию.
import grpc
from fastapi import FastAPI, Request
from fastapi.middleware.cors import CORSMiddleware
from fastapi.responses import JSONResponse
app = FastAPI(title="UserService Gateway", version="1.0.0")
# CORS для браузеров
app.add_middleware(CORSMiddleware, allow_origins=["https://app.example.com"], allow_methods=["*"])
GRPC_TO_HTTP = {
grpc.StatusCode.INVALID_ARGUMENT: 400,
grpc.StatusCode.UNAUTHENTICATED: 401,
grpc.StatusCode.PERMISSION_DENIED: 403,
grpc.StatusCode.NOT_FOUND: 404,
grpc.StatusCode.ALREADY_EXISTS: 409,
grpc.StatusCode.UNAVAILABLE: 503,
}
# Аналог runtime.WithErrorHandler: один обработчик на все gRPC-ошибки
@app.exception_handler(grpc.RpcError)
def grpc_error_handler(request: Request, err: grpc.RpcError) -> JSONResponse:
return JSONResponse(
status_code=GRPC_TO_HTTP.get(err.code(), 500),
content={"error": err.details(), "code": err.code().name},
)
# Аналог WithIncomingHeaderMatcher: какие HTTP headers пробрасываем в gRPC metadata
FORWARDED_HEADERS = {"authorization", "x-request-id"}
def incoming_metadata(request: Request) -> list[tuple[str, str]]:
return [(key, value) for key, value in request.headers.items() if key in FORWARDED_HEADERS]
В фасаде на FastAPI те же концерны решает стандартная инфраструктура: exception_handler под кастомный формат ошибок, CORSMiddleware для CORS, slowapi для rate limit, logging для логов. Прокидывание HTTP headers в gRPC metadata - явная функция, которую вызывают в обработчиках (client.GetUser(req, metadata=incoming_metadata(request))).
OpenAPI-документация у FastAPI генерируется автоматически из type hints и pydantic-моделей: спека лежит на /openapi.json, Swagger UI - на /docs. Это та же выдача, что и --openapiv2_out в gRPC-Gateway (только версии 3.x), и дополнительный генератор не нужен: описания берутся из docstring-ов обработчиков и Field(description=...) в моделях.
В проде также стоит включить CORS (для браузеров), TLS, rate limiting, логирование на уровне HTTP перед gRPC.
Мини-практика
Добавь gRPC-Gateway к TaskService с REST-эндпоинтами под /v1/tasks. Сгенерируй OpenAPI v2 spec, открой в Swagger UI и проверь все методы. Реализуй custom error handler, который возвращает JSON {"error": "...", "code": "..."} вместо стандартного формата. Убедись, что REST и gRPC возвращают одинаковые status-коды для одних и тех же ситуаций.