К содержимому
Войти

Go Road Map

📡 gRPC-сервис на Go

Эта страница про то, как собрать gRPC-сервис на Go целиком: от .proto до сервера, который переживает панику, отдаёт понятные ошибки и спокойно выключается при деплое. Как устроен сам протокол, коды статусов и совместимость полей, разобрано на странице про gRPC и Protocol Buffers. Здесь — код, который пишут на работе, и вопросы, которые задают, когда видят gRPC в резюме

🧠 Как это устроено

Путь от контракта до работающего сервиса выглядит так:

  1. Пишешь .proto с сервисом и сообщениями
  2. Генератор превращает его в два файла: orders.pb.go со структурами сообщений (плагин protoc-gen-go) и orders_grpc.pb.go с интерфейсом сервера и клиентом (плагин protoc-gen-go-grpc)
  3. Пишешь структуру, которая реализует интерфейс OrderServiceServer
  4. Создаёшь grpc.Server, вешаешь на него интерсепторы, регистрируешь свой сервис, health-check и рефлексию
  5. Слушаешь порт и по сигналу останавливаешь сервер так, чтобы начатые вызовы успели закончиться

Сгенерированный код коммитят в репозиторий или генерируют в 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