Dart 生成的代码

描述了 Protocol Buffers 编译器为任何给定的协议定义生成的 Dart 代码。

突出显示了 proto2 和 proto3 生成代码之间的任何差异 - 注意，这些差异是在本文档描述的生成代码中，而不是在两个版本中都相同的基本 API 中。在阅读本文档之前，你应该阅读proto2 语言指南和/或proto3 语言指南。

编译器调用

Protocol Buffers 编译器需要一个用于生成 Dart 代码的插件。按照说明进行安装，会提供一个 protoc-gen-dart 可执行文件，protoc 在使用 --dart_out 命令行标志调用时会使用该文件。--dart_out 标志告诉编译器将 Dart 源文件写入何处。对于 .proto 文件输入，编译器会生成一个 .pb.dart 文件等。

.pb.dart 文件的名称通过获取 .proto 文件的名称并进行两处更改来计算得出

扩展名 (.proto) 被替换为 .pb.dart。例如，名为 foo.proto 的文件将生成一个名为 foo.pb.dart 的输出文件。
proto 路径 (使用 --proto_path 或 -I 命令行标志指定) 被替换为输出路径 (使用 --dart_out 标志指定)。

例如，当你如下调用编译器时

protoc --proto_path=src --dart_out=build/gen src/foo.proto src/bar/baz.proto

编译器将读取文件 src/foo.proto 和 src/bar/baz.proto。它会生成：build/gen/foo.pb.dart 和 build/gen/bar/baz.pb.dart。编译器在必要时会自动创建目录 build/gen/bar，但它不会创建 build 或 build/gen；这些目录必须已经存在。

消息

假设有一个简单的消息声明

message Foo {}

Protocol Buffers 编译器会生成一个名为 Foo 的类，它继承自 GeneratedMessage 类。

GeneratedMessage 类定义了一些方法，允许你检查、操作、读取或写入整个消息。除了这些方法之外，Foo 类还定义了以下方法和构造函数

Foo()：默认构造函数。创建一个实例，其中所有单个字段都未设置，重复字段为空。
Foo.fromBuffer(...)：从表示消息的序列化 Protocol Buffers 数据创建 Foo。
Foo.fromJson(...)：从编码消息的 JSON 字符串创建 Foo。
Foo clone()：创建消息中字段的深度克隆。
Foo copyWith(void Function(Foo) updates)：创建此消息的可写副本，对其应用 updates，并在返回之前将副本标记为只读。
static Foo create()：创建单个 Foo 的工厂函数。
static PbList<Foo> createRepeated()：工厂函数，用于创建实现 Foo 元素的可变重复字段的 List。
static Foo getDefault()：返回 Foo 的单例实例，该实例与新构造的 Foo 实例相同（因此所有单个字段都未设置，所有重复字段都为空）。

嵌套类型

一个消息可以在另一个消息内部声明。例如

message Foo {
  message Bar {
  }
}

在这种情况下，编译器会生成两个类：Foo 和 Foo_Bar。

字段

除了上一节中描述的方法之外，Protocol Buffers 编译器还会为 .proto 文件中消息内定义的每个字段生成访问器方法。

请注意，即使 .proto 文件中的字段名使用下划线和小写字母（应该如此），生成的名称也总是使用驼峰命名法。大小写转换规则如下

名称中的每个下划线都被移除，并且其后面的字母会大写。
如果名称附加了前缀（例如 "has"），则首字母大写。否则，首字母小写。

因此，对于字段 foo_bar_baz，getter 会变成 get fooBarBaz，而以 has 为前缀的方法将是 hasFooBarBaz。

单个基本字段 (proto2)

对于以下任何字段定义

optional int32 foo = 1;
required int32 foo = 1;

编译器将在消息类中生成以下访问器方法

int get foo：返回字段的当前值。如果字段未设置，则返回默认值。
bool hasFoo()：如果字段已设置，则返回 true。
set foo(int value)：设置字段的值。调用此方法后，hasFoo() 将返回 true，并且 get foo 将返回 value。
void clearFoo()：清除字段的值。调用此方法后，hasFoo() 将返回 false，并且 get foo 将返回默认值。

对于其他简单字段类型，会根据标量值类型表选择相应的 Dart 类型。对于消息和枚举类型，值类型会被替换为消息或枚举类。

单个基本字段 (proto3)

对于此字段定义

int32 foo = 1;

编译器将在消息类中生成以下访问器方法

