gRPC: первый сервер и клиент

gRPC: первый сервер и клиент

gRPC - фреймворк для вызова удалённых процедур поверх HTTP/2 и Protocol Buffers. Сильные стороны: типизированный контракт, мультиплексирование запросов в одном TCP-соединении, поддержка стримов, готовая инфраструктура (deadlines, metadata, interceptors).

Определение сервиса

service UserService {
  rpc CreateUser(CreateUserRequest) returns (CreateUserResponse);
  rpc GetUser(GetUserRequest) returns (GetUserResponse);
  rpc ListUsers(ListUsersRequest) returns (ListUsersResponse);
}

// User, CreateUserRequest и CreateUserResponse - из урока 1
message GetUserRequest { string id = 1; }
message GetUserResponse { User user = 1; }
message ListUsersRequest {}
message ListUsersResponse { repeated User users = 1; }

Каждый RPC имеет ровно один request-message и один response-message. Это сознательное ограничение - оно делает интерфейс предсказуемым и легко эволюционируемым через добавление полей.

Когда ответ не влезает в одно сообщение и его надо отдавать порциями (выгрузка миллиона строк, живой хвост логов, прогресс задачи) - схема «один запрос, один ответ» ломается. На такие случаи есть стриминговые типы RPC.

Сервер

type userServer struct {
    // Сгенерированная заглушка: на любой ещё не реализованный метод отвечает
    // UNIMPLEMENTED. Добавят метод в .proto - код сервера всё равно скомпилируется.
    pb.UnimplementedUserServiceServer
    users map[string]*pb.User
    mu    sync.RWMutex
}

func (s *userServer) CreateUser(ctx context.Context, req *pb.CreateUserRequest) (*pb.CreateUserResponse, error) {
    if req.Name == "" {
        return nil, status.Error(codes.InvalidArgument, "name is required")
    }

    user := &pb.User{
        Id:   uuid.New().String(),
        Name: req.Name,
    }

    s.mu.Lock()
    s.users[user.Id] = user
    s.mu.Unlock()

    return &pb.CreateUserResponse{User: user}, nil
}

func (s *userServer) GetUser(ctx context.Context, req *pb.GetUserRequest) (*pb.GetUserResponse, error) {
    s.mu.RLock()
    user, ok := s.users[req.Id]
    s.mu.RUnlock()

    if !ok {
        return nil, status.Error(codes.NotFound, "user not found")
    }
    return &pb.GetUserResponse{User: user}, nil
}

func main() {
    lis, _ := net.Listen("tcp", ":50051")
    grpcServer := grpc.NewServer()
    pb.RegisterUserServiceServer(grpcServer, &userServer{users: make(map[string]*pb.User)})
    log.Fatal(grpcServer.Serve(lis))
}
<?php
declare(strict_types=1);

namespace App\Grpc;

use Spiral\RoadRunner\GRPC\ContextInterface;
use Spiral\RoadRunner\GRPC\Exception\GRPCException;
use Spiral\RoadRunner\GRPC\StatusCode;
use User\CreateUserRequest;
use User\CreateUserResponse;
use User\GetUserRequest;
use User\GetUserResponse;
use User\ListUsersRequest;
use User\ListUsersResponse;
use User\User;
use User\UserServiceInterface;
use Symfony\Component\Uid\Uuid;

final class UserService implements UserServiceInterface
{
    /** @var array<string, User> */
    private array $users = [];

    public function CreateUser(ContextInterface $ctx, CreateUserRequest $in): CreateUserResponse
    {
        if ($in->getName() === '') {
            throw new GRPCException('name is required', StatusCode::INVALID_ARGUMENT);
        }

        $user = (new User())
            ->setId(Uuid::v4()->toRfc4122())
            ->setName($in->getName());

        $this->users[$user->getId()] = $user;

        return (new CreateUserResponse())->setUser($user);
    }

    public function GetUser(ContextInterface $ctx, GetUserRequest $in): GetUserResponse
    {
        $user = $this->users[$in->getId()] ?? null;
        if ($user === null) {
            throw new GRPCException('user not found', StatusCode::NOT_FOUND);
        }
        return (new GetUserResponse())->setUser($user);
    }

