Kotlin 生成的代码指南

本文重点指出了 proto2、proto3 和 editions 生成的代码之间的所有差异——请注意，这些差异存在于本文档描述的生成代码中，而不是在基础消息类/接口中，后者在所有版本中都是相同的。在阅读本文档之前，您应先阅读 proto2 语言指南、proto3 语言指南和/或Editions 指南。

编译器调用

Protocol Buffer 编译器会生成构建在 Java 代码之上的 Kotlin 代码。因此，调用它时必须使用两个命令行标志：--java_out= 和 --kotlin_out=。--java_out= 选项的参数是您希望编译器写入 Java 输出的目录，--kotlin_out= 也是如此。对于每个输入的 .proto 文件，编译器都会创建一个包装器 .java 文件，其中包含一个表示 .proto 文件本身的 Java 类。

无论您的 .proto 文件是否包含类似下面这行内容：

option java_multiple_files = true;

编译器都会为它将为 .proto 文件中声明的每个顶级消息生成的每个类和工厂方法创建单独的 .kt 文件。

每个文件的 Java 包名与 Java 生成代码参考中描述的生成 Java 代码所使用的包名相同。

输出文件是通过拼接 --kotlin_out= 的参数、包名（将点 [.] 替换为斜杠 [/]）以及后缀为 Kt.kt 的文件名来确定的。

因此，举例来说，假设您像下面这样调用编译器：

protoc --proto_path=src --java_out=build/gen/java --kotlin_out=build/gen/kotlin src/foo.proto

如果 foo.proto 的 Java 包是 com.example，并且它包含一个名为 Bar 的消息，那么 Protocol Buffer 编译器将生成文件 build/gen/kotlin/com/example/BarKt.kt。Protocol Buffer 编译器会自动创建 build/gen/kotlin/com 和 build/gen/kotlin/com/example 目录（如果需要）。但是，它不会创建 build/gen/kotlin、build/gen 或 build；它们必须已经存在。您可以在一次调用中指定多个 .proto 文件；所有输出文件将一次性生成。

消息

给定一个简单的消息声明：

message FooBar {}

除了生成的 Java 代码之外，Protocol Buffer 编译器还会生成一个名为 FooBarKt 的对象，以及两个顶级函数，其结构如下：

object FooBarKt {
  class Dsl private constructor { ... }
}
inline fun fooBar(block: FooBarKt.Dsl.() -> Unit): FooBar
inline fun FooBar.copy(block: FooBarKt.Dsl.() -> Unit): FooBar

嵌套类型

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

message Foo {
  message Bar { }
}

在这种情况下，编译器将 BarKt 对象和 bar 工厂方法嵌套在 FooKt 内部，但 copy 方法仍是顶级的：

object FooKt {
  class Dsl { ... }
  object BarKt {
    class Dsl private constructor { ... }
  }
  inline fun bar(block: FooKt.BarKt.Dsl.() -> Unit): Foo.Bar
}
inline fun foo(block: FooKt.Dsl.() -> Unit): Foo
inline fun Foo.copy(block: FooKt.Dsl.() -> Unit): Foo
inline fun Foo.Bar.copy(block: FooKt.BarKt.Dsl.() -> Unit): Foo.Bar

字段

除了上一节中描述的方法外，Protocol Buffer 编译器还会在 DSL 中为 .proto 文件中消息内定义的每个字段生成可变属性。（Kotlin 已经从 Java 生成的 getter 中推断出消息对象上的只读属性。）

请注意，属性始终使用驼峰命名法（camel-case），即使 .proto 文件中的字段名使用带下划线的小写字母（这是推荐的做法）。大小写转换规则如下：

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

因此，字段 foo_bar_baz 变为 fooBarBaz。

在少数特殊情况下，当字段名与 Kotlin 中的保留字或 protobuf 库中已定义的方法冲突时，会附加一个额外的下划线。例如，名为 in 的字段的清除器是 clearIn_()。

单一字段

对于此字段定义：

int32 foo = 1;

编译器将在 DSL 中生成以下访问器：

• fun hasFoo(): Boolean：如果字段已设置，则返回 true。对于使用隐式存在性的字段，不会生成此方法。
• var foo: Int：字段的当前值。如果字段未设置，则返回默认值。
• fun clearFoo()：清除字段的值。调用此方法后，hasFoo() 将返回 false，getFoo() 将返回默认值。

对于其他简单字段类型，相应的 Java 类型是根据标量值类型表选择的。对于消息和枚举类型，值类型将被替换为消息或枚举类。由于消息类型仍然在 Java 中定义，因此消息中的无符号类型在 DSL 中使用标准的相应有符号类型表示，以与 Java 和旧版 Kotlin 兼容。

内嵌消息字段

请注意，对子消息没有特殊处理。例如，如果您有一个字段：

optional Foo my_foo = 1;

您必须这样写：

myFoo = foo {
  ...
}

通常，这是因为编译器不知道 Foo 是否有 Kotlin DSL，或者例如是否只生成了 Java API。这意味着您不必等待您依赖的消息添加 Kotlin 代码生成。

重复字段

