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

Go Road Map

⚙️ gRPC и Protocol Buffers

gRPC — способ, которым сервисы внутри компании вызывают друг друга: контракт пишут в .proto-файле, из него генерируют клиент и сервер, а данные идут в бинарном protobuf поверх HTTP/2. Чаще всего его просят в вакансиях Go: в нашем срезе это 53% вакансий мидлов и 49% сеньоров, у Node.js-мидлов — 8%. На собеседовании спрашивают, как он устроен, чем лучше REST, какие бывают стримы и что будет, если удалить поле из сообщения. Страница опирается на разборы HTTP/2 и REST API из этого модуля

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

Контракт в .proto

Всё начинается с описания сервиса и сообщений:

syntax = "proto3";

package orders.v1;

service OrderService {
  rpc GetOrder(GetOrderRequest) returns (Order);
}

message GetOrderRequest {
  int64 id = 1;
}

message Order {
  int64 id = 1;
  string customer = 2;
  int64 total_kopecks = 3;
  OrderStatus status = 4;
}

enum OrderStatus {
  ORDER_STATUS_UNSPECIFIED = 0;
  ORDER_STATUS_PAID = 1;
  ORDER_STATUS_SHIPPED = 2;
}

Компилятор protoc (или buf generate) с плагинами protoc-gen-go и protoc-gen-go-grpc превращает файл в Go-код: структуры сообщений, интерфейс OrderServiceServer, который реализуешь ты, и готовый клиент. Клиент вызывает client.GetOrder(ctx, req) как обычную функцию, а сериализация, сеть и ошибки спрятаны в сгенерированном коде. Этот файл и есть контракт: его кладут в общий репозиторий, и все команды генерируют код из одного источника

Что идёт по сети

Вызов gRPC — это один поток HTTP/2. Метод превращается в путь: :path = /orders.v1.OrderService/GetOrder, метод всегда POST, content-type: application/grpc. Каждое сообщение в теле идёт с префиксом в 5 байт: 1 байт флага сжатия и 4 байта длины. Так в одном потоке можно передать сколько угодно сообщений подряд, и на этом держатся стримы

Ответ устроен необычно. HTTP-статус почти всегда 200, а настоящий результат вызова приходит в трейлерах — заголовках после тела: grpc-status: 0 и grpc-message с текстом ошибки. Протокол требует слать статус в трейлерах даже при успехе. Поэтому прокси, которые не умеют трейлеры, ломают gRPC, а браузерный fetch не может говорить с gRPC-сервером напрямую: для этого есть gRPC-Web и прокси вроде Envoy между браузером и сервисом

Дедлайн клиент передаёт заголовком grpc-timeout, например 1S. Если его нет, сервер считает, что ждать можно бесконечно

Protobuf на проводе

В бинарном сообщении нет имён полей, только номера и типы. Каждое поле начинается с тега (номер << 3) | тип_на_проводе, дальше значение. Типов на проводе немного: varint для целых, bool и enum, LEN для строк, байтов и вложенных сообщений, fixed32 и fixed64 для чисел фиксированной длины. Числа пишутся varint: 150 занимает 2 байта, а не 8

Отсюда все правила совместимости. Имя поля можно переименовать безопасно: на проводе его нет. Номер поля менять нельзя: старый клиент прочитает чужие данные или не найдёт свои. Незнакомое поле парсер пропускает, потому что по типу знает его длину, а сообщения proto3 сохраняют такие поля при повторной сериализации

Четыре вида вызовов

ВидВ .protoПример
Унарныйrpc Get(Req) returns (Resp)получить заказ по id
Серверный стримreturns (stream Resp)подписка на события заказов, выгрузка большого списка порциями
Клиентский стримrpc Upload(stream Chunk) returns (Resp)загрузка файла частями, пачка метрик
Двунаправленный(stream Req) returns (stream Resp)чат, обмен командами с агентом

