protoc-gen-tonic

A protoc 插件，使用 Tonic 生成 gRPC 服务器和客户端代码，使用 Prost! 代码生成引擎。

当在仅使用 Rust 代码的项目中使用时，使用 Tonic 生成 gRPC 服务的首选机制是在 build.rs 文件中使用 tonic-build。然而，在多语言环境中，利用 Protocol Buffers 生态系统中的常用工具可能更有优势。这类工具之一是 buf，它可以简化代码生成过程，并包括一些有用的功能，如 linting、包管理和破坏性更改检测。

用法

确保 protoc-gen-tonic 已安装在您的 $PATH 上的目录中。然后从命令行按如下方式调用 protoc

protoc --tonic_out=proto/gen -I proto proto/greeter/v1/greeter.proto

选项

此工具支持所有来自 tonic-build 的选项，但不包括那些预期已在之前的 protoc-gen-prost 步骤中完全处理的选项。有关这些设置的影响信息，请参阅 tonic-build 的相关文档。

• default_package_filename=<value>: default_package_filename
• extern_path=<proto_path>=<rust_path>: extern_path
• compile_well_known_types(=<boolean>): 编译已知类型
• disable_package_emission(=<boolean>): 禁用包输出
• server_attribute=<proto_path>=<attribute>: 服务器属性
• server_mod_attribute=<proto_path>=<attribute>: 服务器模块属性
• client_attribute=<proto_path>=<attribute>: 客户端属性
• client_mod_attribute=<proto_path>=<attribute>: 客户端模块属性

此外，还可以指定以下选项

• no_server(=<boolean>): 禁止生成服务器模块
• no_client(=<boolean>): 禁止生成客户端模块
• no_transport(=<boolean>): 禁止使用 tonic::transport::Channel 生成连接方法
• no_include(=<boolean>): 跳过向 protoc-gen-prost 生成的文件中添加包含项。如果在此插件单独运行的 protoc 调用中遇到 Tried to insert into file that doesn't exist 错误，则可能需要这种行为。

关于参数值的注意事项

• <attribute>: 值中出现的所有 , 必须转义（即 \,）。这是由于在内部，protoc 在将参数作为单个字符串发送到底层插件之前，使用 , 将所有传递的参数连接起来。
• <proto_path>：以 . 开头的 Protobuf 路径将从全局根目录进行匹配（前缀匹配）。所有其他路径都将进行后缀匹配。
• (=<boolean>)：可以在参数之后指定布尔值，但如果没有指定，则默认为 true，因为已经列出了该参数。

与 protoc 和 protoc-gen-prost 一起使用

为了便于与 prost 生成的基定义一起工作，此插件假设它在与 protoc-gen-prost 相同的 protoc 调用中作为链式模式运行。可以通过在同一个 protoc 调用中指定多个插件来实现，如下所示

protoc -I proto proto/greeter/v1/greeter.proto \
    --prost_out=proto/gen \
    --tonic_out=proto/gen

当作为单独的调用运行时，protoc 将不知道由 protoc-gen-prost 生成的基定义。在这种情况下，需要使用 no_include 指令，并且需要单独包含生成的 .tonic.rs 文件。

protoc -I proto proto/greeter/v1/greeter.proto \
    --prost_out=proto/gen

protoc -I proto proto/greeter/v1/greeter.proto \
    --tonic_out=proto/gen \
    --tonic_opt=no_include

与 buf 一起使用

当与 buf 一起使用时，可以在 buf.gen.yaml 文件中指定选项。protoc-gen-prost-tonic 应该出现在 protoc-gen-prost 步骤之后的插件步骤中。

version: v1
plugins:
  - plugin: prost
    out: gen
  - plugin: tonic
    out: gen

如果您在任何早期步骤中指定了 compile_well_known_types 或 extern_path，则也应在此步骤中指定这些内容。

protoc-gen-tonic 插件还发布在 Buf Schema 注册表上，您可以通过远程执行而无需显式安装此工具。请参阅 插件列表 以确定可用的最新版本。插件引用如下

version: v1
plugins:
  - plugin: buf.build/community/neoeinstein-tonic:v0.3.0
    out: gen

结合所有这些，可以使用以下示例编译一个用于 gRPC 服务的、可使用 JSON 序列化的类型的现成 crate。然后您可以从将托管服务器的二进制文件或使用客户端依赖此 crate。

version: v1
plugins:
  - plugin: prost
    out: gen/src
    opt:
      - compile_well_known_types
      - extern_path=.google.protobuf=::pbjson_types
  - plugin: prost-serde
    out: gen/src
  - plugin: tonic
    out: gen/src
    opt:
      - compile_well_known_types
      - extern_path=.google.protobuf=::pbjson_types
  - plugin: prost
    out: gen
    opt:
      - gen_crate=Cargo.toml.tpl