int get foo：返回字段的当前值。如果字段未设置，则返回默认值。
set foo(int value)：设置字段的值。调用此方法后，get foo 将返回 value。
void clearFoo()：清除字段的值。调用此方法后，get foo 将返回默认值。
注意
由于 Dart proto3 实现中的一个特性，即使 proto 定义中没有使用用于请求存在语义的 optional 修饰符，也会生成以下方法。
bool hasFoo()：如果字段已设置，则返回 true。
注意
如果 proto 是在支持隐式存在（例如 Java）的另一种语言中序列化的，则该值实际上不可信。即使 Dart 跟踪存在性，其他语言不跟踪，并且往返一个零值隐式存在字段会使其在 Dart 的视角下“消失”。
void clearFoo()：清除字段的值。调用此方法后，hasFoo() 将返回 false，并且 get foo 将返回默认值。

单个消息字段

假设消息类型为

message Bar {}

对于包含 Bar 字段的消息

// proto2
message Baz {
  optional Bar bar = 1;
  // The generated code is the same result if required instead of optional.
}

// proto3
message Baz {
  Bar bar = 1;
}

编译器将在消息类中生成以下访问器方法

Bar get bar：返回字段的当前值。如果字段未设置，则返回默认值。
set bar(Bar value)：设置字段的值。调用此方法后，hasBar() 将返回 true，并且 get bar 将返回 value。
bool hasBar()：如果字段已设置，则返回 true。
void clearBar()：清除字段的值。调用此方法后，hasBar() 将返回 false，并且 get bar 将返回默认值。
Bar ensureBar()：如果 hasBar() 返回 false，则将 bar 设置为空实例，然后返回 bar 的值。调用此方法后，hasBar() 将返回 true。

重复字段

对于此字段定义

repeated int32 foo = 1;

编译器会生成

List<int> get foo：返回支持该字段的列表。如果字段未设置，则返回一个空列表。对列表的修改会反映在字段中。

Int64 字段

对于此字段定义

// proto2
optional int64 bar = 1;

// proto3
int64 bar = 1;

编译器会生成

Int64 get bar：返回一个包含字段值的 Int64 对象。

请注意，Int64 不包含在 Dart 核心库中。要使用这些对象，你可能需要导入 Dart fixnum 库

import 'package:fixnum/fixnum.dart';

Map 字段

假设有这样一个map 字段定义

map<int32, int32> map_field = 1;

编译器会生成以下 getter

Map<int, int> get mapField：返回支持该字段的 Dart map。如果字段未设置，则返回一个空 map。对 map 的修改会反映在字段中。

Any

假设有这样一个Any 字段

import "google/protobuf/any.proto";

message ErrorStatus {
  string message = 1;
  google.protobuf.Any details = 2;
}

在我们生成的代码中，details 字段的 getter 返回一个 com.google.protobuf.Any 的实例。这提供了以下用于打包和解包 Any 值的特殊方法

    /// Unpacks the message in [value] into [instance].
    ///
    /// Throws a [InvalidProtocolBufferException] if [typeUrl] does not correspond
    /// to the type of [instance].
    ///
    /// A typical usage would be `any.unpackInto(new Message())`.
    ///
    /// Returns [instance].
    T unpackInto<T extends GeneratedMessage>(T instance,
        {ExtensionRegistry extensionRegistry = ExtensionRegistry.EMPTY});

    /// Returns `true` if the encoded message matches the type of [instance].
    ///
    /// Can be used with a default instance:
    /// `any.canUnpackInto(Message.getDefault())`
    bool canUnpackInto(GeneratedMessage instance);

    /// Creates a new [Any] encoding [message].
    ///
    /// The [typeUrl] will be [typeUrlPrefix]/`fullName` where `fullName` is
    /// the fully qualified name of the type of [message].
    static Any pack(GeneratedMessage message,
        {String typeUrlPrefix = 'type.googleapis.com'});

Oneof

假设有这样一个oneof 定义

message Foo {
  oneof test {
    string name = 1;
    SubMessage sub_message = 2;
  }
}

编译器会生成以下 Dart 枚举类型

 enum Foo_Test { name, subMessage, notSet }

此外，它还会生成这些方法

Foo_Test whichTest()：返回表示哪个字段已设置的枚举。如果都没有设置，则返回 Foo_Test.notSet。
void clearTest()：清除当前已设置的 oneof 字段的值（如果有），并将 oneof 情况设置为 Foo_Test.notSet。

为 oneof 定义内的每个字段生成常规的字段访问器方法。例如对于 name