    public function ListUsers(ContextInterface $ctx, ListUsersRequest $in): ListUsersResponse
    {
        // Интерфейс требует реализовать все методы; пока метод не готов - честно отвечаем UNIMPLEMENTED
        throw new GRPCException('not implemented yet', StatusCode::UNIMPLEMENTED);
    }
}

ListUsers в примерах оставлен как упражнение. В Go его закрывает встроенный UnimplementedUserServiceServer (его встраивают ради forward compatibility: без него новый метод в .proto ломает компиляцию всех серверов, которые его ещё не реализовали), в Python базовый UserServiceServicer - оба отвечают кодом UNIMPLEMENTED. В PHP интерфейс требует объявить все методы, поэтому нужна явная заглушка.

В PHP полноценный gRPC-сервер обычно поднимается через Spiral RoadRunner (spiral/roadrunner-grpc) - это production-grade рантайм на Go, который держит долгоживущие соединения (PHP-FPM на это не способен по архитектуре). Сгенерированный из .proto интерфейс UserServiceInterface реализуется как обычный сервис.

В worker.php (entrypoint RoadRunner) регистрируем сервис и стартуем:

<?php
declare(strict_types=1);

require __DIR__ . '/vendor/autoload.php';

use Spiral\RoadRunner\GRPC\Server;
use Spiral\RoadRunner\Worker;
use User\UserServiceInterface;

$server = new Server();
$server->registerService(UserServiceInterface::class, new App\Grpc\UserService());
$server->serve(Worker::create());

Запуск: ./rr serve -c .rr.yaml, где .rr.yaml описывает grpc.listen: tcp://0.0.0.0:50051. Альтернативный путь - Swoole (swoole/grpc), но RoadRunner более развит в PHP-экосистеме.

# pip install grpcio grpcio-tools
# Генерация: python -m grpc_tools.protoc -I proto --python_out=. --grpc_python_out=. proto/user.proto
import threading
import uuid
from concurrent import futures

import grpc

import user_pb2 as pb
import user_pb2_grpc as pb_grpc


class UserServer(pb_grpc.UserServiceServicer):
    def __init__(self) -> None:
        self._users: dict[str, pb.User] = {}
        # Сервер grpcio обслуживает запросы из пула потоков, поэтому словарь нужно защищать.
        self._lock = threading.Lock()

    def CreateUser(self, request: pb.CreateUserRequest, context: grpc.ServicerContext) -> pb.CreateUserResponse:
        if request.name == "":
            # abort поднимает исключение и завершает RPC со статусом; return после него не нужен.
            context.abort(grpc.StatusCode.INVALID_ARGUMENT, "name is required")

        user = pb.User(id=str(uuid.uuid4()), name=request.name)

        with self._lock:
            self._users[user.id] = user

        return pb.CreateUserResponse(user=user)

    def GetUser(self, request: pb.GetUserRequest, context: grpc.ServicerContext) -> pb.GetUserResponse:
        with self._lock:
            user = self._users.get(request.id)

        if user is None:
            context.abort(grpc.StatusCode.NOT_FOUND, "user not found")
        return pb.GetUserResponse(user=user)


def main() -> None:
    server = grpc.server(futures.ThreadPoolExecutor(max_workers=10))
    pb_grpc.add_UserServiceServicer_to_server(UserServer(), server)
    server.add_insecure_port("[::]:50051")
    server.start()
    server.wait_for_termination()


if __name__ == "__main__":
    main()

Сервис - подкласс сгенерированного UserServiceServicer; имена методов остаются в CamelCase, как в .proto. Вместо возврата error метод вызывает context.abort(code, message) - это выбрасывает исключение, поэтому код после него не выполняется. Есть и asyncio-вариант (grpc.aio.server(), методы async def) - тот же API без пула потоков.

Клиент

Клиент создаётся один раз и переиспользуется - он thread-safe и держит постоянное соединение с пулом HTTP/2 streams. Открывать новый conn на каждый запрос - антипаттерн.

// grpc.NewClient заменил устаревший grpc.Dial (deprecated с grpc-go v1.63).
// Соединение устанавливается лениво, при первом вызове.
conn, err := grpc.NewClient("localhost:50051",
    grpc.WithTransportCredentials(insecure.NewCredentials()),
)
if err != nil {
    log.Fatal(err)
}
defer conn.Close()

client := pb.NewUserServiceClient(conn)

