protobuf-well-known-types：Rust Protobuf 发行版中 Well-Known Types 的实现与构建机制

protobuf-well-known-typesRust Protobuf 发行版中 Well-Known Types 的实现与构建机制【免费下载链接】protobufProtocol Buffers - Googles data interchange format项目地址: https://gitcode.com/GitHub_Trending/pr/protobuf本篇基于 protobuf 仓库中 Rust 发布 crate 包 protobuf_well_known_types 的官方说明与配套源码展开说明该 crate 如何打包 Protocol Buffers 的 Well-Known TypesWKT、这些预生成类型在build.rs代码生成流程中如何被声明为依赖以及 Bazel 侧如何利用protoc完成代码生成与打包。读完本文你可以掌握在 Rust 项目中引用 WKT crate 的正确方式并能理解从.proto源文件到.u.pb.rs生成代码的完整链路。1. Crate 定位仓库中“预打包”的 Well-Known Typescrate 的 README 只有一句话但信息密度很高该 crate 包含 protobuf 的全部 Well-Known Types。所谓 Well-Known Types是 Protocol Buffers 官方定义的一组跨语言通用消息类型google.protobuf.Any、google.protobuf.Timestamp等它们随语言运行时/生成代码一起提供使用者不需要自己维护这些.proto文件。在 rust/release_crates 目录的说明中可以看到该目录下“每个子目录对应一个发布到 crates.io 的 crate”每个目录内含一个pkg_tar()仓库内实现为pkg_filegroup用于把 crate 打包成可推送的 tar 包。protobuf_well_known_types就是其中一个它的特殊性在于crate 本身不含手写业务代码主体是“预生成的 WKT 代码 原始 proto 源文件”两部分。2. 覆盖的 10 个 Well-Known Typescrate 生成逻辑中明确列出了所包含的全部 WKT见 src/lib.rsProto 文件包路径前缀典型用途any.protogoogle/protobuf/any.proto任意消息的序列化容器api.protogoogle/protobuf/api.protoAPI 描述元数据duration.protogoogle/protobuf/duration.proto时间跨度empty.protogoogle/protobuf/empty.proto空消息占位field_mask.protogoogle/protobuf/field_mask.proto部分更新字段掩码source_context.protogoogle/protobuf/source_context.proto源文件位置信息struct.protogoogle/protobuf/struct.proto动态 JSON 风格结构timestamp.protogoogle/protobuf/timestamp.proto时间点type.protogoogle/protobuf/type.proto类型系统描述wrappers.protogoogle/protobuf/wrappers.proto标量包装类型这一清单与仓库 C 侧的权威文件组 well_known_type_protos 完全一致——后者是//src/google/protobuf包中定义的filegroup同样由any.proto、api.proto、…、wrappers.proto共 10 个文件组成。也就是说Rust crate 直接复用了与 C 实现相同的 proto 源文件集合保证多语言 WKT 定义的单一事实来源。3. crate 源码结构get_dependency是关键入口crate 的入口文件 src/lib.rs 结构极简mod generated; pub use generated::*; pub fn get_dependency(crate_name: str) - Vecprotobuf_codegen::Dependency { vec![protobuf_codegen::Dependency { crate_name: crate_name.to_string(), proto_import_paths: vec![Path::new(env!(CARGO_MANIFEST_DIR)).join(proto)], proto_files: vec![ google/protobuf/any.proto.to_string(), google/protobuf/api.proto.to_string(), // ... 共 10 个 WKT ], }] }它由两部分构成mod generated;pub use generated::*;generated模块是构建期由protoc生成的代码见第 5 节generated.rs会把 10 个.u.pb.rs文件重新导出因此下游 crateuse protobuf_well_known_types::*即可直接拿到Timestamp、Any、Struct等 Rust 类型。get_dependency()这是供下游 crate 的build.rs使用的函数。它返回一个protobuf_codegen::Dependency描述结构告诉代码生成器两件事proto_import_pathsWKT 的.proto源文件位于本 crate 安装目录下的proto/子目录运行时通过CARGO_MANIFEST_DIR解析proto_files生成下游代码时需要参与编译的 10 个 WKT proto 清单。crate_name参数则用于生成extern crate声明的命名通常传入protobuf_well_known_types。4. 在 Rust 项目中使用build.rs声明依赖最直观的实战示例来自同目录下的 protobuf_example/build.rsuse protobuf_codegen::CodeGen; fn main() { CodeGen::new() .inputs([proto_example/foo.proto, proto_example/bar/bar.proto]) .include(proto) .dependency(protobuf_well_known_types::get_dependency(protobuf_well_known_types)) .generate_and_compile() .unwrap(); }流程解读.inputs(...)指定本 crate 自己的 proto 文件示例中的 foo.proto 与 bar.proto.dependency(protobuf_well_known_types::get_dependency(protobuf_well_known_types))把 WKT 作为依赖 proto 包注入当foo.proto中出现import google/protobuf/timestamp.proto;时代码生成器能从 WKT crate 的proto/目录找到源文件并生成对protobuf_well_known_types中已编译类型的引用而不是重复生成一遍 WKT 代码。这正是 WKT crate 存在的核心价值——避免每个下游 crate 重复编译 well-known types。从 Cargo-template.toml 可以看到该 crate 的依赖面极小仅依赖同族的protobuf与protobuf-codegen两个 crate[package] name protobuf-well-known-types version {PROTOBUF_RUST_VERSION} edition 2021 description Protobuf Well-Known Types license BSD-3-Clause [dependencies] protobuf { version {PROTOBUF_LEGACY_VERSION}, path ../protobuf, package protobuf } protobuf-codegen { version {PROTOBUF_LEGACY_VERSION}, path ../protobuf_codegen, package protobuf-codegen }注意version字段是模板占位符{PROTOBUF_RUST_VERSION}发布前由 substitute_rust_release_version.bzl 对应的 Bazel 规则substitute_rust_release_version把Cargo-template.toml渲染成带真实版本号的Cargo.toml见 BUILD.bazel 中的调用。因此源码树中只维护模板版本号由发布流程统一注入。5. 生成代码的构建链路protoc upb 代码生成crate 内的generated模块并非手写而是 Bazel 构建时现产。BUILD.bazel 中的genrule定义了完整命令genrule( name gen_well_known_types, srcs [//src/google/protobuf:well_known_type_protos], outs [ google/protobuf/any.u.pb.rs, google/protobuf/api.u.pb.rs, # ... duration / empty / field_mask / source_context / # struct / timestamp / type / wrappers 共 10 个 google/protobuf/generated.rs, ], cmd echo $(SRCS) | sed s?src/??g | xargs $(location //:protoc) -I src --rust_out$(D) --rust_optexperimental-codegenenabled,kernelupb, tools [//:protoc], )关键细节输入直接依赖//src/google/protobuf:well_known_type_protos文件组即第 2 节列出的 10 个 protosed s?src/??g把绝对源路径裁剪后传给protoc-I srcproto 的 import 根是仓库的src/目录因此文件内路径统一写作google/protobuf/*.proto与get_dependency()中proto_files的字符串一一对应--rust_optexperimental-codegenenabled,kernelupb启用实验性代码生成器且以内核为 upb即生成的.u.pb.rs文件名中的u正对应 upb 内核输出每个 WKT 一个.u.pb.rs外加聚合入口generated.rs共 11 个产物被pkg_files以src为前缀打进 crateBUILD.bazel与src/lib.rs中mod generated;精确衔接。同时原始 proto 文件通过pkg_files以proto/google/protobuf前缀打包BUILD.bazel这正对应get_dependency()里CARGO_MANIFEST_DIR/proto的 import 路径——打包布局与运行时声明是同一份契约。6. 打包与发布pkg_filegroup组装 crate最终发布产物由 BUILD.bazel 顶部的pkg_filegroup组装pkg_filegroup( name protobuf_well_known_types_crate, srcs [ :crate_root_files, # Cargo.toml src/lib.rs 等根文件 :well_known_types, # proto/google/protobuf/*.proto :well_known_types_gencode,# src/google/protobuf/*.u.pb.rs generated.rs //rust/release_crates:license, ], prefix protobuf_well_known_types, visibility [//rust:__subpackages__], )四个组成块拼出一个可直接cargo package/ 推送 crates.io 的目录根文件crate_root_files用strip_prefix.from_root剥掉rust/release_crates/protobuf_well_known_types前缀、proto 源文件、生成代码、许可证。整个发布链路可以概括为src/google/protobuf/*.proto │ well_known_type_protos 文件组 ▼ protoc --rust_optexperimental-codegenenabled,kernelupb ▼ 10 个 .u.pb.rs generated.rs ──┐ proto/google/protobuf/* ───┼──▶ pkg_filegroup ──▶ crates.io Cargo.toml模板渲染 lib.rs ┘7. 使用前提与限制该 crate 属于 protobuf 官方 Rust 发行族protobuf、protobuf-codegen、protobuf-well-known-types等由 rust/release_crates/Cargo.toml 统一管理的 workspace版本号由发布流程替换源码树中的{PROTOBUF_RUST_VERSION}/{PROTOBUF_LEGACY_VERSION}是占位符直接读源码树不应按字面值理解依赖版本生成代码使用experimental-codegenenabled选项从命令名可以推断当前 WKT 代码走的是实验性生成器 upb 内核路径下游 crate 若要复用同样的类型布局build.rs中通过get_dependency()声明依赖即可无需自行重新生成 WKTcrate 只覆盖上表 10 个 WKTdescriptor.proto等元描述文件不在其中后者属于 descriptor_proto_srcs 文件组如果你的 proto 依赖的是descriptor.proto不能指望本 crate 提供。小结protobuf-well-known-types是 protobuf Rust 发行版中专门承载 10 个 well-known types 的 crate——它把src/google/protobuf下的 WKT proto 源文件、由protocupb 内核实验性代码生成产出的预编译 Rust 代码、以及get_dependency()声明接口三者打包为一个单元使任意使用protobuf-codegen的下游 crate 都能以一行build.rs代码复用官方 WKT而不用各自维护重复的 proto 与生成逻辑。【免费下载链接】protobufProtocol Buffers - Googles data interchange format项目地址: https://gitcode.com/GitHub_Trending/pr/protobuf创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考