对于此字段定义：

repeated string foo = 1;

编译器将在 DSL 中生成以下成员：

• class FooProxy: DslProxy，一个不可构造的类型，仅用于泛型。
• val fooList: DslList<String, FooProxy>，一个只读视图，显示重复字段中当前元素的列表。
• fun DslList<String, FooProxy>.add(value: String)，一个扩展函数，允许向重复字段中添加元素。
• operator fun DslList<String, FooProxy>.plusAssign(value: String)，add 的别名。
• fun DslList<String, FooProxy>.addAll(values: Iterable<String>)，一个扩展函数，允许将一个 Iterable 的元素添加到重复字段中。
• operator fun DslList<String, FooProxy>.plusAssign(values: Iterable<String>)，addAll 的别名。
• operator fun DslList<String, FooProxy>.set(index: Int, value: String)，一个扩展函数，用于设置给定零基索引处元素的值。
• fun DslList<String, FooProxy>.clear()，一个扩展函数，用于清除重复字段的内容。

这种不寻常的构造使得 fooList 在 DSL 的作用域内“表现得像”一个可变列表，只支持底层构建器支持的方法，同时防止可变性“逃离” DSL，这可能会导致令人困惑的副作用。

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

Oneof 字段

对于此 oneof 字段定义：

oneof oneof_name {
    int32 foo = 1;
    ...
}

编译器将在 DSL 中生成以下访问器方法：

• val oneofNameCase: OneofNameCase：获取设置了 oneof_name 中的哪个字段（如果有）；返回类型请参阅Java 代码参考。
• fun hasFoo(): Boolean：如果 oneof 的情况是 FOO，则返回 true。
• val foo: Int：如果 oneof 的情况是 FOO，则返回 oneof_name 的当前值。否则，返回此字段的默认值。

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

映射字段

对于此 map 字段定义：

map<int32, int32> weight = 1;

编译器将在 DSL 类中生成以下成员：

• class WeightProxy private constructor(): DslProxy()，一个不可构造的类型，仅用于泛型。
• val weight: DslMap<Int, Int, WeightProxy>，一个只读视图，显示映射字段中的当前条目。
• fun DslMap<Int, Int, WeightProxy>.put(key: Int, value: Int)：将条目添加到此映射字段。
• operator fun DslMap<Int, Int, WeightProxy>.put(key: Int, value: Int)：使用操作符语法的 put 别名。
• fun DslMap<Int, Int, WeightProxy>.remove(key: Int)：如果存在，则移除与 key 关联的条目。
• fun DslMap<Int, Int, WeightProxy>.putAll(map: Map<Int, Int>)：将指定映射中的所有条目添加到此映射字段，覆盖已存在键的先前值。
• fun DslMap<Int, Int, WeightProxy>.clear()：清除此映射字段中的所有条目。

扩展

给定一个带有扩展范围的 proto2 或 editions 消息：

message Foo {
  extensions 100 to 199;
}

Protocol Buffer 编译器将向 FooKt.Dsl 添加以下方法：

• operator fun <T> get(extension: ExtensionLite<Foo, T>): T：获取 DSL 中扩展字段的当前值。
• operator fun <T> get(extension: ExtensionLite<Foo, List<T>>): ExtensionList<T, Foo>：以只读 List 的形式获取 DSL 中重复扩展字段的当前值。
• operator fun <T : Comparable<T>> set(extension: ExtensionLite<Foo, T>)：设置 DSL 中扩展字段的当前值（对于 Comparable 字段类型）。
• operator fun <T : MessageLite> set(extension: ExtensionLite<Foo, T>)：设置 DSL 中扩展字段的当前值（对于消息字段类型）。
• operator fun set(extension: ExtensionLite<Foo, ByteString>)：设置 DSL 中扩展字段的当前值（对于 bytes 字段）。
• operator fun contains(extension: ExtensionLite<Foo, *>): Boolean：如果扩展字段有值，则返回 true。
• fun clear(extension: ExtensionLite<Foo, *>)：清除扩展字段。
• fun <E> ExtensionList<Foo, E>.add(value: E)：向重复扩展字段添加一个值。
• operator fun <E> ExtensionList<Foo, E>.plusAssign(value: E)：使用操作符语法的 add 别名。
• operator fun <E> ExtensionList<Foo, E>.addAll(values: Iterable<E>)：向重复扩展字段添加多个值。
• operator fun <E> ExtensionList<Foo, E>.plusAssign(values: Iterable<E>)：使用操作符语法的 addAll 别名。
• operator fun <E> ExtensionList<Foo, E>.set(index: Int, value: E)：设置重复扩展字段在指定索引处的元素。
• inline fun ExtensionList<Foo, *>.clear()：清除重复扩展字段的元素。

这里的泛型很复杂，但效果是 this[extension] = value 对除重复扩展之外的每种扩展类型都有效，而重复扩展具有“自然的”列表语法，其工作方式类似于非扩展的重复字段。

给定一个扩展定义：

extend Foo {
  int32 bar = 123;
}

Java 生成“扩展标识符” bar，用于“键控”上述扩展操作。