resp, err := client.CreateUser(ctx, &pb.CreateUserRequest{Name: "Alice"})
if err != nil {
    st, ok := status.FromError(err)
    if ok {
        log.Printf("gRPC error: code=%s msg=%s", st.Code(), st.Message())
    }
}
<?php
declare(strict_types=1);

use Grpc\ChannelCredentials;
use User\CreateUserRequest;
use User\UserServiceClient;

final class UserApi
{
    public function __construct(
        private readonly UserServiceClient $client,
    ) {}

    public static function create(string $host): self
    {
        return new self(new UserServiceClient($host, [
            'credentials' => ChannelCredentials::createInsecure(),
        ]));
    }

    public function createUser(string $name): string
    {
        $req = (new CreateUserRequest())->setName($name);

        // Метод возвращает [$response, $status]
        [$response, $status] = $this->client->CreateUser($req)->wait();

        if ($status->code !== Grpc\STATUS_OK) {
            throw new RuntimeException(
                sprintf('gRPC error: code=%d msg=%s', $status->code, $status->details),
            );
        }
        return $response->getUser()->getId();
    }
}

$api = UserApi::create('localhost:50051');
$id = $api->createUser('Alice');

PHP-клиент - это сгенерированный класс, унаследованный от \Grpc\BaseStub. Подключается через ext-grpc.

BaseStub thread-safe только в рамках одного процесса PHP; внутри FPM-воркера держим один экземпляр на запрос (или per-worker через DI Symfony). Закрывать соединение вручную не нужно - Channel живёт пока есть ссылка.

import logging

import grpc

import user_pb2 as pb
import user_pb2_grpc as pb_grpc

# Канал - аналог conn в Go: создаётся один раз, thread-safe, закрывается через with.
with grpc.insecure_channel("localhost:50051") as channel:
    client = pb_grpc.UserServiceStub(channel)

    try:
        resp = client.CreateUser(pb.CreateUserRequest(name="Alice"))
    except grpc.RpcError as err:
        # Объект ошибки одновременно реализует grpc.Call: у него есть code() и details().
        logging.error("gRPC error: code=%s msg=%s", err.code().name, err.details())

Клиент - сгенерированный UserServiceStub. Ошибка вызова приходит исключением grpc.RpcError, а не вторым возвращаемым значением; код и сообщение достаются через err.code() и err.details().

gRPC коды ошибок

gRPC CodeHTTP аналогКогда
InvalidArgument400Невалидные данные
NotFound404Не найден
AlreadyExists409Дубликат
PermissionDenied403Нет прав
Unauthenticated401Не авторизован
DeadlineExceeded504Таймаут
ResourceExhausted429Rate limit
Internal500Внутренняя ошибка
Unavailable503Недоступен - retry

Unavailable важен: это сигнал клиенту, что запрос можно безопасно повторить. Используйте его, когда сбой временный (БД не отвечает, lock contention) и есть смысл повторить. Сам по себе клиент такой ответ не повторит: нужна retryPolicy в service config с UNAVAILABLE в retryableStatusCodes или retry-interceptor (его пишем в уроке 4). Автоматически повторяются только «прозрачные» случаи, когда запрос вообще не дошёл до кода сервера.

Status с details

Стандартные коды лаконичные. Для дополнительной структурированной информации есть status.Details:

st := status.New(codes.InvalidArgument, "validation failed")
st, _ = st.WithDetails(&errdetails.BadRequest{
    FieldViolations: []*errdetails.BadRequest_FieldViolation{
        {Field: "email", Description: "must be valid email"},
    },
})
return nil, st.Err()

Клиент извлекает детали через st.Details() и обрабатывает программно - например, подсвечивает невалидные поля в форме.

<?php
declare(strict_types=1);

use Google\Rpc\BadRequest;
use Google\Rpc\BadRequest\FieldViolation;
use Spiral\RoadRunner\GRPC\Exception\GRPCException;
use Spiral\RoadRunner\GRPC\StatusCode;

$violations = new BadRequest();
$violations->setFieldViolations([
    (new FieldViolation())->setField('email')->setDescription('must be valid email'),
]);

// Третий аргумент - массив protobuf-сообщений (details).
// RoadRunner сам упакует их в Any внутри google.rpc.Status и отправит в trailer grpc-status-details-bin.
throw new GRPCException('validation failed', StatusCode::INVALID_ARGUMENT, [$violations]);

