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 Code | HTTP аналог | Когда |
|---|---|---|
| InvalidArgument | 400 | Невалидные данные |
| NotFound | 404 | Не найден |
| AlreadyExists | 409 | Дубликат |
| PermissionDenied | 403 | Нет прав |
| Unauthenticated | 401 | Не авторизован |
| DeadlineExceeded | 504 | Таймаут |
| ResourceExhausted | 429 | Rate limit |
| Internal | 500 | Внутренняя ошибка |
| Unavailable | 503 | Недоступен - 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 вызовы могут висеть бесконечно - обязательно ставьте.
Что значит «пробрасывается»
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/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 на стороне клиента и проверь, что сервер реагирует на отмену.