Внутри одного вызова порядок сообщений гарантирован. В двунаправленном стриме две стороны пишут и читают независимо, в любом порядке

🛠️ На практике

Сервер и ошибки

Ошибку сервер возвращает не произвольным error, а статусом с кодом. Иначе клиент получит Unknown и не поймёт, повторять ли запрос:

func (s *server) GetOrder(ctx context.Context, req *ordersv1.GetOrderRequest) (*ordersv1.Order, error) {
	if req.GetId() <= 0 {
		return nil, status.Error(codes.InvalidArgument, "id должен быть положительным")
	}
	o, err := s.repo.Get(ctx, req.GetId())
	if errors.Is(err, repo.ErrNotFound) {
		return nil, status.Errorf(codes.NotFound, "заказ %d не найден", req.GetId())
	}
	if err != nil {
		return nil, status.Error(codes.Internal, "не удалось прочитать заказ")
	}
	return o, nil
}

Кодов 17, от OK (0) до Unauthenticated (16). Чаще всего нужны эти:

КодКогдаАналог в HTTP
InvalidArgumentзапрос неверен сам по себе400
NotFoundобъекта нет404
AlreadyExistsтакой объект уже создан409
FailedPreconditionсистема не в том состоянии, повтор не поможет400
Unauthenticated и PermissionDeniedнет учётных данных или прав401 и 403
ResourceExhaustedквота кончилась или сообщение больше лимита429
Unavailableсервис временно недоступен, можно повторить с паузой503
DeadlineExceededдедлайн истёк504

Библиотека gRPC сама никогда не возвращает InvalidArgument, NotFound, AlreadyExists и ещё четыре кода. Если клиент их видит, их вернул код приложения

Клиент и дедлайн

conn, err := grpc.NewClient("dns:///orders:50051",
	grpc.WithTransportCredentials(insecure.NewCredentials()))
if err != nil {
	return err
}
defer conn.Close()

client := ordersv1.NewOrderServiceClient(conn)

ctx, cancel := context.WithTimeout(ctx, 300*time.Millisecond)
defer cancel()

order, err := client.GetOrder(ctx, &ordersv1.GetOrderRequest{Id: 42})
if status.Code(err) == codes.NotFound {
	// заказа нет: это не сбой, повторять не нужно
}

grpc.NewClient пришёл на смену grpc.Dial, который помечен устаревшим. Он ничего не делает с сетью при создании: соединение откроется на первом вызове. Создают его один раз на сервис и переиспользуют, а не на каждый запрос

По умолчанию дедлайна нет, и клиент может ждать ответа вечно. В Go дедлайн берётся из context, а сервер, который сам зовёт следующий сервис с тем же ctx, передаёт ему остаток времени. Если клиенту дали 2 секунды, а первый сервис потратил 0,5, второй получит grpc-timeout на 1,5 секунды. Когда время вышло, сервер отменяет вызов, но остановить свою работу должен сам: проверяй ctx.Err() в долгих циклах

Совместимость сообщений, запущенный пример

Чтобы увидеть, почему номера полей важнее имён, можно собрать сообщение руками через пакет protowire из официальной библиотеки:

Go · Старый сервер читает сообщение нового клиента

package main

import (
	"fmt"

	"google.golang.org/protobuf/encoding/protowire"
)

func main() {
	// Новый клиент: message User { int64 id = 1; string name = 2; bool vip = 3; }
	var b []byte
	b = protowire.AppendTag(b, 1, protowire.VarintType)
	b = protowire.AppendVarint(b, 150)
	b = protowire.AppendTag(b, 2, protowire.BytesType)
	b = protowire.AppendString(b, "ann")
	b = protowire.AppendTag(b, 3, protowire.VarintType)
	b = protowire.AppendVarint(b, 1)
	fmt.Printf("% x\n", b)

	// Старый сервер знает только поля 1 и 2. Имён на проводе нет, только номера
	for len(b) > 0 {
		num, typ, n := protowire.ConsumeTag(b)
		b = b[n:]
		m := protowire.ConsumeFieldValue(num, typ, b)
		switch num {
		case 1:
			v, _ := protowire.ConsumeVarint(b)
			fmt.Println("поле 1 (id):", v)
		case 2:
			s, _ := protowire.ConsumeString(b)
			fmt.Println("поле 2 (name):", s)
		default:
			fmt.Printf("поле %d неизвестно, пропускаю %d байт\n", num, m)
		}
		b = b[m:]
	}
}