В PHP классы деталей (Google\Rpc\BadRequest) берутся из пакета google/common-protos (composer require google/common-protos). Go-клиент достанет их тем же st.Details().

# pip install grpcio-status googleapis-common-protos
from google.protobuf import any_pb2
from google.rpc import code_pb2, error_details_pb2, status_pb2
from grpc_status import rpc_status

detail = any_pb2.Any()
detail.Pack(error_details_pb2.BadRequest(
    field_violations=[
        error_details_pb2.BadRequest.FieldViolation(
            field="email", description="must be valid email",
        ),
    ],
))
rich_status = status_pb2.Status(
    code=code_pb2.INVALID_ARGUMENT,
    message="validation failed",
    details=[detail],
)
# abort_with_status кладёт сериализованный Status в trailer grpc-status-details-bin.
context.abort_with_status(rpc_status.to_status(rich_status))

Клиент извлекает детали через rpc_status.from_call(err) и распаковывает каждый Any обратно в BadRequest методом Unpack.

Metadata - заголовки gRPC

// Клиент
ctx = metadata.AppendToOutgoingContext(ctx, "authorization", "Bearer token123")
ctx = metadata.AppendToOutgoingContext(ctx, "x-request-id", uuid.New().String())

// Сервер
md, ok := metadata.FromIncomingContext(ctx)
if ok {
    tokens := md.Get("authorization")
}
<?php
declare(strict_types=1);

use Spiral\RoadRunner\GRPC\ContextInterface;

// Клиент: metadata третьим аргументом
$metadata = [
    'authorization' => ['Bearer token123'],
    'x-request-id'  => [Symfony\Component\Uid\Uuid::v4()->toRfc4122()],
];
[$response, $status] = $client->CreateUser($req, $metadata)->wait();

// Сервер: ContextInterface даёт getValue() для metadata
public function CreateUser(ContextInterface $ctx, CreateUserRequest $in): CreateUserResponse
{
    $tokens = $ctx->getValue('authorization') ?? [];
    $token = $tokens[0] ?? null;
    // ...
}

В PHP-клиенте metadata - это третий аргумент вызова метода stub-а. На сервере (RoadRunner) - объект ContextInterface.

import uuid

import grpc

# Клиент: metadata - список пар (ключ, значение), ключи в нижнем регистре
metadata = [
    ("authorization", "Bearer token123"),
    ("x-request-id", str(uuid.uuid4())),
]
resp = client.CreateUser(req, metadata=metadata)


# Сервер: входящие заголовки лежат в context.invocation_metadata()
def CreateUser(self, request: pb.CreateUserRequest, context: grpc.ServicerContext) -> pb.CreateUserResponse:
    tokens = [value for key, value in context.invocation_metadata() if key == "authorization"]
    ...

В клиенте metadata передаётся именованным аргументом вызова, на сервере читается из context.invocation_metadata() - это последовательность пар, поэтому «все значения заголовка» собираются фильтром по ключу.

Используется для аутентификации, correlation ID, A/B-флагов. Имена case-insensitive, значения - список строк (один заголовок может иметь несколько значений).

Доставать токен и correlation ID руками в каждом методе - копипаста. Один раз распарсить metadata и положить в context удобнее в interceptor-е: handler получит уже готового пользователя и не будет знать про заголовки вообще.

Deadlines и cancellation propagation

ctx, cancel := context.WithTimeout(ctx, 2*time.Second)
defer cancel()

resp, err := client.CreateUser(ctx, req)
<?php
declare(strict_types=1);

// Клиент: 2 секунды на запрос
$options = ['timeout' => 2_000_000]; // microseconds
[$response, $status] = $client->CreateUser($req, [], $options)->wait();

if ($status->code === Grpc\STATUS_DEADLINE_EXCEEDED) {
    throw new RuntimeException('CreateUser timed out');
}

В PHP deadline передаётся через timeout (в микросекундах) в опциях вызова. RoadRunner на сервере читает его из контекста:

<?php
declare(strict_types=1);

use Spiral\RoadRunner\GRPC\ContextInterface;

