Protocol Buffers: бинарная сериализация

Protocol Buffers: бинарная сериализация

Protocol Buffers (protobuf) - бинарный формат от Google. В 3-10 раз компактнее JSON, в 5-100 раз быстрее в парсинге, строго типизирован, со схемой и автогенерацией кода. Стандарт де-факто для межсервисного общения.

Установка

# protoc compiler
brew install protobuf  # macOS
# apt install -y protobuf-compiler  # Linux

# Go плагины
go install google.golang.org/protobuf/cmd/protoc-gen-go@latest
go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@latest

Для PHP отдельно ставится PECL-расширение и плагин grpc_php_plugin (собирается из исходников gRPC). Composer-пакеты google/protobuf и grpc/grpc подключают runtime:

# Расширение ext-grpc (нужно для gRPC-клиента; сервер на PHP поднимается через RoadRunner)
pecl install grpc

# protoc compiler уже стоит, нужен plugin для PHP
# Собираем из grpc/grpc исходников. vX.Y.Z - последний релиз
# со страницы https://github.com/grpc/grpc/releases
git clone -b vX.Y.Z https://github.com/grpc/grpc
cd grpc && git submodule update --init
mkdir -p cmake/build && cd cmake/build
cmake ../..
make protoc grpc_php_plugin
sudo cp grpc_php_plugin /usr/local/bin/

# Composer-зависимости проекта
composer require grpc/grpc google/protobuf
{
    "require": {
        "php": "^8.2",
        "ext-grpc": "*",
        "grpc/grpc": "^1.57",
        "google/protobuf": "^4.28",
        "spiral/roadrunner-grpc": "^3.2"
    },
    "autoload": {
        "psr-4": {
            "App\\": "src/",
            "GPBMetadata\\": "generated/GPBMetadata/",
            "User\\": "generated/User/"
        }
    }
}

Первый .proto файл

syntax = "proto3";
package user;
option go_package = "github.com/example/user/pb";

message User {
  string id = 1;
  string name = 2;
  string email = 3;
  int32 age = 4;
  Role role = 5;
  repeated string tags = 6;
  optional string bio = 7;
}

enum Role {
  ROLE_UNSPECIFIED = 0;
  ROLE_USER = 1;
  ROLE_ADMIN = 2;
}

message CreateUserRequest {
  string name = 1;
  string email = 2;
}

message CreateUserResponse {
  User user = 1;
}

service UserService {
  rpc CreateUser(CreateUserRequest) returns (CreateUserResponse);
}

syntax = "proto3" - современная версия. Номера полей (1, 2, 3...) - ключевая идея: они кодируются в wire-формате, а не имена. Поэтому переименование поля не ломает бинарную совместимость (но ломает JSON-представление, где ключи - это имена полей, например через grpc-gateway из урока 5), а смена номера ломает всё.

У enum в proto3 первое значение обязано быть 0, и оно же значение по умолчанию: поле, которое не передали, читается как 0. Поэтому нулём делают ROLE_UNSPECIFIED - «не задано», чтобы забытое поле не превратилось молча в настоящую роль.

Wire format в двух словах

Каждое поле кодируется как [tag][value]. Tag = field_number << 3 | wire_type. Маленькие int (0-127) занимают 1 байт благодаря varint-кодированию. Строки и сообщения - длина + содержимое. Это даёт компактность и быструю десериализацию: парсер просто считывает теги один за другим.

Генерация кода

Pipeline: .proto файл компилируется protoc в Go server interface и Go client interface

protoc --go_out=. --go_opt=paths=source_relative \
 --go-grpc_out=. --go-grpc_opt=paths=source_relative \
       proto/user.proto

Создаются файлы user.pb.go (структуры и (Un)marshal) и user_grpc.pb.go (gRPC-сервисы). Второй файл появляется, только если в .proto объявлен хотя бы один service: без него плагину protoc-gen-go-grpc нечего генерировать. В CI обычно есть проверка, что сгенерированный код актуален относительно .proto.

Сгенерированный интерфейс сервера сам ничего не делает - его нужно реализовать и зарегистрировать в gRPC-сервере, а на другой стороне поднять клиент: этим занимается следующий урок. Тот же .proto пригодится ещё раз позже: по аннотациям в нём генерируется REST-прокси и OpenAPI-спека, чтобы к сервису мог обратиться браузер.

Для PHP та же команда с другими плагинами. --php_out генерирует Message-классы, --grpc_out с protoc-gen-grpc=grpc_php_plugin генерирует клиентские стабы:

protoc -I=./proto \
    --php_out=./generated \
    --grpc_out=./generated \
    --plugin=protoc-gen-grpc=$(which grpc_php_plugin) \
    proto/user.proto

Структура generated/: GPBMetadata/User.php (метаданные), User/User.php, User/CreateUserRequest.php, User/CreateUserResponse.php (классы сообщений), User/UserServiceClient.php (gRPC-клиент). Namespace классов берётся из package (user превращается в User\); переопределить его можно опцией option php_namespace. В CI добавляется шаг проверки, что generated/ соответствует свежей генерации (git diff --exit-code).

Использование сгенерированного кода

user := &pb.User{
    Id:    "123",
    Name:  "Alice",
    Email: "alice@example.com",
    Age:   30,
    Role:  pb.Role_ROLE_ADMIN,
    Tags:  []string{"backend", "go"},
}

// Сериализация
data, err := proto.Marshal(user)

// Десериализация
var decoded pb.User
err = proto.Unmarshal(data, &decoded)
<?php
declare(strict_types=1);

use User\User;
use User\Role;

$user = new User();
$user->setId('123')
    ->setName('Alice')
    ->setEmail('alice@example.com')
    ->setAge(30)
    ->setRole(Role::ROLE_ADMIN)
    ->setTags(['backend', 'php']);

