Protocol Buffers

Введение: Когда текста слишком много

Представьте, что вы пересылаете фотографию. Можно отправить её как текстовое описание: “красный квадрат 100x100 пикселей, в центре жёлтый круг”. Это понятно, но очень длинно. А можно отправить бинарный файл — сами байты картинки. Это нечитаемо для человека, но компьютер обработает его за доли секунды.

JSON и XML — как текстовое описание. Человек может прочитать, отредактировать, понять. Но они занимают много места и медленно парсятся.

Protocol Buffers (protobuf) — как бинарный файл. Компактный, быстрый, но нечитаемый. Это формат сериализации, разработанный Google для внутренних нужд. Он используется в gRPC, Kafka, многих микросервисных архитектурах.

Protocol Buffers — это не просто формат. Это целая экосистема: язык описания данных (.proto файлы), компилятор (protoc), генерация кода на 10+ языках. Вы описываете структуру данных один раз, а protobuf генерирует классы для сериализации и десериализации на любом языке.

Зачем нужны Protocol Buffers

Проблемы JSON и XML

Что предлагает protobuf

Основные концепции

.proto файл

Всё начинается с .proto файла — описания структур данных и сервисов.

syntax = "proto3";

package example.user;

// Сообщение (структура данных)
message User {
    int32 id = 1;           // поле с тегом 1
    string name = 2;        // поле с тегом 2
    string email = 3;       // поле с тегом 3
    int32 age = 4;          // поле с тегом 4
    Address address = 5;    // вложенное сообщение
    repeated string phones = 6;  // массив
}

message Address {
    string city = 1;
    string street = 2;
    int32 zip = 3;
}

// Сервис (для gRPC)
service UserService {
    rpc GetUser (GetUserRequest) returns (User);
    rpc CreateUser (CreateUserRequest) returns (User);
}

message GetUserRequest {
    int32 user_id = 1;
}

message CreateUserRequest {
    string name = 1;
    string email = 2;
    int32 age = 3;
}

Типы данных

Теги полей (Field tags)

Числа (1, 2, 3) — это теги, не значения. Они используются для идентификации полей в бинарном формате.

message User {
    int32 id = 1;        // тег 1
    string name = 2;     // тег 2
    string email = 3;    // тег 3
}

Правила тегов:

Важно: Теги нельзя менять. Если вы создали поле с тегом 2, оно останется с тегом 2 навсегда. Удалять поля можно, но тег не переиспользовать.

Правила совместимости

Сериализация в protobuf

Как данные превращаются в байты

Protobuf кодирует данные очень компактно.

Пример: сообщение User

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

Данные: id = 123, name = "Иван"

Кодирование:

Итого: 12 байт

Тот же объект в JSON: {"id":123,"name":"Иван"} — 27 байт

Экономия: более чем в 2 раза.

Wire types (как кодируются типы)

Varint (Variable-length integer):

• Маленькие числа (0-127) — 1 байт
• Большие числа — больше байт
• Эффективно для ID, счётчиков, порогов

ZigZag (для отрицательных):

• -1 → 1 (1 байт)
• 1 → 2 (1 байт)
• -2 → 3 (1 байт)

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

Установка protoc (компилятора protobuf)

# macOS
brew install protobuf

# Linux
apt install protobuf-compiler

# Windows
# Скачать с github.com/protocolbuffers/protobuf/releases

Установка плагинов для языка

# Go
go install google.golang.org/protobuf/cmd/protoc-gen-go@latest
go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@latest

# Python
pip install grpcio-tools

# Java (gradle plugin)
id 'com.google.protobuf' version '0.9.1'

# Node.js
npm install -g protoc-gen-js

Генерация

# Go
protoc --go_out=. --go-grpc_out=. user.proto

# Python
python -m grpc_tools.protoc -I. --python_out=. --grpc_python_out=. user.proto

# Java
protoc --java_out=. user.proto

Примеры использования

Go

// Сгенерированный код
import pb "example/proto/user"

// Сериализация
user := &pb.User{
    Id:    123,
    Name:  "Иван",
    Email: "ivan@example.com",
}
data, err := proto.Marshal(user)

// Десериализация
var parsed pb.User
err = proto.Unmarshal(data, &parsed)
fmt.Println(parsed.Name) // "Иван"

Python

import user_pb2

# Сериализация
user = user_pb2.User()
user.id = 123
user.name = "Иван"
user.email = "ivan@example.com"
data = user.SerializeToString()

# Десериализация
parsed = user_pb2.User()
parsed.ParseFromString(data)
print(parsed.name)  # "Иван"

Java

// Сгенерированный код
import com.example.UserProto.User;

