Protocol Buffers: сердце gRPC

Если gRPC — это двигатель взаимодействия сервисов, то Protocol Buffers (protobuf) — это его сердце.
Именно protobuf определяет, как описываются данные, как они сериализуются, и как из одной схемы генерируются типобезопасные классы для разных языков.

Чтобы по-настоящему понимать gRPC, нужно уверенно работать с .proto-файлами.

1. Что такое .proto файл

.proto — это файл описания структуры данных и интерфейсов (API).

Он играет сразу три роли:
Документирует контракт между клиентом и сервером (описывает, какие методы и какие данные доступны).
Генерирует код для разных языков с помощью protoc (компилятора Protocol Buffers).
Определяет схему сериализации — то, как объекты превращаются в байты и обратно.
Фактически .proto — это единый источник правды для вашего API.


2. Базовая структура .proto файла

Пример простого файла:

syntax = "proto3";

package car;

option java_multiple_files = true;
option java_package = "com.example.car";
option java_outer_classname = "CarProto";

// Определение сообщений
message Car {
  string model = 1;
  int32 year = 2;
  CarStatus status = 3;
}

// Перечисление (enum)
enum CarStatus {
  ACTIVE = 0;
  INACTIVE = 1;
}

// Определение сервиса
service CarService {
  rpc BuyCar (CarRequest) returns (CarResponse);
}

message CarRequest {
  string model = 1;
}

message CarResponse {
  string confirmation = 1;
}

3. Ключевые элементы .proto

3.1. syntax

Первая строка файла:

syntax = "proto3";

Обязательно указывает версию синтаксиса.
На практике используется только proto3, потому что она проще, строже типизирована и лучше поддерживается в gRPC.

3.2. package

Задает логическое пространство имён, чтобы избежать конфликтов:

package car;

В Java и других языках это превращается в пакеты/модули.

3.3. option

Позволяет задавать настройки генерации кода, например:

option java_package = "com.example.car";
option java_multiple_files = true;
option java_outer_classname = "CarProto";

Без этого весь код попадёт в один файл, что неудобно для больших схем.

3.4. message — описание структуры данных

message — это аналог класса в объектно-ориентированных языках.
Каждое поле внутри него — это свойство (переменная), которое сериализуется в бинарный поток.

Пример:

message User {
  string name = 1;
  int32 age = 2;
  repeated string hobbies = 3;
}


string name = 1; — поле с типом string и номером 1.

int32 age = 2; — целочисленное поле.

repeated string hobbies = 3; — массив строк.

Важно: номер поля (= 1, = 2, = 3) — это не просто индекс. Это ключ в бинарной сериализации, который должен быть уникален и неизменен.

3.5. enum — перечисление значений

enum — это список допустимых констант.

enum CarStatus {
  ACTIVE = 0;
  INACTIVE = 1;
  SOLD = 2;
}

Значение 0 обязательно — это значение по умолчанию.

При сериализации хранится не текстовое имя ("ACTIVE"), а его числовое значение (0), что делает protobuf компактным.

3.6. service — описание API

service определяет набор удалённых методов, которые сервер предоставляет клиенту.

Это аналог интерфейса в Java:

service CarService {
  rpc BuyCar (CarRequest) returns (CarResponse);
  rpc ListCars (Empty) returns (CarList);
}

Каждый rpc определяет:
имя метода (BuyCar),
входной тип (CarRequest),
выходной тип (CarResponse).

4. Типы данных в Protocol Buffers

Protobuf поддерживает ограниченный, но универсальный набор типов.

Некоторые часто используемые:

string - Текст
bool - Логическое значение
int32, int64 - Целые числа
float, double - Числа с плавающей точкой
bytes - Массив байтов
repeated - Массив
map<key, value> - Словарь

Пример:

message Garage {
  map<string, Car> cars = 1;
}

#Java #middle #gRPC #proto

5. Нумерация полей — почему это критично

Каждое поле имеет свой уникальный номер — это его идентификатор в бинарном потоке.

message Car {
  string model = 1;
  int32 year = 2;
}

Если поменять номера, клиент и сервер перестанут понимать друг друга.
Например, если у старой версии клиента year = 2, а у новой year = 3, при сериализации они будут читать разные данные.


6. Почему важно резервировать поля

Когда вы удаляете или переименовываете поле, нельзя просто убрать строку — нужно зарезервировать номер и имя.

Пример:

message Car {
  string model = 1;
  reserved 2;             // резервируем номер
  reserved "status_old";  // резервируем имя
}

Это предотвращает случайное переиспользование старого номера под другое поле, что может привести к неправильной интерпретации данных.


7. Эволюция и миграция схем (Schema Evolution)

Protobuf специально спроектирован так, чтобы позволять обновлять схемы без поломки совместимости.
Главное — соблюдать несколько правил.

Что можно делать безопасно:
Добавлять новые поля с новыми номерами.
Удалять поля (с их резервированием).
Изменять имя поля (номер должен остаться прежним).
Изменять порядок полей — не влияет на сериализацию.

Что делать нельзя:
Менять тип поля (например, int32 → string).
Менять номер поля.
Удалять поле без reserved.

Пример миграции

Старая версия:

message User {
  string name = 1;
  int32 age = 2;
}

Новая версия:

message User {
  string name = 1;
  reserved 2;
  string email = 3;
}

Старый клиент, который не знает про email, просто проигнорирует это поле.
А новый клиент не столкнётся с конфликтом, потому что старый 2 зарезервирован.


8. Компиляция .proto файла и генерация кода

protoc — компилятор, который читает .proto и создаёт Java-классы.

Пример команды:

protoc \
  --java_out=./build/generated \
  --grpc-java_out=./build/generated \
  proto/car.proto

Результат:
Для каждого message создаются классы с Builder-паттерном.
Для service создаются классы CarServiceGrpc, CarServiceImplBase, CarServiceStub.


9. Пример полного цикла

Файл car.proto:

syntax = "proto3";

service CarService {
  rpc BuyCar (CarRequest) returns (CarResponse);
}

message CarRequest {
  string model = 1;
  int32 budget = 2;
}

message CarResponse {
  string message = 1;
}

Сгенерированный код в Java (упрощённо):

// Отправитель (клиент)
CarRequest request = CarRequest.newBuilder()
    .setModel("BMW")
    .setBudget(20000)
    .build();

CarResponse response = stub.buyCar(request);
System.out.println(response.getMessage());

Серверная реализация:

public class CarServiceImpl extends CarServiceGrpc.CarServiceImplBase {
    @Override
    public void buyCar(CarRequest request, StreamObserver<CarResponse> responseObserver) {
        String msg = "Car purchased: " + request.getModel();
        CarResponse response = CarResponse.newBuilder().setMessage(msg).build();

        responseObserver.onNext(response);
        responseObserver.onCompleted();
    }
}

#Java #middle #gRPC #proto