Вывод:

08 96 01 12 03 61 6e 6e 18 01
поле 1 (id): 150
поле 2 (name): ann
поле 3 неизвестно, пропускаю 1 байт

08 — тег поля 1 с типом varint. Следом 96 01, это число 150. Пара 12 03 означает поле 2 типа LEN длиной 3 байта, дальше ann. Старый сервер не знает поле 3, но по типу понимает, сколько байт пропустить, и не падает. Так и работает обратная совместимость: добавлять поля можно в любой момент

Правила эволюции схемы коротко:

  • можно: добавить поле с новым номером, переименовать поле, добавить значение в enum
  • нельзя: поменять номер поля, переиспользовать номер удалённого поля, поменять тип поля
  • удалённое поле помечают reserved 3; и reserved "vip";, тогда protoc не даст занять номер снова
  • первое значение enum — ..._UNSPECIFIED = 0: им становится любое неустановленное поле, и оно не должно значить что-то реальное

Номера от 1 до 15 занимают 1 байт тега, от 16 до 2047 — два. Самые частые поля держат в первом диапазоне. Номера 19000–19999 зарезервированы самой библиотекой

Когда gRPC, а когда REST

gRPCREST с JSON
Контракт.proto, код генерируетсяOpenAPI, если команда его ведёт
Форматбинарный, компактный, без имён полейтекст, читается глазами и в curl
Стримычетыре вида из коробкиSSE, WebSocket или опрос
Браузертолько через gRPC-Web и проксиработает везде
Отладкаgrpcurl, рефлексия сервералюбой HTTP-клиент
Кэш HTTPне работает, всё POSTGET кэшируется прокси и CDN

Обычно снаружи для браузера, мобильных приложений и партнёров оставляют REST, а между своими сервисами ставят gRPC. Внутри его выгода видна сразу: контракт один на все команды, клиенты для Go, Java и Python генерируются из него же, а сообщение из примера выше занимает 10 байт против 34 у того же объекта в JSON

⚠️ Где ошибаются

  • Нет дедлайна у клиента. Один медленный сервис держит горутины и соединения у всех, кто его зовёт, и отказ расползается по цепочке. Дедлайн ставят на каждый вызов, а внутри цепочки передают тот же ctx
  • gRPC за балансировщиком L4. HTTP/2 держит одно долгое TCP-соединение и гонит по нему все запросы. Обычный Service в Kubernetes балансирует соединения, а не запросы, и вся нагрузка от клиента уходит в один под, даже если их десять. Нужна балансировка по запросам: L7-прокси (Envoy, service mesh) или клиентская балансировка через headless Service с политикой round_robin
  • Переиспользование номера поля. Поле 5 удалили, через полгода добавили новое тоже с номером 5. Старые клиенты и сообщения, сохранённые в Kafka или логах, прочитаются как мусор. Удалённый номер — сразу в reserved
  • Ошибка без кода. return nil, err с ошибкой из базы клиент получит как Unknown с текстом SQL-запроса внутри. Код статуса выбирают осознанно, а детали базы наружу не отдают
  • Повторы неидемпотентных вызовов. Unavailable можно повторить, но если запрос успел дойти до сервера, повтор создаст второй заказ. Политику повторов включают только для методов, которые безопасно вызвать дважды, или передают ключ идемпотентности, как в REST

🎯 Вопросы с собеседований

Что такое gRPC и чем он лучше REST?

