Gerando código com tonic-build

tonic-build é executado durante a compilação e transforma seus arquivos .proto em código-fonte Rust. Ele encapsula prost-build para as mensagens e acrescenta os traços de serviço gRPC e os clientes.

Ele é executado a partir de um script de compilação do Cargo (build.rs), portanto a geração ocorre automaticamente antes da compilação do seu crate.

Você precisa de crates de execução e de um crate usado durante a compilação. tonic e prost são dependências normais; tonic-build fica em [build-dependencies].

tonic depende de tokio como seu ambiente de execução assíncrono, portanto inclua-o também.

Crie build.rs na raiz do crate. Chame tonic_build::compile_protos passando o caminho para o arquivo proto.

Por padrão, isso compila o código do cliente e do servidor e o grava em OUT_DIR do Cargo.

Para ter mais controle, use tonic_build::configure(). Você pode desativar a geração do cliente ou do servidor, definir caminhos de saída ou adicionar atributos de tipo.

Aqui geramos o servidor, mas ignoramos o cliente, o que é útil para um crate exclusivo de back-end.

O segundo argumento de compile_protos é a lista de diretórios de inclusão. As importações dentro do seu proto, como google/protobuf/empty.proto, são resolvidas em relação a essas raízes.

Sempre inclua o diretório que contém seus arquivos proto, para que as importações entre arquivos sejam resolvidas.

Os arquivos gerados são gravados no diretório indicado pela variável de ambiente OUT_DIR, com nomes baseados no pacote proto, por exemplo greeter.v1.rs.

Você os inclui no crate com a macro include_proto! dentro de um módulo.

Para cada serviço, tonic produz um módulo de servidor com um traço (por exemplo, greeter_server::Greeter) e um invólucro GreeterServer, além de uma estrutura de cliente GreeterClient.

Cada mensagem se torna uma estrutura Rust que deriva Clone, PartialEq e o Message do prost.

É comum querer derivações adicionais nas estruturas geradas, como serde::Serialize. Use type_attribute para injetar atributos em tipos específicos ou em todos eles com ..

Isso permite que as mensagens geradas sejam usadas em APIs JSON ou em dados de teste.

O Cargo executa novamente build.rs apenas quando entende que as entradas foram alteradas. Emita linhas cargo:rerun-if-changed para que as edições nos arquivos proto forcem a regeneração.

Sem isso, um proto alterado talvez não seja regenerado até que você modifique um arquivo Rust.

Historicamente, tonic-build executava o compilador protoc externamente, e ele precisava estar instalado. As versões modernas podem usar o analisador protox, escrito totalmente em Rust, para evitar essa dependência.

Se você vir um erro indicando que o protoc não foi encontrado, instale o protoc ou ative um recurso de compilador incorporado.

Para reflexão ou ferramentas avançadas, peça ao tonic-build que emita um conjunto de descritores de arquivos com file_descriptor_set_path.

Os bytes resultantes podem alimentar tonic-reflection, permitindo que ferramentas como grpcurl descubram seus serviços durante a execução.

Para onde vai o código gerado pelo tonic e como ele é carregado?

Você configurou as dependências, escreveu um build.rs, configurou a geração do cliente e do servidor e os caminhos de inclusão, carregou o código por meio de include_proto!, adicionou derivações, tratou os gatilhos de recompilação e aprendeu sobre protoc e conjuntos de descritores.

Em seguida, você implementará o traço de servidor gerado pelo tonic.