protoc-gen-prost

一个使用 Prost！ 代码生成引擎生成代码的 protoc 插件。

当在仅使用 Rust 代码的项目中使用时，使用 Prost！ 生成 protobuf 定义的首选机制是在 build.rs 文件中使用 prost-build。然而，当在多语言环境中工作时，利用 Protocol Buffers 生态系统中的常用工具可能是有益的。用于此目的的常见工具之一是 buf，它简化了代码生成过程，并包括几个有用的功能，包括代码检查、包管理和破坏性更改检测。

用法

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

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

选项

此工具支持与 prost-build 相同的所有选项。有关这些设置的详细效果信息，请参阅该crate的相关文档

• btree_map=<proto_path>: btree_map
• bytes=<proto_path>: bytes
• default_package_filename=<value>: default_package_filename
• disable_comments=<proto_path>: disable_comments
• extern_path=<proto_path>=<rust_path>: extern_path
• compile_well_known_types(=<boolean>): compile_well_known_types
• retain_enum_prefix(=<boolean>): retain_enum_prefix
• field_attribute=<proto_path>=<attribute>: field_attribute
• type_attribute=<proto_path>=<attribute>: type_attribute
• enable_type_names(=<boolean>): enable_type_names

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

• file_descriptor_set(=<boolean>): 在每个模块的生成输出中包含编码的 FileDescriptorSet。请注意，这与 prost-build 的行为不同，因为每个模块只包含该模块的文件描述符。这允许在传递给 protobuf 反射 API 时更好地限定信息，并且减少了无用或多余信息的暴露。此外，此模块在未先使用 Prost! 解码的情况下嵌入原始文件描述符，确保了扩展和意外标签被保留。

关于参数值的说明

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

与buf一起使用

当与buf一起使用时，可以在buf.gen.yaml文件中指定选项

version: v1
plugins:
  - plugin: prost
    out: gen
    opt:
      - bytes=.
      - compile_well_known_types
      - extern_path=.google.protobuf=::pbjson_types
      - file_descriptor_set
      - type_attribute=.helloworld.v1.HelloWorld=#[derive(Eq\, Hash)]

protoc-gen-prost插件也作为插件发布在Buf Schema Registry上，您可以通过远程执行来使用它，而无需显式安装此工具。请参阅插件列表以识别最新发布的版本以供使用。插件如下引用

version: v1
plugins:
  - plugin: buf.build/community/neoeinstein-prost:v0.2.3
    out: gen

如果需要包含文件或生成的crate，则应该将其作为独立步骤运行，如下例所示。有关更多信息，请参阅protoc-gen-prost-crate插件。

version: v1
plugins:
  - plugin: prost
    out: gen/src
    opt:
      - bytes=.
      - file_descriptor_set
  - plugin: prost-crate
    out: gen
    strategy: all
    opt:
      - gen_crate=Cargo.toml.tpl

扩展

在构建输出时，protoc-gen-prost在模块内部添加插入点，以便轻松添加更多特质实现。这些插入点位于每个模块中，如果生成了包含文件，则也位于其中。输出模块文件根据未转换的protobuf包名称命名。因此，名为helloworld.abstract.v1的包将具有输出文件名为helloworld.abstract.v1.rs。

在模块文件（<proto_package>.rs）中

• module：在模块文件末尾添加

在包含文件中

• <proto_package>：将内容追加到为此包定义的模块

以下是一个使用protoc-gen-prost-serde插件的buf示例

version: v1
plugins:
  - plugin: prost
    out: gen/src
    opt:
      - bytes=.
      - file_descriptor_set
  - plugin: prost-serde
    out: gen/src
  - plugin: prost-crate
    out: gen
    strategy: all
    opt:
      - gen_crate=Cargo.toml.tpl