protoc-gen-prost-serde

A protoc 插件，生成遵循 protobuf-JSON 约定的 serde 序列化实现。

当在仅使用 Rust 代码的项目中使用时，使用 Prost! 生成 protobuf 定义的首选机制是在 build.rs 文件中使用 prost-build，然后使用 pbjson-build 生成 serde 实现。然而，在多语言环境中工作，利用 Protocol Buffers 生态系统中的通用工具可能会有优势。用于此目的的一个常见工具是 buf，它简化了代码生成过程，并包含一些有用的功能，包括 linting、包管理和破坏性变更检测。

用法

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

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

选项

此工具支持来自 pbjson-build 的所有相同选项。有关这些设置的详细影响信息，请参阅该crate的相关文档

• btree_map=<proto_path>: btree_map
• default_package_filename=<value>: default_package_filename
• extern_path=<proto_path>=<rust_path>: extern_path
• retain_enum_prefix(=<boolean>): retain_enum_prefix
• preserve_proto_field_names=(<boolean>): preserve_proto_field_names
• ignore_unknown_fields=(<boolean>): ignore_unknown_fields
• emit_fields=(<boolean>): emit_fields
• use_integers_for_enums=(<boolean>): use_integers_for_enums

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

• no_include(=<boolean>): 跳过将 include 添加到由 protoc-gen-prost 生成的文件中。如果在单独的 protoc 调用中运行此插件并遇到 Tried to insert into file that doesn't exist 错误，则可能需要这种行为。

有关参数值的一些说明

• <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 \
    --prost_opt=compile_well_known_types \
    --prost_opt=extern_path=.google.protobuf=::pbjson_types \
    --prost-serde_out=proto/gen

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

protoc -I proto proto/greeter/v1/greeter.proto \
    --prost_out=proto/gen \
    --prost_opt=compile_well_known_types \
    --prost_opt=extern_path=.google.protobuf=::pbjson_types

protoc -I proto proto/greeter/v1/greeter.proto \
    --prost-serde_out=proto/gen \
    --prost-serde_opt=no_include

与 buf 一起使用

当与 buf 一起使用时，可以在 buf.gen.yaml 文件中指定选项。 protoc-gen-prost-serde 应作为插件步骤出现在任何 protoc-gen-prost 步骤之后。此外，应指定 compile_well_known_types 和 extern_path=.google.protobuf=::pbjson_types 选项。

version: v1
plugins:
  - plugin: prost
    out: gen
    opt:
      - compile_well_known_types
      - extern_path=.google.protobuf=::pbjson_types
  - plugin: prost-serde
    out: gen

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

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

protoc-gen-prost-serde 也与 protoc-gen-prost-crate 插件兼容

version: v1
plugins:
  - plugin: prost
    out: gen
    opt:
      - compile_well_known_types
      - extern_path=.google.protobuf=::pbjson_types
  - plugin: prost-serde
    out: gen
  - plugin: prost-crate
    strategy: all
    out: gen
    opt:
      - no_features