gRPC & High Performance APIs · Урок

Определение схемы Protobuf

Научитесь определять сообщения и сервисы с помощью синтаксиса Protocol Buffers (Protobuf) для строгой типизации.

«Определение схемы Protobuf» — бесплатный урок gRPC & High Performance APIs на CoddyKit. Это урок 1 из 4. Ты можешь прочитать весь урок бесплатно ниже — а потом практиковать его прямо в браузере с встроенным редактором кода и ИИ-репетитором 24/7. Это часть пути обучения gRPC & High Performance APIs, и твой прогресс синхронизируется между веб-версией и приложением CoddyKit. Курс gRPC & High Performance APIs содержит 4 уроков всего.

What are Protocol Buffers?

Добро пожаловать! В этом уроке мы погрузимся в Protocol Buffers, которые часто называют Protobuf. Это ключевая технология для gRPC.

Protobuf — это нейтральный к языку и платформе расширяемый механизм сериализации структурированных данных. Представьте это как высокоэффективный способ определения и обмена данными.
Он похож на JSON или XML, но меньше, быстрее и проще.
gRPC использует Protobuf для определения интерфейса сервиса и структуры передаваемых сообщений.

The .proto File

Схемы Protobuf определяются в специальных файлах с расширением .proto. Эти файлы выступают в роли контрактов для ваших данных.

Каждый .proto файл начинается с объявления синтаксиса, обычно это syntax = "proto3";. Это указывает компилятору Protobuf, какую версию синтаксиса следует использовать.
Это критически важно для обеспечения прямой и обратной совместимости.

syntax = "proto3";

// Your Protobuf definitions go here

Defining Your First Message

В Protobuf сообщение (message) — это структурированная запись информации. Оно похоже на класс в объектно-ориентированном программировании или структуру (struct) в языке C.

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

syntax = "proto3";

message MyMessage {
  // fields will go here
}

Fields, Types & Numbers

Внутри сообщения вы определяете поля, каждое из которых имеет определенный тип данных и уникальный номер поля.

Тип данных: определяет тип данных (например, string, int32, bool).
Имя поля: уникальный идентификатор поля внутри сообщения.
Номер поля: уникальный положительный целочисленный тег (от 1 до 2²⁹-1). Эти числа критически важны для идентификации полей в бинарном формате и должны оставаться неизменными для обеспечения совместимости.

Common Scalar Data Types

Protobuf поддерживает ряд скалярных типов данных. Вот некоторые из наиболее распространенных:

int32, int64: целые числа.
float, double: числа с плавающей запятой.
bool: логический тип (true/false).
string: текст в кодировке UTF-8.
bytes: последовательности необработанных байтов.

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

Example: A Simple Person Message

Давайте определим сообщение Person с несколькими общими полями. Обратите внимание на уникальные номера, присвоенные каждому полю.

Эти номера похожи на уникальные идентификаторы для ваших фрагментов данных. Если вы измените имя поля, его номер должен остаться прежним, чтобы старые системы могли его распознать.

syntax = "proto3";

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

Using Enums for Fixed Choices

Иногда требуется, чтобы поле имело значение из предопределенного списка вариантов. Здесь на помощь приходят перечисления (enums).

Перечисления определяют набор именованных целочисленных констант.
Первое значение в перечислении должно быть 0, так как это значение по умолчанию, если поле не задано.

syntax = "proto3";

enum UserRole {
  GUEST = 0;
  MEMBER = 1;
  ADMIN = 2;
}

Example: User Message with Role

Теперь создадим сообщение User и включим в него наше перечисление UserRole в качестве поля. Это гарантирует, что роль пользователя может принимать только одно из определенных значений.

Это обеспечивает строгую типизацию и предотвращает отправку некорректных данных.

syntax = "proto3";

enum UserRole {
  GUEST = 0;
  MEMBER = 1;
  ADMIN = 2;
}

message User {
  string id = 1;
  string username = 2;
  UserRole role = 3;
}

Nesting Messages for Structure

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

Представьте это как объект внутри другого объекта в языках программирования.

syntax = "proto3";

message UserProfile {
  string email = 1;
  message Address {
    string street = 1;
    string city = 2;
    string zip_code = 3;
  }
  Address home_address = 2;
}

Quick Check: Protobuf Basics

Рассмотрим следующее определение сообщения Protobuf:

syntax = "proto3";

message Product {
  string name = 1;
  int32 price_cents = 2;
  bool in_stock = 3;
  enum ProductCategory {
    ELECTRONICS = 0;
    BOOKS = 1;
    CLOTHING = 2;
  }
  ProductCategory category = 4;
}

Recap: Protobuf Schema

Отличная работа! Вы изучили основы определения схем Protobuf:

Файлы .proto: контракт для ваших данных.
Сообщения (Messages): определения структурированных данных, похожие на классы.
Поля (Fields): каждое из них имеет тип, имя и уникальный номер поля.
Скалярные типы: распространенные типы, такие как string, int32, bool.
Перечисления (Enums): для предопределенных наборов значений, начинающихся с 0.
Вложенность: организация сложных данных путем встраивания сообщений.

Далее мы увидим, как превратить эти определения в код!

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

Урок «Определение схемы Protobuf» бесплатный?

Да — полный текст урока «Определение схемы Protobuf» бесплатно доступен здесь в веб-версии. Чтобы практиковать его интерактивно (встроенный редактор кода и ИИ-репетитор 24/7) и разблокировать остальной курс gRPC & High Performance APIs, подпишись на CoddyKit PRO. Курс gRPC & High Performance APIs содержит 4 уроков всего.

Чему я научусь в уроке «Определение схемы Protobuf»?

Научитесь определять сообщения и сервисы с помощью синтаксиса Protocol Buffers (Protobuf) для строгой типизации. Ты практикуешь gRPC & High Performance APIs с помощью реального кода, который запускаешь прямо в браузере, и ИИ-репетитор 24/7 отвечает на твои вопросы во время урока.

Нужен ли мне опыт, чтобы начать gRPC & High Performance APIs?

Предыдущий опыт не требуется. gRPC & High Performance APIs на CoddyKit структурирован для всех уровней — от новичков до продвинутых, поэтому ты можешь начать отсюда или с самого начала и учиться в своем темпе. Это урок 1 из 4.

Сколько времени занимает урок «Определение схемы Protobuf»?

Большинство уроков CoddyKit занимают около 5–10 минут. Каждый из них компактный и интерактивный, поэтому ты постоянно делаешь прогресс и продолжаешь с того же места в веб-версии и приложении.

Можно ли писать и запускать код в этом уроке gRPC & High Performance APIs?

Да. Каждый урок gRPC & High Performance APIs включает встроенный редактор кода, поэтому ты пишешь и запускаешь реальный код прямо в браузере и получаешь моментальную обратную связь от AI — локальная установка не требуется.

Все уроки этого курса

Определение схемы Protobuf
Генерация кода gRPC
Простой однонаправленный сервис gRPC
Потоковые RPC: серверные, клиентские и двунаправленные

← Назад к gRPC & High Performance APIs