proto файлы: терминология, описание, использование

.proto файлы используются в Protocol Buffers (Protobuf) для определения структуры данных и сервисов в платформо-независимом формате. Они содержат контракт взаимодействия между системами и позволяют автоматически генерировать код для сериализации/десериализации данных, а также для работы с RPC-сервисами.

Вот обзор терминологии, базовых понятий и правил написания .proto файлов.

---

Основные элементы и терминология

1. syntax
   Указывает версию языка .proto (обычно proto3):
   
   Default

   syntax = "proto3";

   1 2	syntax = "proto3";

   • proto3 — текущая версия, с более строгими правилами и упрощениями по сравнению с proto2.
   • Обязательный элемент в начале файла.
2. package
   Определяет пространство имен для сообщений и сервисов в данном файле:
   
   Default

   package example;

   1 2	package example;

   Используется для организации структуры и предотвращения конфликтов имен.
3. option
   Устанавливает дополнительные настройки, такие как язык программирования или параметры генерации кода:
   
   Default

   option go_package = "internal/proto";

   1 2	option go_package = "internal/proto";

   Важен для правильной работы сгенерированного кода.
4. Сообщения (message)
   Описывают структуру данных, которая будет сериализоваться/десериализоваться:
   
   Default

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

   1 2 3 4 5

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

   • Каждое поле имеет уникальный номер (field number), который используется при сериализации.
   • Типы данных (например, string, int32, bool) строго определены.
5. RPC-сервисы (service)
   Определяют удаленные вызовы процедур (RPC):
   
   Default

   service Greeter { rpc SayHello (HelloRequest) returns (HelloReply); }

   1 2 3 4

   service Greeter {     rpc SayHello (HelloRequest) returns (HelloReply); }

   Описывает методы, которые клиент может вызывать на сервере.
6. Поле (field)
   • Каждое поле внутри message имеет:
     • Тип (например, int32, string).
     • Имя (например, name, age).
     • Номер (например, 1, 2).
7. Импорт (import)
   Позволяет использовать определения из других .proto файлов:
   
   Default

   import "common.proto";

   1 2	import "common.proto";

   Поддерживает реюз данных между сервисами.

Типы данных

1. Простые типы:
   • int32, int64 — целые числа.
   • float, double — числа с плавающей запятой.
   • string — строки UTF-8.
   • bool — булев тип (true/false).
2. Комплексные типы:
   • message — для сложных структур данных.
   • enum — для перечислений:
     
     Default

     enum Gender { UNKNOWN = 0; MALE = 1; FEMALE = 2; }

     1 2 3 4 5 6

     enum Gender {     UNKNOWN = 0;     MALE = 1;     FEMALE = 2; }

      
3. Повторяемые поля:
   • Используются для массивов:
     
     Default

     repeated string hobbies = 3;

     1 2	repeated string hobbies = 3;

      

Пример .proto файла

Правила и рекомендации

1. Имена и номера полей:
   • Номера полей должны быть уникальны в пределах одного сообщения.
   • Номера от 1 до 15 занимают меньше места при сериализации.
   • Не используйте зарезервированные номера 19000–19999.
2. Типы данных:
   • Выбирайте подходящие типы, чтобы минимизировать размер данных и повысить читаемость.
   • Используйте repeated для списков, но избегайте избыточных данных.
3. Расширяемость:
   • Никогда не изменяйте или удаляйте номера полей.
   • Для добавления новых данных просто добавьте новые поля с уникальными номерами.
4. Импорты:
   • Реюзайте сообщения, чтобы избегать дублирования.
5. Go-специфичные настройки: Указывайте option go_package для интеграции с Go проектами.

---

Как писать и использовать

1. Создание файла .proto: Напишите файл с учетом описанных правил и требований.
2. Генерация кода: Используйте protoc для генерации кода на нужном языке:
   
   Default

   protoc --go_out=. --go-grpc_out=. internal/proto/example.proto

   1 2	protoc --go_out=. --go-grpc_out=. internal/proto/example.proto

    
3. Использование сгенерированного кода:
   • Импортируйте сгенерированный пакет в коде.
   • Реализуйте сервер или клиент.
4. Тестирование: Проверьте совместимость между клиентом и сервером.

Часто задаваемые вопросы

Что произойдет, если изменить номер поля?

Старые версии системы не смогут правильно обработать измененные данные. Номера полей — это часть «публичного контракта».

Почему номера начинаются с 1?

Ноль зарезервирован как «значение по умолчанию», если поле не задано.

Чем отличаются proto2 и proto3?

• В proto3 значения по умолчанию задаются автоматически.
• proto2 поддерживает обязательные (required) и опциональные (optional) поля, которые в proto3 заменены на всегда опциональные.

---

.proto файлы — это сердце Protobuf. Их грамотное проектирование помогает избежать проблем с совместимостью и упрощает разработку распределенных систем.