protoc-gen-prost-crate

一个 protoc 插件，用于生成 Cargo crates 和包含文件。

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

使用方法

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

protoc --prost-crate_out=proto/gen -I proto proto/greeter/v1/greeter.proto

选项

可以指定以下选项

• default_package_filename=<value>：这应该与主 protoc-gen-prost 步骤的值匹配，以便包含文件引用正确的输出文件。（也请参阅 prost-build 中的 默认包文件名）
• include_file(=<value>)：设置生成的包含文件的名称。如果没有指定，则默认值取决于是否指定了gen_crate。如果是，则<value>默认为src/lib.rs。否则，默认为mod.rs。生成的包含文件将为每个生成的模块添加功能标记，以便实现更快的编译和减少不必要的功能的大小。可以通过指定no_features来禁用此功能。
• only_include=<proto_path>：如果启用，则仅将具有指定前缀的包包含在生成的包含文件和生成的功能列表中，路径必须是完全限定的，并以.开头。
• gen_crate(=<template_path>)：指示应该根据提供的路径上的模板生成一个基于清单的Cargo crate。模板应包含一个占位符以注入crate功能图，除非指定了no_features。模板生成不考虑crate依赖项。这些必须单独管理。如果没有指定，则假定Cargo.toml。这允许自动更新Cargo清单中的功能。
• no_features(=<boolean>)：禁用在包含文件或Cargo清单中生成功能标志。
• package_separator=[-_.+]：更改用于在用作功能标志时分隔包名称各个部分的字符。如果未指定，则默认为-。注意：.会导致无法在crates.io上发布的特征名称。

关于参数值的一些说明

• (=<boolean>)：可以在参数之后指定布尔值，但如果未指定，则假定值为true，因为已经列出了该参数。

与buf一起使用

当与buf一起使用时，选项可以指定在buf.gen.yaml文件中。此插件必须使用strategy: all运行，才能全面了解protobuf模式并正确识别输入文件的依赖项。

以下操作将仅生成输出目录gen中的包含文件mod.rs，不包含任何条件编译功能标志。

version: v1
plugins:
  - plugin: prost-crate
    out: gen
    strategy: all
    opt:
      - no_features

当使用gen_crate选项时，后来的Rust生成器应该生成到由该插件创建的src目录中。

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

当处理私有、供应商包依赖项时，buf往往会输出比所需更多的文件。要限制放入包含文件中的包，请使用only_include选项。

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

protoc-gen-prost-crate 插件也发布在 Buf Schema Registry 上，作为一个可以远程执行的插件，无需显式安装此工具。请参阅插件列表以识别最新的发布版本。请注意，远程插件形式与 gen_crate 选项不兼容，因为插件是在当前文件系统之外执行，所以无法使用模板信息。插件引用如下

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

Cargo 清单模板

当使用 gen_crate 选项时，指定的模板将放置在输出文件夹中。模板应包括一个注释插入点，可以用来放置功能依赖图。默认情况下，模板将是 Cargo.toml，并将对 Cargo.toml 文件进行原地更新，更新公开的功能以匹配生成的代码。

protoc 将在插入点上方插入计算出的依赖图。如果此注释行未包含，则 protoc 将不知道将功能列表放置在哪里，插入将静默跳过。

[package]
name = "my-cool-proto-defs"
version = "0.1.0"
edition = "2021"

[dependencies]
prost = "0.10.0"

[features]
default = []
## @@protoc_insertion_point(features)

一旦生成，清单将包括一组功能，这些功能允许将编译限制为仅包含所需模块。每个功能将自动激活所需的相关功能。

[package]
name = "my-cool-proto-defs"
version = "0.1.0"
edition = "2021"

[dependencies]
prost = "0.10.0"

[features]
default = []
## @@protoc_deletion_point(features)
## This section is automatically generated by protoc-gen-prost-crate. 
## Changes in this area may be lost on regeneration.
proto_full = ["helloworld-v1", "greeter-v1"]
"greeter-v1" = ["helloworld-v1"]
"helloworld-v1" = []
## @@protoc_insertion_point(features)

生成后的自定义

通常，我建议不要手动编辑生成的代码文件。这样做会使您难以发展您的模式，因为重新生成代码将需要手动再次编辑以重新添加自定义。相反，我建议使用子目录来托管生成的代码，并在 src/lib.rs 中包含该文件，如 build-with-buf 示例所示。

src/lib.rs:

include!("gen/mod.rs");

// Any additional traits or other impls can go here or in other related files.
// These won't be touched by the code generation process.

Cargo.toml（第一次生成之前）

[package]
name = "my-cool-proto-defs"
version = "0.1.0"
edition = "2021"

[features]
default = ["proto_full"]
## @@protoc_insertion_point(features)

[dependencies]
prost = "0.10.0"

buf.gen.yaml:

version: v1
plugins:
  - plugin: prost
    out: src
    opt:
      - bytes=.
      - file_descriptor_set
  - plugin: prost-crate
    out: gen
    strategy: all
    opt:
      - include_file=src/gen/mod.rs
      - gen_crate