public function Get(ContextInterface $ctx, GetRequest $in): GetResponse
{
    // RoadRunner кладёт оставшийся deadline в значения контекста
    $timeout = $ctx->getValue('timeout');
    if ($timeout !== null && (int)$timeout[0] < 100_000) {
        // меньше 100ms - не имеет смысла лезть в downstream
        throw new GRPCException('not enough time', StatusCode::DEADLINE_EXCEEDED);
    }
    // ...
}
import grpc

# Клиент: 2 секунды на запрос; по истечении - RpcError с кодом DEADLINE_EXCEEDED
try:
    resp = client.CreateUser(req, timeout=2.0)
except grpc.RpcError as err:
    if err.code() == grpc.StatusCode.DEADLINE_EXCEEDED:
        raise TimeoutError("CreateUser timed out") from err
    raise

Deadline передаётся аргументом timeout (в секундах) в каждый вызов stub-а; отдельного объекта контекста на клиенте нет, поэтому один и тот же таймаут на цепочку вызовов приходится вычислять руками. На сервере остаток виден через context.time_remaining():

def Get(self, request: pb.GetRequest, context: grpc.ServicerContext) -> pb.GetResponse:
    # time_remaining() - секунды до deadline или None, если клиент его не задал
    remaining = context.time_remaining()
    if remaining is not None and remaining < 0.1:
        # меньше 100ms - не имеет смысла лезть в downstream
        context.abort(grpc.StatusCode.DEADLINE_EXCEEDED, "not enough time")
    ...

Deadline пробрасывается через wire - сервер видит его и может отменить долгие операции. Если сервер вызывает другие сервисы - deadline пробрасывается дальше, образуя цепочку. Без deadline вызовы могут висеть бесконечно - обязательно ставьте.

Что значит «пробрасывается»

Deadline уменьшается на каждом hop: Frontend -> Gateway -> user svc -> account svc -> DB

Frontend → API Gateway → UserService → AccountService → DB
   3s           ~2.95s         ~2.85s          ~2.7s        ~2.5s
   ↑ оставшееся время уменьшается на каждом hop: на сеть и на работу предыдущего сервиса

gRPC-runtime автоматически сериализует remaining deadline в metadata (grpc-timeout). Сервер при получении запроса создаёт child-context с этим deadline. Если в сервере вы делаете client.SomethingElse(ctx, ...) - ctx уже содержит deadline, и он улетит дальше.

// Сервер видит deadline и УЖЕ ИМЕЕТ ctx с ним:
func (s *server) Get(ctx context.Context, req *pb.GetRequest) (*pb.GetResponse, error) {
    if dl, ok := ctx.Deadline(); ok {
        slog.Info("incoming deadline", "remaining", time.Until(dl))
    }
    // Этот вызов не превысит remaining deadline:
    user, err := s.accountClient.Get(ctx, &pb.AccountReq{Id: req.Id})
    return &pb.GetResponse{...}, err
}
<?php
declare(strict_types=1);

use Spiral\RoadRunner\GRPC\ContextInterface;

final readonly class AccountFacade
{
    public function __construct(
        private AccountServiceClient $accountClient,
        private LoggerInterface $logger,
    ) {}

    public function get(ContextInterface $ctx, string $id): Account
    {
        $remaining = (int)($ctx->getValue('timeout')[0] ?? 0);
        $this->logger->info('incoming deadline', ['remaining_us' => $remaining]);

        $req = (new AccountReq())->setId($id);
        [$resp, $status] = $this->accountClient
            ->Get($req, [], ['timeout' => $remaining])
            ->wait();

        if ($status->code !== Grpc\STATUS_OK) {
            throw new RuntimeException('downstream failed: ' . $status->details);
        }
        return $resp->getAccount();
    }
}

В PHP при обращении к downstream-сервису берём остаток таймаута и прокидываем дальше. В Symfony-проектах удобно делегировать это Symfony\Contracts\HttpClient или сделать декоратор над gRPC-клиентом.

import logging

import grpc

logger = logging.getLogger(__name__)


# Сервер видит deadline, но в downstream-вызов его нужно передать явно:
def Get(self, request: pb.GetRequest, context: grpc.ServicerContext) -> pb.GetResponse:
    remaining = context.time_remaining()
    if remaining is not None:
        logger.info("incoming deadline", extra={"remaining_s": remaining})
    # Прокидываем остаток дальше - этот вызов не превысит remaining deadline:
    account = self._account_client.Get(pb.AccountReq(id=request.id), timeout=remaining)
    return pb.GetResponse(...)

