📡 gRPC-сервис на Go
Эта страница про то, как собрать gRPC-сервис на Go целиком: от .proto до сервера, который переживает панику, отдаёт понятные ошибки и спокойно выключается при деплое. Как устроен сам протокол, коды статусов и совместимость полей, разобрано на странице про gRPC и Protocol Buffers. Здесь — код, который пишут на работе, и вопросы, которые задают, когда видят gRPC в резюме
🧠 Как это устроено
Путь от контракта до работающего сервиса выглядит так:
- Пишешь
.protoс сервисом и сообщениями - Генератор превращает его в два файла:
orders.pb.goсо структурами сообщений (плагинprotoc-gen-go) иorders_grpc.pb.goс интерфейсом сервера и клиентом (плагинprotoc-gen-go-grpc) - Пишешь структуру, которая реализует интерфейс
OrderServiceServer - Создаёшь
grpc.Server, вешаешь на него интерсепторы, регистрируешь свой сервис, health-check и рефлексию - Слушаешь порт и по сигналу останавливаешь сервер так, чтобы начатые вызовы успели закончиться
Сгенерированный код коммитят в репозиторий или генерируют в CI, но руками его никогда не правят: следующая генерация всё перезапишет
protoc или buf
Исторически код генерирует protoc, компилятор от Google, которому плагины передают флагами: protoc --go_out=. --go-grpc_out=. .... Его ставят отдельным бинарником, а флаги и пути импорта каждая команда собирает в свой Makefile
Сейчас в Go-проектах чаще берут buf. Это один бинарник с конфигом в YAML, который генерирует код, проверяет стиль схемы и ищет изменения, ломающие совместимость. Три команды закрывают почти всё:
| Команда | Что делает |
|---|---|
buf generate | генерирует код по buf.gen.yaml |
buf lint | проверяет схему по набору правил STANDARD: имена, пакеты с версией, отдельные запрос и ответ на каждый метод |
buf breaking --against <старая версия> | сравнивает схему с прошлой и падает, если изменение сломает старых клиентов |
buf breaking в CI ловит ровно те ошибки, о которых спрашивают на собеседовании про protobuf. В проверке номер поля total_kopecks поменяли с 3 на 4, и команда упала с кодом 100 и сообщением Previously present field "3" with name "total_kopecks" on message "Order" was deleted. На ревью такое легко пропустить глазами, а проверка не пропустит
🛠️ На практике
Генерация
Плагины генерации удобно держать в go.mod директивой tool, как разобрано на странице про модули. Тогда у всей команды и в CI одни и те же версии:
go get -tool google.golang.org/protobuf/cmd/protoc-gen-go@latest
go get -tool google.golang.org/grpc/cmd/protoc-gen-go-grpc@latestСам buf лучше ставить отдельным бинарником. Директива tool добавляет зависимости инструмента в общий граф модуля, и в проверке buf v1.75.0 сразу потребовал версию google.golang.org/protobuf новее той, что стояла в проекте. Тянуть такой инструмент в граф сервиса незачем
Конфиги лежат в корне репозитория:
# buf.yaml
version: v2
modules:
- path: proto
lint:
use:
- STANDARD
breaking:
use:
- FILE# buf.gen.yaml
version: v2
plugins:
- local: ["go", "tool", "protoc-gen-go"]
out: gen
opt: paths=source_relative
- local: ["go", "tool", "protoc-gen-go-grpc"]
out: gen
opt: paths=source_relativeВ .proto пакет Go задаёт опция option go_package = "example.com/orders/gen/orders/v1;ordersv1";. Линтер STANDARD требует версию в имени пакета (orders.v1) и отдельные сообщения GetOrderRequest и GetOrderResponse на каждый метод. Первый вариант схемы, где GetOrder сразу возвращал Order, он не пропустил. Отдельный ответ даёт место для новых полей рядом с заказом, не трогая сам заказ
Сервер
type OrderServer struct {
ordersv1.UnimplementedOrderServiceServer // встраивать по значению, не указателем
repo Repo
}
func (s *OrderServer) GetOrder(ctx context.Context, req *ordersv1.GetOrderRequest) (*ordersv1.GetOrderResponse, error) {
o, err := s.repo.Get(ctx, req.GetId())
if err != nil {
return nil, toStatus(err)
}
return &ordersv1.GetOrderResponse{Order: o}, nil
}Встроенная UnimplementedOrderServiceServer нужна для совместимости вперёд. Когда в .proto добавят новый метод, твоя структура не перестанет компилироваться: метод возьмётся из встроенной структуры и вернёт codes.Unimplemented. Сгенерированный код требует встраивать её по значению. При регистрации он вызывает у неё метод-пустышку, и если встроен нулевой указатель, сервис упадёт с паникой сразу на старте, а не на первом вызове нового метода
Запуск сервера:
srv := grpc.NewServer(
grpc.ChainUnaryInterceptor(logging(log), recovery(log)),
)
ordersv1.RegisterOrderServiceServer(srv, &OrderServer{repo: repo})
hs := health.NewServer()
healthpb.RegisterHealthServer(srv, hs)
reflection.Register(srv) // чтобы grpcurl видел схему без .proto
lis, err := net.Listen("tcp", ":50051")
if err != nil {
return err
}
go srv.Serve(lis)У сообщений есть лимит по размеру. Сервер и клиент по умолчанию принимают до 4 МБ, а отправлять можно до math.MaxInt32. Больше 4 МБ получатель отвергнет с ResourceExhausted и текстом grpc: received message larger than max. Поднять можно через grpc.MaxRecvMsgSize, но если сообщения такого размера, это повод подумать о стриме
Интерсепторы
Интерсептор — это middleware для gRPC. Унарный получает контекст, запрос, имя метода в info.FullMethod и следующий обработчик в цепочке:
func logging(log *slog.Logger) grpc.UnaryServerInterceptor {
return func(ctx context.Context, req any, info *grpc.UnaryServerInfo, handler grpc.UnaryHandler) (any, error) {
start := time.Now()
resp, err := handler(ctx, req)
log.Info("grpc", "method", info.FullMethod, "code", status.Code(err).String(), "took", time.Since(start))
return resp, err
}
}
func recovery(log *slog.Logger) grpc.UnaryServerInterceptor {
return func(ctx context.Context, req any, info *grpc.UnaryServerInfo, handler grpc.UnaryHandler) (resp any, err error) {
defer func() {
if p := recover(); p != nil {
log.Error("panic", "method", info.FullMethod, "panic", p, "stack", string(debug.Stack()))
err = status.Error(codes.Internal, "внутренняя ошибка")
}
}()
return handler(ctx, req)
}
}grpc-go не ловит панику в обработчике. В net/http сервер хотя бы закрывает соединение и пишет http: panic serving, а здесь паника роняет весь процесс вместе с остальными вызовами. На пробном запуске запись в nil-map без интерсептора восстановления остановила тест с panic: assignment to entry in nil map. Recovery-интерсептор в сервисе обязателен
grpc.ChainUnaryInterceptor собирает цепочку так: первый в списке — внешний, последний оборачивает сам обработчик. Порядок меняет поведение, и это видно в логах:
| Порядок | Что видно при панике |
|---|---|
recovery, logging | строка panic есть, строки access-лога нет: паника пролетела через logging насквозь |
logging, recovery | строка panic и строка access-лога с code=Internal |
Поэтому recovery ставят последним, ближе всего к обработчику. Так же советует README go-grpc-middleware: там готовы интерсепторы логирования, recovery, auth, rate limit и валидации, а для метрик и трейсов берут OpenTelemetry. Для стримов есть свой тип grpc.StreamServerInterceptor и своя цепочка grpc.ChainStreamInterceptor: унарные интерсепторы стримы не видят
Токен, request id и другие заголовки в gRPC называются метаданными. В интерсепторе их читают через metadata.FromIncomingContext(ctx), клиент кладёт их через metadata.AppendToOutgoingContext
Ошибки и детали
Код статуса выбирают в одном месте, на границе сервиса, а не в каждом обработчике. Репозиторий возвращает доменную ошибку, функция вроде toStatus превращает её в статус:
func toStatus(err error) error {
switch {
case errors.Is(err, ErrNotFound):
return status.Error(codes.NotFound, "заказ не найден")
case errors.Is(err, context.DeadlineExceeded), errors.Is(err, context.Canceled):
return status.FromContextError(err).Err()
default:
return status.Error(codes.Internal, "внутренняя ошибка") // детали — в лог, не клиенту
}
}Если клиенту нужно знать, какое поле не прошло проверку, к статусу добавляют детали из пакета errdetails. Это protobuf-сообщения, которые уходят вместе со статусом:
st, _ := status.New(codes.InvalidArgument, "неверный запрос").WithDetails(&errdetails.BadRequest{
FieldViolations: []*errdetails.BadRequest_FieldViolation{
{Field: "id", Description: "должен быть больше нуля"},
},
})
return nil, st.Err()Клиент достаёт их через status.Convert(err).Details() и проверкой типа на *errdetails.BadRequest. В тесте клиент получил InvalidArgument и пару id: должен быть больше нуля
Дедлайны на стороне сервера
Клиентский дедлайн приходит в контексте обработчика. Когда время клиента вышло, контекст отменяется, а клиент сразу получает DeadlineExceeded, не дожидаясь сервера. Сервер при этом не прерывает обработчик сам: тот работает дальше, пока не проверит ctx
В тесте клиент дал 100 мс, а обработчик ждал 2 секунды в select с ctx.Done(). Клиент получил DeadlineExceeded через 100 мс, обработчик вышел с context canceled: отмена от клиента пришла раньше собственного таймера сервера. Обработчик вернул ctx.Err() как есть, и в логе сервера вызов записался как code=Unknown. Через status.FromContextError он стал бы DeadlineExceeded или Canceled, и метрики ошибок не путали бы таймаут с багом
Если клиент не передал дедлайн, контекст обработчика бесконечен. Часть команд ставит в интерсепторе верхний предел, например context.WithTimeout(ctx, 10*time.Second), если в ctx.Deadline() ничего нет
Health-check и выключение
Стандартный сервис grpc.health.v1.Health знают Kubernetes, балансировщики и клиентские библиотеки. В Go он уже написан: health.NewServer() сразу отвечает SERVING для пустого имени, то есть для сервера целиком. Статус отдельного сервиса ставят через SetServingStatus("orders.v1.OrderService", ...), а на имя, которое никто не выставил, Check вернёт NotFound
Kubernetes умеет ходить в него сам, без утилиты в образе: проба grpc стабильна с версии 1.27. По умолчанию kubelet подключается без TLS, а любую ошибку считает проваленной проверкой:
readinessProbe:
grpc:
port: 50051
periodSeconds: 5Выключение при деплое собирают из трёх шагов:
ctx, stop := signal.NotifyContext(context.Background(), syscall.SIGTERM, os.Interrupt)
defer stop()
<-ctx.Done()
hs.Shutdown() // все статусы NOT_SERVING, проба перестанет пускать трафик
done := make(chan struct{})
go func() { srv.GracefulStop(); close(done) }()
select {
case <-done:
case <-time.After(20 * time.Second):
srv.Stop() // оборвать то, что не успело
}GracefulStop закрывает порт, перестаёт принимать новые вызовы и ждёт, пока закончатся начатые. Открытый стрим может не закончиться никогда, поэтому без таймера под так и висит до SIGKILL. В тесте с открытым серверным стримом GracefulStop не вернулся и за 500 мс. После Stop контекст обработчика стрима отменился, а клиент получил Unavailable. Таймер берут меньше terminationGracePeriodSeconds пода, по умолчанию это 30 секунд
Тесты без сети
Пакет google.golang.org/grpc/test/bufconn даёт листенер в памяти. Настоящий сервер с настоящими интерсепторами поднимается в тесте за миллисекунды, порт не нужен:
Go · Тест сервиса через bufconn
func newClient(t *testing.T) ordersv1.OrderServiceClient {
lis := bufconn.Listen(1 << 20)
srv := grpc.NewServer(grpc.ChainUnaryInterceptor(recovery(slog.Default())))
ordersv1.RegisterOrderServiceServer(srv, &OrderServer{repo: fakeRepo{}})
go srv.Serve(lis)
conn, err := grpc.NewClient("passthrough:///bufnet",
grpc.WithContextDialer(func(ctx context.Context, _ string) (net.Conn, error) {
return lis.DialContext(ctx)
}),
grpc.WithTransportCredentials(insecure.NewCredentials()))
if err != nil {
t.Fatal(err)
}
t.Cleanup(func() { conn.Close(); srv.Stop() })
return ordersv1.NewOrderServiceClient(conn)
}Так проверяют то, что юнит-тест обработчика не видит: коды статусов на клиенте, детали ошибок, работу интерсепторов и стримов
⚠️ Где ошибаются
- Нет recovery-интерсептора. Одна паника в редком обработчике кладёт под целиком, вместе с сотнями вызовов, которые шли параллельно
- Обёрнутый статус.
fmt.Errorf("repo: %w", status.Error(codes.NotFound, ...))код сохранит, но текст для клиента станетrepo: rpc error: code = NotFound desc = заказ 404 не найден. Статус создают на границе сервиса, а оборачивают обычные ошибки до неё return nil, errс ошибкой из базы. Клиент увидитUnknownи текст SQL-запроса. Всё, что не распознано, превращают вInternalс нейтральным текстом, а подробности пишут в лог- Работа после дедлайна. Обработчик не смотрит на
ctxи честно досчитывает отчёт, который клиент уже не ждёт. Под нагрузкой такие вызовы копятся и съедают CPU и соединения к базе GracefulStopбез таймера. Один долгий стрим держит деплой доSIGKILL, а потом обрывается всё разом
🎯 Вопросы с собеседований
Как сгенерировать код из .proto в Go-проекте?
Нужны два плагина: protoc-gen-go генерирует структуры сообщений, protoc-gen-go-grpc — интерфейс сервера и клиента. Их запускает protoc или buf generate по конфигу buf.gen.yaml. Версии плагинов держу в go.mod через директиву tool, чтобы у всех генерировался одинаковый код. В CI запускаю buf lint и buf breaking против основной ветки, чтобы несовместимое изменение схемы не попало в мастер
Зачем встраивать UnimplementedXxxServer?
Чтобы сервис продолжал компилироваться, когда в .proto добавят метод. Новый метод берётся из встроенной структуры и отвечает клиентам Unimplemented, пока его не реализуют. Встраивают по значению: сгенерированный код проверяет это при регистрации, и с нулевым указателем сервис упадёт на старте
Что такое интерсептор и в каком порядке они выполняются?
Это middleware для gRPC: функция, которая получает контекст, запрос, имя метода и следующий обработчик. На них делают логирование, метрики, трейсинг, авторизацию, восстановление после паники. В ChainUnaryInterceptor первый интерсептор внешний, последний ближе всего к обработчику. Поэтому recovery ставят последним, иначе паника пролетит мимо логирования и метрик. Для стримов цепочка отдельная, ChainStreamInterceptor
Что будет, если в обработчике gRPC случится паника?
grpc-go её не перехватывает, и процесс падает целиком, вместе со всеми параллельными вызовами. В этом отличие от net/http, где сервер ловит панику хендлера и закрывает соединение. Поэтому в каждом сервисе стоит recovery-интерсептор, который превращает панику в codes.Internal и пишет стек в лог
Как вернуть клиенту ошибку валидации с подробностями?
Через status.New(codes.InvalidArgument, ...) и WithDetails с сообщением errdetails.BadRequest, где перечислены поля и причины. Детали уходят вместе со статусом, клиент читает их через status.Convert(err).Details(). Код статуса нужен клиенту для решения, повторять ли вызов, а детали — для того, чтобы показать человеку, что исправить
Что происходит на сервере, когда истёк дедлайн клиента?
Клиент сразу получает DeadlineExceeded, а у обработчика отменяется контекст. Сам обработчик никто не останавливает: если он не проверяет ctx, то доработает до конца впустую. Поэтому ctx передают во все вызовы базы и других сервисов, а в долгих циклах проверяют ctx.Err(). Ошибку контекста возвращают через status.FromContextError, иначе она запишется в метрики как Unknown
Как правильно выключить gRPC-сервер при деплое?
Поймать SIGTERM через signal.NotifyContext, перевести health-check в NOT_SERVING, чтобы на под перестал идти новый трафик, и вызвать GracefulStop. Он перестаёт принимать вызовы и ждёт начатые. Долгие стримы могут не закончиться никогда, поэтому рядом ставят таймер меньше terminationGracePeriodSeconds и по нему вызывают Stop
Как Kubernetes проверяет здоровье gRPC-сервиса?
Через стандартный протокол grpc.health.v1.Health: проба grpc в манифесте пода стабильна с Kubernetes 1.27 и не требует утилит в образе. В Go сервис уже реализован в пакете health, пустое имя означает весь сервер. Статус меняют через SetServingStatus, а при выключении вызывают Shutdown, который ставит NOT_SERVING всем
Как тестировать gRPC-сервис?
Логику обработчика можно проверить обычным юнит-тестом, вызвав метод структуры напрямую. Но коды статусов на клиенте, детали ошибок и интерсепторы так не проверить. Для этого поднимают настоящий grpc.Server на листенере из bufconn в памяти и ходят в него сгенерированным клиентом: без порта и сети, за миллисекунды
📚 Что почитать
- Interceptors на grpc.io — виды интерсепторов и для каких задач их берут
- Health Checking на grpc.io — протокол health-check,
CheckиWatch, смысл пустого имени сервиса - buf.gen.yaml v2 — все ключи конфига генерации, включая локальные плагины
- go-grpc-middleware — готовые интерсепторы и совет про порядок recovery