// Сериализация
$data = $user->serializeToString();

// Десериализация
$decoded = new User();
$decoded->mergeFromString($data);

echo $decoded->getName(); // Alice

В PHP сгенерированные классы наследуются от \Google\Protobuf\Internal\Message. Сеттеры возвращают $this для fluent-стиля. Сериализация - метод serializeToString(), десериализация - mergeFromString().

# Генерация: python -m grpc_tools.protoc -I proto --python_out=. --pyi_out=. \
#     --grpc_python_out=. proto/user.proto
# Получаем user_pb2.py (сообщения) и user_pb2_grpc.py (сервисы), pyi - type hints.
import user_pb2 as pb

user = pb.User(
    id="123",
    name="Alice",
    email="alice@example.com",
    age=30,
    role=pb.Role.ROLE_ADMIN,
    tags=["backend", "python"],
)

# Сериализация
data: bytes = user.SerializeToString()

# Десериализация
decoded = pb.User()
decoded.ParseFromString(data)

print(decoded.name)  # Alice

Сгенерированные классы - подклассы google.protobuf.message.Message: поля заполняются через kwargs конструктора или присваиванием, repeated ведут себя как списки. Сериализация - SerializeToString(), десериализация - ParseFromString(); имена методов в CamelCase унаследованы от исходного API protobuf, а не от PEP 8.

oneof - взаимоисключающие поля

Когда нужно «либо одно, либо другое»:

message Notification {
  string user_id = 1;
  oneof channel {
    EmailChannel email = 2;
    SmsChannel sms = 3;
    PushChannel push = 4;
  }
}

В сообщении заполнено ровно одно поле из channel. Это discriminated union: в Go он разбирается через type switch, в PHP через match:

switch ch := notification.Channel.(type) {
case *pb.Notification_Email:
    sendEmail(ch.Email.Address)
case *pb.Notification_Sms:
    sendSms(ch.Sms.PhoneNumber)
}
<?php
declare(strict_types=1);

use Notification\Notification;

match ($notification->getChannel()) {
    'email' => $emailSender->send($notification->getEmail()->getAddress()),
    'sms'   => $smsSender->send($notification->getSms()->getPhoneNumber()),
    'push'  => $pushSender->send($notification->getPush()->getDeviceToken()),
    default => throw new LogicException('channel is not set'),
};

В PHP сгенерированный класс даёт метод getChannel() (возвращает имя выбранного поля как строку) и геттеры по конкретному полю. match идеально подходит для дискриминированного юниона.

# WhichOneof возвращает имя заполненного поля oneof (или None, если ни одно не задано).
match notification.WhichOneof("channel"):
    case "email":
        send_email(notification.email.address)
    case "sms":
        send_sms(notification.sms.phone_number)
    case "push":
        send_push(notification.push.device_token)
    case None:
        raise ValueError("channel is not set")

Сгенерированный класс даёт метод WhichOneof("channel") - аналог getChannel() из PHP - и обычные атрибуты по каждому полю. Обращение к незаполненному полю oneof не падает, а возвращает пустое сообщение, поэтому проверять нужно именно через WhichOneof.

map - словари

message UserAttributes {
  map<string, string> labels = 1;
  map<int32, User> users_by_id = 2;
}

Под капотом - список пар (key, value). Ключи - целочисленные типы, string или bool (не float, double, bytes и не enum), значения - что угодно, кроме map (нет вложенных map).

Well-known types - стандартные обёртки

import "google/protobuf/timestamp.proto";
import "google/protobuf/duration.proto";
import "google/protobuf/empty.proto";

message Event {
  google.protobuf.Timestamp created_at = 1;
  google.protobuf.Duration timeout = 2;
}

service Health {
  rpc Check(google.protobuf.Empty) returns (google.protobuf.Empty);
}

Используйте Timestamp вместо int64 unix-time - это переносимо и читаемо. Empty для запросов/ответов без параметров.

Protobuf vs JSON

ProtobufJSON
Размер3-10x меньшеБазовый
Скорость5-100x быстрееБазовый
ТипизацияСтрогаяНет
ЧитаемостьБинарныйДа
Backward compatВстроеннаяРучная

Правила backward compatibility

  • НЕ меняй номера полей - это сломает всех существующих клиентов
  • НЕ переиспользуй удалённые номера - используй reserved
  • Можно добавлять новые поля (старый код их проигнорирует)
  • Можно переименовывать поля (имя в wire format не используется), но это ломает JSON-клиентов: в JSON ключом служит имя поля
  • Можно добавлять enum-значения - старый клиент получит число, которого нет в его enum (например, 3), поэтому код должен обрабатывать неизвестные значения в default-ветке
  • НЕ меняй тип существующего поля (int32 ↔ string ломает wire format)
message User {
  reserved 4, 8;            // эти номера навсегда заняты
  reserved "phone", "fax";  // эти имена тоже
  string id = 1;
  string name = 2;
  // string phone = 4;  // ОШИБКА - поле зарезервировано
}

proto3 поля и nullability

В proto3 у скалярных полей нет понятия «не задано» - int32 age = 4 всегда возвращает 0, если не установлено. Если различие важно (например, age=0 vs age не передан), используй optional (proto3 v3.15+) или Int32Value из wrappers.proto.

Мини-практика

Создай .proto файл для сервиса задач (Todo): сообщения Task, CreateTaskRequest, ListTasksResponse. Используй oneof для статуса (открыта/в работе/закрыта с разными полями), Timestamp для дедлайна, map для меток. Сгенерируй Go-код через protoc и убедись, что компилируется.

Зарегистрируйтесь бесплатно, чтобы пройти квиз, вести прогресс.