В отличие от Go, где deadline лежит в ctx и уходит в downstream сам, здесь контекст сервера и клиентский вызов не связаны: остаток из context.time_remaining() передаётся в timeout= руками (или одним interceptor-ом на всех клиентах).

Cancellation: клиент отменил - все остановились

// Клиент:
ctx, cancel := context.WithCancel(parentCtx)
go func() { <-someEvent; cancel() }()      // отмена по сигналу
resp, err := client.LongOperation(ctx, req)

// Сервер видит отмену через ctx.Done():
func (s *server) LongOperation(ctx context.Context, req *pb.Req) (*pb.Resp, error) {
    select {
    case <-ctx.Done():
        return nil, status.FromContextError(ctx.Err()).Err()
    case result := <-s.compute(ctx, req):
        return result, nil
    }
}
<?php
declare(strict_types=1);

use Spiral\RoadRunner\GRPC\ContextInterface;

public function LongOperation(ContextInterface $ctx, Req $in): Resp
{
    $deadlineUs = (int)($ctx->getValue('timeout')[0] ?? PHP_INT_MAX);
    $startedAt = hrtime(true);

    while (!$this->isDone()) {
        // cooperative cancellation: каждые N шагов проверяем deadline
        $elapsedUs = (int)((hrtime(true) - $startedAt) / 1000);
        if ($elapsedUs >= $deadlineUs) {
            // истёк deadline - это DEADLINE_EXCEEDED; CANCELLED означает отмену самим клиентом
            throw new GRPCException('deadline exceeded', StatusCode::DEADLINE_EXCEEDED);
        }
        $this->step();
    }
    return (new Resp())->setResult($this->result());
}

В PHP отмены «по событию» нет (нет горутин и каналов), но deadline-cancellation работает аналогично - истёкший timeout прерывает вызов. Для долгих операций на сервере периодически проверяем флаг через cooperative cancellation.

import threading

import grpc

# Клиент: .future() возвращает объект вызова, у него есть cancel()
call = client.LongOperation.future(req)
threading.Thread(target=lambda: (some_event.wait(), call.cancel())).start()  # отмена по сигналу
try:
    resp = call.result()
except grpc.FutureCancelledError:
    ...


# Сервер видит отмену через context.is_active() или callback:
def LongOperation(self, request: pb.Req, context: grpc.ServicerContext) -> pb.Resp:
    done = threading.Event()
    # add_callback срабатывает при отмене клиентом или истечении deadline
    context.add_callback(done.set)

    for step in self._compute(request):
        if done.is_set() or not context.is_active():
            context.abort(grpc.StatusCode.CANCELLED, "client cancelled")
    return pb.Resp(result=step)

Отмена «по событию» есть: синхронный stub даёт .future() с методом cancel(), в asyncio-варианте отмена задачи (task.cancel()) отменяет и RPC. На сервере нет ctx.Done(), вместо него context.add_callback и context.is_active() - долгая операция проверяет их между шагами (cooperative cancellation, как в PHP).

Отмена пробрасывается транзитивно: если ваш сервер делает 5 даунстрим-вызовов, отмена клиента остановит все 5. Это бесплатное «убийство» висящих запросов - не нужно вручную закрывать соединения.

⚠️ DB-запросы тоже принимают ctx

db.QueryContext(ctx, ...) (метод *sql.DB) отменит запрос в PostgreSQL при отмене context - драйвер пошлёт CancelRequest. Если же вы делаете db.Query() без ctx - даже после возврата ошибки в gRPC, БД будет дожимать тяжёлый JOIN. Всегда передавайте ctx до самого низа.

gRPC vs REST: trade-offs

Структура gRPC и REST: разные транспорт, payload и контракт

Аспект                     gRPC                           REST/JSON
─────────────────────      ───────────────────────────    ───────────────────────────
Транспорт                  HTTP/2 (multiplexing)          HTTP/1.1 (обычно)
Payload                    Protobuf (binary, типизир.)    JSON (текст, нетипизир.)
Контракт                   .proto + кодген                OpenAPI (опционально)
Streaming                  4 типа из коробки              SSE/WebSocket - отдельно
Браузер                    нужен grpc-web/gateway         работает напрямую
Размер payload             3-10× меньше JSON              базовый
Скорость сериализации      5-100× быстрее                 базовый
Читаемость в логах         бинарный (нужен protoc)        видно глазами
Curl-friendly              нет (нужен grpcurl)            да
Эволюция API               через номера полей             через версионирование/опц. поля
Ошибки                     gRPC codes (17, от 0 до 16)    HTTP status (400-599)
Зрелость инструментов      service mesh, tracing - норма  REST везде, есть всё