gRPC — фреймворк удалённого вызова процедур: контракт описывают в .proto, из него генерируют клиент и сервер для разных языков, данные идут в protobuf поверх HTTP/2. Плюсы перед REST с JSON: строгий контракт и сгенерированный код без ручной сериализации, компактный бинарный формат, мультиплексирование по одному соединению и стримы из коробки. Минусы: браузер не работает с ним напрямую, нужен gRPC-Web, сообщения не прочитать глазами, не работает HTTP-кэширование. Поэтому его обычно берут для общения сервисов внутри, а наружу отдают REST

Какие виды вызовов есть в gRPC?

Четыре. Унарный — один запрос, один ответ, как обычная функция. Серверный стрим — один запрос и поток ответов, например подписка на события. Клиентский стрим — поток запросов и один ответ, например загрузка файла частями. Двунаправленный — обе стороны шлют потоки независимо, например чат. Внутри одного вызова порядок сообщений сохраняется, а технически любой вызов — это один поток HTTP/2

Почему gRPC работает поверх HTTP/2, а не HTTP/1.1?

HTTP/2 мультиплексирует много вызовов в одном TCP-соединении, поэтому не нужен пул соединений и нет блокировки очереди на уровне HTTP. Он двунаправленный и потоковый, без этого не было бы стримов. И у него есть трейлеры, в которых gRPC передаёт статус вызова после тела ответа. Сжатие заголовков HPACK экономит байты на повторяющихся метаданных вроде токена

Что будет, если удалить поле из protobuf-сообщения или поменять его номер?

Удалить поле можно: старые клиенты будут слать его, а новый сервер пропустит как неизвестное. Но номер удалённого поля нужно пометить reserved, иначе кто-нибудь займёт его новым полем, и старые данные прочитаются как значение другого поля. Сменить номер — то же самое, что удалить поле и создать новое: старые и новые клиенты перестанут понимать друг друга. Переименовать поле безопасно для бинарного формата, потому что на проводе только номера, но сломает JSON-представление, если оно используется

Как в gRPC работают дедлайны?

Клиент задаёт время, после которого ответ ему не нужен, и оно уходит на сервер в заголовке grpc-timeout. По умолчанию дедлайна нет, поэтому его всегда ставят явно. В Go дедлайн живёт в context, и если сервер зовёт дальше с тем же ctx, следующий сервис получает остаток времени, а не исходное значение. Когда время вышло, клиент получает DeadlineExceeded, а сервер отменяет контекст, но остановить работу должен сам код обработчика

Почему gRPC плохо балансируется в Kubernetes?

Обычный Service балансирует на уровне TCP-соединений. HTTP/2 держит одно долгое соединение, по которому идут все вызовы клиента, поэтому они все попадают в один под, а остальные простаивают. Решение — балансировать отдельные вызовы: L7-прокси вроде Envoy или Linkerd, или клиентская балансировка, когда клиент через headless Service получает адреса всех подов и раскидывает вызовы по round_robin

Как вернуть ошибку из gRPC-метода?

Через status.Error(codes.X, "текст"). Код говорит клиенту, что делать: InvalidArgument и NotFound повторять бессмысленно, Unavailable можно повторить с паузой. Если вернуть обычный error, клиент получит Unknown и не отличит баг от временного сбоя. Для подробностей, например списка невалидных полей, к статусу добавляют детали — protobuf-сообщения, которые идут в трейлере grpc-status-details-bin

📚 Что почитать

  • Core concepts на grpc.io — виды вызовов, жизненный цикл, дедлайны и отмена от авторов gRPC
  • gRPC over HTTP2 — короткая спецификация того, что именно лежит в заголовках, теле и трейлерах
  • Proto Best Practices — правила эволюции схемы с объяснением, почему каждое нарушение ломает чтение
  • gRPC Load Balancing on Kubernetes without Tears — разбор, почему все вызовы уходят в один под и как это чинят