Dart 生成的代码

描述 protocol buffer 编译器为任何给定的协议定义所生成的 Dart 代码。

本文档会重点说明 proto2、proto3 和 editions 版本生成的代码之间的任何差异——请注意，这些差异存在于本文档描述的生成代码中，而不是基础 API 中，基础 API 在两个版本中是相同的。在阅读本文档之前，您应该先阅读 proto2 语言指南、proto3 语言指南或 editions 语言指南。

编译器调用

protocol buffer 编译器需要一个插件来生成 Dart 代码。按照说明进行安装，会提供一个 protoc-gen-dart 二进制文件，当使用 --dart_out 命令行标志调用 protoc 时会用到它。--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 buffer 编译器会生成一个名为 Foo 的类，它扩展了 GeneratedMessage 类。

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

Foo(): 默认构造函数。创建一个实例，其中所有单一字段都未设置，所有重复字段为空。
Foo.fromBuffer(...): 从表示消息的序列化 protocol buffer 数据创建一个 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 buffer 编译器还为 .proto 文件中消息内定义的每个字段生成了访问器方法。

请注意，生成的名称始终使用驼峰命名法 (camel-case)，即使 .proto 文件中的字段名使用带下划线的小写字母（这是推荐的风格）。大小写转换的工作方式如下：

对于名称中的每个下划线，下划线被移除，其后的字母大写。
如果名称将附加前缀（例如 "has"），则首字母大写。否则，首字母小写。

因此，对于字段 foo_bar_baz，getter 将是 get fooBarBaz，而带有 has 前缀的方法将是 hasFooBarBaz。

单一原始类型字段

在 Dart 实现中，所有字段都具有显式存在性。

对于以下字段定义：

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 实现的一个特性，即使配置了隐式存在性，以下方法仍会生成。
bool hasFoo(): 如果字段已设置，则返回 true。
注意
如果 proto 是在另一种支持隐式存在性的语言（例如 Java）中序列化的，那么这个值实际上是不可信的。尽管 Dart 会跟踪存在性，但其他语言不会，往返传输一个值为零的隐式存在性字段将导致它从 Dart 的角度看“消失”。
void clearFoo(): 清除字段的值。调用此方法后，hasFoo() 将返回 false，get foo 将返回默认值。

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

奇异消息字段

给定消息类型：

message Bar {}

对于带有 Bar 字段的消息：

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

// proto3 and editions
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 字段

对于此字段定义：

int64 bar = 1;

编译器将生成：

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

请注意，Int64 并不内置于 Dart 核心库中。要使用这些对象，您可能需要导入 Dart fixnum 库：

import 'package:fixnum/fixnum.dart';

映射字段

给定一个像这样的 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 case 设置为 Foo_Test.notSet。

对于 oneof 定义中的每个字段，都会生成常规的字段访问器方法。例如，对于 name：

String get name: 如果 oneof case 是 Foo_Test.name，则返回该字段的当前值。否则，返回默认值。
set name(String value): 设置字段的值，并将 oneof case 设置为 Foo_Test.name。调用此方法后，get name 将返回 value，whichTest() 将返回 Foo_Test.name。
void clearName(): 如果 oneof case 不是 Foo_Test.name，则不进行任何更改。否则，清除字段的值。调用此方法后，get name 将返回默认值，whichTest() 将返回 Foo_Test.notSet。

枚举

给定一个枚举定义，例如：

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

protocol buffer 编译器将生成一个名为 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 buffer 编译器将生成一个名为 Bar 的类，它扩展了 GeneratedMessage，以及一个名为 Bar_Color 的类，它扩展了 ProtobufEnum。

扩展（proto3 中不可用）

给定一个文件 foo_test.proto，其中包含一个带有扩展范围的消息和一个顶级扩展定义：

message Foo {
  extensions 100 to 199;
}

extend Foo {
  optional int32 bar = 101;
}

protocol buffer 编译器除了生成 Foo 类之外，还会生成一个名为 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 {
    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。

服务（Services）

给定一个服务定义：

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

可以带 `grpc` 选项调用 protocol buffer 编译器（例如 --dart_out=grpc:output_folder），在这种情况下，它将生成支持 gRPC 的代码。更多详情请参阅 gRPC Dart 快速入门指南。