Когда gRPC выигрывает: микросервисы внутри одного периметра (типизация, скорость, streaming), мобильные клиенты на медленных сетях (бинарный payload), бэкенд-к-бэкенд интеграции с высокой нагрузкой.

Когда REST лучше: публичный API для веба (браузеры, curl, debug), интеграции с внешними партнёрами (JSON - lingua franca), простые CRUD-сервисы (накладные расходы gRPC не оправданы).

В реальных проектах часто комбинируют: gRPC между сервисами плюс REST наружу. Выбирать между двумя API не нужно - один и тот же .proto может отдавать оба протокола, если поставить перед сервисом gRPC-Gateway.

Health Checking

Стандартизированный API проверки здоровья сервиса:

import "google.golang.org/grpc/health"
import healthpb "google.golang.org/grpc/health/grpc_health_v1"

healthSrv := health.NewServer()
healthpb.RegisterHealthServer(grpcServer, healthSrv)
healthSrv.SetServingStatus("user.UserService", healthpb.HealthCheckResponse_SERVING)
<?php
declare(strict_types=1);

namespace App\Grpc;

use Grpc\Health\V1\HealthCheckRequest;
use Grpc\Health\V1\HealthCheckResponse;
use Grpc\Health\V1\HealthCheckResponse\ServingStatus;
use Grpc\Health\V1\HealthInterface;
use Spiral\RoadRunner\GRPC\ContextInterface;

final class HealthService implements HealthInterface
{
    /** @var array<string, int> */
    private array $statuses = ['' => ServingStatus::SERVING];

    public function setStatus(string $service, int $status): void
    {
        $this->statuses[$service] = $status;
    }

    public function Check(ContextInterface $ctx, HealthCheckRequest $in): HealthCheckResponse
    {
        $status = $this->statuses[$in->getService()] ?? ServingStatus::SERVICE_UNKNOWN;
        return (new HealthCheckResponse())->setStatus($status);
    }
}

В RoadRunner-приложении health-сервис реализуется тем же способом - стандартный proto grpc.health.v1.Health с методами Check и Watch.

# pip install grpcio-health-checking
from grpc_health.v1 import health, health_pb2, health_pb2_grpc

health_srv = health.HealthServicer()
health_pb2_grpc.add_HealthServicer_to_server(health_srv, server)
health_srv.set("user.UserService", health_pb2.HealthCheckResponse.SERVING)

Готовая реализация стандартного grpc.health.v1.Health лежит в пакете grpcio-health-checking; свой класс писать не нужно, как и в Go.

Используется Kubernetes liveness/readiness probes, load balancer-ами для исключения unhealthy instances. Стандартный API - везде один и тот же.

Reflection и grpcurl

import "google.golang.org/grpc/reflection"
reflection.Register(grpcServer)

RoadRunner поддерживает reflection через флаг конфигурации - не нужно отдельно регистрировать сервис в коде:

# .rr.yaml
grpc:
    listen: tcp://0.0.0.0:50051
    proto:
        - proto/user.proto
    pool:
        num_workers: 4
    # Включаем server reflection API
    enable_reflection: true

С reflection можно вызывать сервис без .proto файла на руках. grpcurl использует это:

grpcurl -plaintext localhost:50051 list
grpcurl -plaintext localhost:50051 describe user.UserService
grpcurl -plaintext -d '{"name":"Bob"}' localhost:50051 user.UserService/CreateUser

В проде reflection обычно отключают (security: раскрывает API). В dev/staging - оставляют для удобства.

Мини-практика

Реализуй gRPC сервис TaskService с методами Create, Get, List, Delete. Добавь reflection для grpcurl, health-check, status.Details при ошибке валидации. Передай в metadata correlation_id и пробрось его в логах сервера. Установи deadline на стороне клиента и проверь, что сервер реагирует на отмену.

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