String get name：如果 oneof 情况是 Foo_Test.name，则返回字段的当前值。否则，返回默认值。
set name(String value)：设置字段的值，并将 oneof 情况设置为 Foo_Test.name。调用此方法后，get name 将返回 value，并且 whichTest() 将返回 Foo_Test.name。
void clearName()：如果 oneof 情况不是 Foo_Test.name，则不会发生任何改变。否则，清除字段的值。调用此方法后，get name 将返回默认值，并且 whichTest() 将返回 Foo_Test.notSet。

枚举

假设有这样一个枚举定义

enum Color {
  COLOR_UNSPECIFIED = 0;
  COLOR_RED = 1;
  COLOR_GREEN = 2;
  COLOR_BLUE = 3;
}

Protocol Buffers 编译器会生成一个名为 Color 的类，它继承自 ProtobufEnum 类。该类将为四个值中的每一个都包含一个 static const Color，以及一个包含这些值的 static const List<Color>。

static const List<Color> values = <Color> [
  COLOR_UNSPECIFIED,
  COLOR_RED,
  COLOR_GREEN,
  COLOR_BLUE,
];

它还会包含以下方法

static Color? valueOf(int value)：返回与给定数值对应的 Color。

每个值都将具有以下属性

name：枚举的名称，如 .proto 文件中指定。
value：枚举的整数值，如 .proto 文件中指定。

请注意，.proto 语言允许多个枚举符号具有相同的数值。具有相同数值的符号是同义词。例如

enum Foo {
  BAR = 0;
  BAZ = 0;
}

在这种情况下，BAZ 是 BAR 的同义词，并将如下定义

static const Foo BAZ = BAR;

枚举可以在消息类型内嵌套定义。例如，假设有这样一个枚举定义

message Bar {
  enum Color {
    COLOR_UNSPECIFIED = 0;
    COLOR_RED = 1;
    COLOR_GREEN = 2;
    COLOR_BLUE = 3;
  }
}

Protocol Buffers 编译器会生成一个名为 Bar 的类，它继承自 GeneratedMessage，以及一个名为 Bar_Color 的类，它继承自 ProtobufEnum。

扩展 (仅限 proto2)

假设文件 foo_test.proto 包含一个带有扩展范围的消息和一个顶级扩展定义

message Foo {
  extensions 100 to 199;
}

extend Foo {
  optional int32 bar = 101;
}

除了 Foo 类之外，Protocol Buffers 编译器还会生成一个 Foo_test 类，其中包含文件中每个扩展字段的 static Extension，以及用于在 ExtensionRegistry 中注册所有扩展的方法

static final Extension bar
static void registerAllExtensions(ExtensionRegistry registry)：在给定的注册表中注册所有定义的扩展。

Foo 的扩展访问器可以如下使用

Foo foo = Foo();
foo.setExtension(Foo_test.bar, 1);
assert(foo.hasExtension(Foo_test.bar));
assert(foo.getExtension(Foo_test.bar)) == 1);

扩展也可以在另一个消息内部嵌套声明

message Baz {
  extend Foo {
    optional int32 bar = 124;
  }
}

在这种情况下，扩展 bar 则被声明为 Baz 类的一个静态成员。

当解析可能包含扩展的消息时，必须提供一个 ExtensionRegistry，并在其中注册你想要能够解析的任何扩展。否则，这些扩展将被视为未知字段。例如

ExtensionRegistry registry = ExtensionRegistry();
registry.add(Baz.bar);
Foo foo = Foo.fromBuffer(input, registry);

如果你已经有一个带有未知字段的已解析消息，可以在 ExtensionRegistry 上使用 reparseMessage 来重新解析消息。如果未知字段集包含注册表中存在的扩展，则这些扩展会被解析并从未知字段集中移除。消息中已存在的扩展会被保留。

Foo foo = Foo.fromBuffer(input);
ExtensionRegistry registry = ExtensionRegistry();
registry.add(Baz.bar);
Foo reparsed = registry.reparseMessage(foo);

请注意，这种检索扩展的方法总体上开销更大。如果可能，我们建议在使用 GeneratedMessage.fromBuffer 时使用包含所有必需扩展的 ExtensionRegistry。

服务

假设有一个服务定义

service Foo {
  rpc Bar(FooRequest) returns(FooResponse);
}

Protocol Buffers 编译器可以使用 `grpc` 选项调用（例如 --dart_out=grpc:output_folder），在这种情况下，它会生成支持gRPC 的代码。有关更多详细信息，请参阅gRPC Dart 快速入门指南。