// Сериализация
User user = User.newBuilder()
    .setId(123)
    .setName("Иван")
    .setEmail("ivan@example.com")
    .build();
byte[] data = user.toByteArray();

// Десериализация
User parsed = User.parseFrom(data);
System.out.println(parsed.getName()); // "Иван"

Protobuf vs JSON vs XML

Когда использовать protobuf

Идеальные сценарии

Плохие сценарии

Расширения и экосистема

gRPC

Protobuf + gRPC = идеальная пара для микросервисов.

service UserService {
    rpc GetUser (GetUserRequest) returns (User);
    rpc ListUsers (ListUsersRequest) returns (stream User);  // server streaming
    rpc CreateUsers (stream User) returns (Summary);        // client streaming
}

gRPC-Gateway

Генерирует REST API из .proto файлов.

protoc --grpc-gateway_out=. user.proto

Результат: Один .proto → gRPC сервер + REST прокси.

protoc-gen-doc

Генерирует документацию из .proto.

protoc --doc_out=. --doc_opt=markdown,user.md user.proto

Buf (инструмент для управления protobuf)

# Линтер, форматтер, разбивка на модули
buf lint
buf format
buf generate

Продвинутые возможности

Oneof (одно из полей)

message Response {
    oneof result {
        User user = 1;
        Error error = 2;
    }
}

В сообщении будет либо user, либо error, но не оба.

Any (любой тип)

import "google/protobuf/any.proto";

message Event {
    string type = 1;
    google.protobuf.Any payload = 2;
}

Timestamp (стандартный тип для времени)

import "google/protobuf/timestamp.proto";

message Order {
    int32 id = 1;
    google.protobuf.Timestamp created_at = 2;
}

Map (словарь)

message Config {
    map<string, string> settings = 1;
}

Опции полей

message User {
    int32 id = 1 [(deprecated) = true];
    string name = 2 [(my_option).description = "имя пользователя"];
}

Версионирование .proto

Стратегия 1: Новые поля (обратная совместимость)

// v1
message User {
    int32 id = 1;
    string name = 2;
}

// v2 (совместимо)
message User {
    int32 id = 1;
    string name = 2;
    string email = 3;      // новое поле
    string phone = 4;      // новое поле
}

Стратегия 2: Разные пакеты

// v1/user.proto
package user.v1;

// v2/user.proto
package user.v2;

Стратегия 3: Reserved для удалённых полей

message User {
    reserved 2, 5 to 7;      // зарезервированные теги
    reserved "old_field";    // зарезервированное имя
    int32 id = 1;
    string name = 3;
}

Распространённые ошибки

Ошибка 1: Менять теги

// Было
message User {
    int32 id = 1;
    string name = 2;
}

// Стало (несовместимо!)
message User {
    int32 user_id = 2;   // тег изменился
    string name = 1;     // тег изменился
}

Исправление: Не менять теги. Добавлять новые поля с новыми тегами.

Ошибка 2: Использовать protobuf для больших файлов

Protobuf не предназначен для сообщений > 100 МБ. Парсинг всего сообщения в память может быть проблемой.

Исправление: Для больших файлов используйте потоковую обработку или отдельный сервис (S3).

Ошибка 3: Не указывать package

// Плохо
message User {}

// Хорошо
package com.example.user.v1;
message User {}

Ошибка 4: Игнорировать совместимость

Удалили поле и переиспользовали тег для нового поля.

Исправление: Использовать reserved для удалённых полей.

Ошибка 5: Protobuf для публичного API

Сделали публичное API на protobuf. Внешние разработчики не могут использовать его из браузера.

Исправление: REST + JSON для публичных API. Protobuf для внутренних.

Резюме для системного аналитика

1. Protocol Buffers (protobuf) — бинарный формат сериализации от Google. Компактный, быстрый, со строгой схемой. Используется в gRPC, микросервисах, высоконагруженных системах.

2. Основные преимущества: размер в 3-10 раз меньше JSON, парсинг в 5-10 раз быстрее, строгая типизация, генерация кода на 10+ языках, обратная совместимость.

3. .proto файл — единый источник истины. Описывает сообщения и сервисы. Компилятор protoc генерирует код для нужного языка.

4. Теги полей — числа, идентифицирующие поля в бинарном формате. Теги 1-15 занимают 1 байт (для частых полей). Теги нельзя менять, можно только добавлять новые.

5. Совместимость: добавлять поля — можно, удалять — можно (но тег зарезервировать), менять тип или тег — нельзя.

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

7. Когда НЕ использовать: публичные API, человеко-читаемые данные, браузеры, маленькие проекты.