Генерация кода с tonic-build

tonic-build запускается во время компиляции и преобразует файлы .proto в исходный код Rust. Он оборачивает prost-build для сообщений и дополняет его трейтами и клиентами служб gRPC.

Он запускается из скрипта сборки Cargo (build.rs), поэтому генерация автоматически выполняется до компиляции крейта.

Вам понадобятся крейты времени выполнения и крейт времени сборки. tonic и prost являются обычными зависимостями, а tonic-build указывается в разделе [build-dependencies].

tonic использует tokio как асинхронную среду выполнения, поэтому его тоже нужно подключить.

Создайте build.rs в корне крейта. Вызовите tonic_build::compile_protos, передав путь к файлу proto.

По умолчанию это компилирует код и клиента, и сервера и записывает его в OUT_DIR Cargo.

Для более точной настройки используйте tonic_build::configure(). Вы можете отключить генерацию клиента или сервера, задать пути вывода или добавить атрибуты типов.

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

Второй аргумент compile_protos — это список каталогов для поиска. Импорты внутри proto, например google/protobuf/empty.proto, разрешаются относительно этих корневых каталогов.

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

Сгенерированные файлы записываются в каталог из переменной окружения OUT_DIR и получают имя на основе пакета proto, например greeter.v1.rs.

Подключите их к своему крейту с помощью макроса include_proto! внутри модуля.

Для каждой службы tonic создаёт серверный модуль с трейтом (например, greeter_server::Greeter) и оболочкой GreeterServer, а также клиентскую структуру GreeterClient.

Каждое сообщение превращается в структуру Rust с производными реализациями Clone, PartialEq и Message из prost.

Часто для сгенерированных структур нужны дополнительные производные реализации, например serde::Serialize. Используйте type_attribute, чтобы добавить атрибуты к определённым типам или ко всем типам с помощью ..

Это позволяет передавать сгенерированные сообщения в JSON API или тестовые наборы данных.

Cargo повторно запускает build.rs только тогда, когда считает, что входные данные изменились. Выводите строки cargo:rerun-if-changed, чтобы изменения proto-файлов принудительно запускали генерацию.

Без этого изменённый proto может не обрабатываться заново, пока Вы не измените файл Rust.

Исторически tonic-build запускал компилятор protoc во внешнем процессе, поэтому его требовалось устанавливать отдельно. Современные версии могут использовать парсер protox на чистом Rust и не зависеть от него.

Если Вы видите ошибку об отсутствии protoc, установите protoc или включите функцию компилятора, поставляемого вместе с пакетом.

Для отражения или продвинутых инструментов попросите tonic-build создать набор дескрипторов файлов с помощью file_descriptor_set_path.

Полученные байты можно передать в tonic-reflection, чтобы инструменты вроде grpcurl могли обнаруживать Ваши службы во время выполнения.

Куда попадает сгенерированный tonic-код и как он подключается?

Вы подключили зависимости, написали build.rs, настроили генерацию клиента и сервера, а также пути поиска, подключили код через include_proto!, добавили производные реализации, настроили условия повторной сборки и узнали о protoc и наборах дескрипторов.

Далее Вы реализуете серверный трейт, созданный tonic.