Learn Rust Coding · Урок

Protobuf и определения сервисов

Описывайте API в формате proto.

Урок 1 из 413 шагов

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

Зачем нужны gRPC и Protobuf

gRPC — высокопроизводительный фреймворк RPC, построенный на HTTP/2 и буферах протокола. В Rust ящик tonic реализует gRPC от начала до конца.

Protobuf — это язык описания интерфейсов (IDL). Вы один раз описываете сообщения и службы в файле .proto, а генераторы кода создают строго типизированные заглушки клиента и сервера.

Структура файла .proto

Каждый файл proto объявляет версию синтаксиса и пакет. Пакет задаёт пространство имён для сгенерированных типов и предотвращает конфликты.

Для tonic используйте proto3. После генерации имя пакета преобразуется в путь к модулю Rust.

syntax = "proto3";

package greeter.v1;

Определение сообщений

Сообщение — это типизированная запись. У каждого поля есть тип, имя и уникальный номер, используемый для кодирования при передаче.

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

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

Скалярные типы и их соответствия в Rust

Скалярные типы Protobuf сопоставляются с типами Rust через prost. string преобразуется в String, int32 — в i32, bool — в bool, а bytes — в Vec<u8>.

В proto3 у каждого скалярного типа есть значение по умолчанию (пустая строка, 0, false); эти поля не являются необязательными, если это явно не указано.

message Metric {
  string label = 1;
  double value = 2;
  bool active = 3;
}

Определение службы

service объединяет методы RPC. Каждый rpc объявляет имя метода, сообщение запроса и сообщение ответа.

tonic создаёт из этого блока серверный трейт и клиентскую структуру. Реализация трейта позволяет определить поведение службы.

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

message HelloReply {
  string message = 1;
}

Четыре вида методов RPC

gRPC поддерживает четыре варианта потоковой передачи: унарный вызов, поток от сервера, поток от клиента и двунаправленный поток.

Поток обозначается ключевым словом stream со стороны запроса, ответа или с обеих сторон.

service Chat {
  rpc Unary (Msg) returns (Msg);
  rpc ServerStream (Msg) returns (stream Msg);
  rpc ClientStream (stream Msg) returns (Msg);
  rpc BiDi (stream Msg) returns (stream Msg);
}

Перечисления в Protobuf

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

prost создаёт перечисление Rust и вспомогательные средства для преобразования из базового типа i32, поскольку по сети могут поступать неизвестные значения.

enum Status {
  STATUS_UNKNOWN = 0;
  STATUS_ACTIVE = 1;
  STATUS_BANNED = 2;
}

Вложенные и повторяющиеся поля

Поле repeated представляет собой список и сопоставляется в Rust с Vec<T>. Сообщения можно вкладывать друг в друга или указывать по имени.

Это позволяет описывать коллекции и составные данные без лишних формальностей.

message Order {
  string id = 1;
  repeated Item items = 2;
}

message Item {
  string sku = 1;
  int32 qty = 2;
}

Пустой тип и известные типы

Для методов, которые ничего не принимают и не возвращают, импортируйте google/protobuf/empty.proto и используйте Empty.

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

import "google/protobuf/empty.proto";

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

Версионирование с помощью пакетов

Указание версии в пакете, например greeter.v1, позволяет безопасно развивать API. Несовместимое изменение добавляется в greeter.v2, а v1 продолжает обслуживать запросы.

Это соглашение сохраняет сгенерированные модули Rust понятными: greeter::v1 и greeter::v2 существуют одновременно.

package greeter.v1;
// later, a parallel file:
// package greeter.v2;

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

Добавление нового поля с новым номером обратно совместимо: старые клиенты его игнорируют. Удалять поле рискованно, если предварительно не зарезервировать его номер и имя с помощью reserve.

Резервирование не позволяет повторно использовать номер удалённого поля и нарушить декодирование.

message User {
  reserved 3, 5;
  reserved "legacy_token";
  string id = 1;
  string email = 2;
}

Быстрая проверка

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

Ответь в интерактивном уроке

Итоги

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

Далее Вы преобразуете эти определения в код Rust с помощью tonic-build.

Можно начать бесплатно

Изучай Rust с ИИ-репетитором — бесплатно

Пиши и запускай код прямо в браузере, получай мгновенную помощь от ИИ-репетитора 24/7 и продолжи учиться на сайте или в приложении.

Курсы: 39
Уроки: 144

Начать учиться бесплатно Посмотреть полный курс

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

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

Да — полный текст урока «Protobuf и определения сервисов» бесплатно доступен здесь в веб-версии. Чтобы практиковать его интерактивно (встроенный редактор кода и ИИ-репетитор 24/7) и разблокировать остальной курс Learn Rust Coding, подпишись на CoddyKit PRO. Курс Learn Rust Coding содержит 4 уроков всего.

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

Описывайте API в формате proto. Ты практикуешь Learn Rust Coding с помощью реального кода, который запускаешь прямо в браузере, и ИИ-репетитор 24/7 отвечает на твои вопросы во время урока.

Нужен ли мне опыт, чтобы начать Learn Rust Coding?

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

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

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

Можно ли писать и запускать код в этом уроке Learn Rust Coding?

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

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

← Назад к Learn Rust Coding