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-сервера

gRPC-Gateway: браузер идёт по REST через прокси, микросервис вызывает тот же backend по gRPC напрямую

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

HTTPgRPCГде поля
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 → 404
  • codes.InvalidArgument → 400
  • codes.PermissionDenied → 403
  • codes.Unauthenticated → 401
  • codes.AlreadyExists → 409
  • codes.Internal → 500
  • codes.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-коды для одних и тех же ситуаций.

Зарегистрируйтесь бесплатно, чтобы пройти квиз, вести прогресс.