Rust Prost-Build 使用指南

Mttao 收录于类别 Rust Protobuf

2024-07-07 2024-07-07 约 1927 字预计阅读 4 分钟

prost是Rust语言中流行的Protobuf实现和代码生成工具。prost_build是prost的构建时代码生成库，它能从 .proto文件生成Rust数据结构和trait实现。本文将详细介绍prost-build的使用方法。

基本用法

prost-build是一个构建依赖项包，用于在Rust项目的构建脚本(build.rs)中编译.proto文件。最基本的用法是使用prost_build::compile_protos函数:

rust

fn main() -> Result<(), Box<dyn std::error::Error>> {
    prost_build::compile_protos(
        &["path/to/foo.proto", "path/to/bar.proto"], 
        &["path/to/include"]
    )?;
    Ok(())
}

这将编译指定的.proto文件并生成相应的Rust代码。第一个参数是一个.proto文件路径的列表，第二个参数是一个包含.proto文件的目录列表，用于解析导入的.proto文件。

生成的Rust代码将写入Cargo指定的OUT_DIR目录中。您可以使用include!宏在您的Rust代码中包含生成的模块。

配置选项

prost-build提供了许多配置选项来定制生成的代码。这些选项是通过prost_build::Config结构体设置的。

btree_map

btree_map方法指示prost-build为指定的字段生成BTreeMap类型，而不是默认的HashMap。这在无std环境中很有用。

rust

let mut config = prost_build::Config::new();
config.btree_map(&["."]);  // 对所有map字段使用BTreeMap
config.btree_map(&[".my_package.MyMessage.my_field"]); // 只对指定字段使用

bytes

bytes方法指示prost-build为指定的字节字段生成bytes::Bytes类型，而不是默认的Vec<u8>。

rust

config.bytes(&["."]);  // 对所有bytes字段使用Bytes

属性

prost-build允许您添加自定义属性到生成的类型和字段。这对于实现特性派生或与其他crate集成(如serde)很有用。

field_attribute为指定的字段添加属性。
type_attribute为指定的消息、枚举和oneof添加属性。
message_attribute为指定的消息添加属性。
enum_attribute为指定的枚举和oneof添加属性。

rust

config.field_attribute(".my_package.MyMessage.id", "#[serde(rename = \"id\")]");
config.type_attribute(".my_package.MyMessage", "#[derive(Serialize, Deserialize)]");

boxed

boxed方法指示prost-build为指定的字段生成Box<T>类型。

rust

config.boxed(".my_package.MyMessage.large_field");

服务生成器

可以使用service_generator方法自定义prost-build生成gRPC服务器和客户端代码的方式。

rust

config.service_generator(Box::new(MyServiceGenerator));

其他选项

prost-build还提供了其他一些选项:

compile_well_known_types: 从.proto文件生成Protobuf的常用类型,而不是使用prost_types crate。
disable_comments: 禁止生成文档注释。
skip_debug: 跳过为指定类型实现Debugtrait。
extern_path: 声明外部提供的Protobuf包或类型,用于引用其他crate中的prost类型。
file_descriptor_set_path: 将FileDescriptorSet写入指定路径,可用于实现反射等功能。
skip_protoc_run: 与file_descriptor_set_path结合使用,从提供的FileDescriptorSet生成代码,而不是调用protoc。
retain_enum_prefix: 防止prost从枚举变量名称中去除枚举名称前缀。
out_dir: 指定生成的Rust文件的输出目录。
default_package_filename: 设置没有包定义的Protobuf的文件名。
enable_type_names: 为消息类型实现Name trait,以支持编码为Any类型。
type_name_domain: 为消息类型URL指定域名前缀。
prost_path: 设置派生Message trait的路径。
protoc_arg: 添加protoc的命令行参数。
include_file: 生成包含所有生成文件的模块文件,以简化包含。
format: 控制是否通过prettyplease格式化生成的代码。

示例

下面是一个完整的build.rs示例,展示了prost-build的多个配置选项:

rust

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut config = prost_build::Config::new();

    // 为所有map字段生成BTreeMap
    config.btree_map(&["."]);
    
    // 为bytes字段生成bytes::Bytes
    config.bytes(&[".my_package.MyMessage.data"]);
    
    // 添加派生Serialize/Deserialize
    config.type_attribute(".my_package.MyMessage", "#[derive(Serialize, Deserialize)]");
    
    // 自定义序列化字段名
    config.field_attribute(".my_package.MyMessage.my_field", "#[serde(rename = \"myField\")]");
    
    // 为大字段生成Box
    config.boxed(".my_package.MyMessage.large_data");
    
    // 禁止生成调试实现
    config.skip_debug(&["."]);

    config.compile_protos(&["proto/my_package.proto"], &["proto"])?;

    Ok(())
}

在这个例子中,我们:

为所有map字段生成BTreeMap
为MyMessage的data字段生成bytes::Bytes
为MyMessage派生Serialize和Deserializetrait
自定义my_field字段的序列化字段名为myField
为large_data字段生成Box类型
禁止为所有类型生成Debug实现
编译proto/my_package.proto,包含目录为proto

通过配置这些选项,我们可以完全定制的Protobuf代码生成结果。

总结

prost-build为Protobuf与Rust的集成提供了强大而灵活的功能。通过深入了解其配置选项,我们可以根据项目需求生成定制的Rust代码。无论是简单的消息类型还是复杂的gRPC服务,prost-build都可以满足您的需求。