Kotlin 生成的代码指南

除了为 Java 生成的代码之外,还详细描述了 Protocol Buffer 编译器为任何给定的协议定义生成的 Kotlin 代码。

突出显示了 proto2 和 proto3 生成的代码之间的任何差异——请注意,这些差异存在于本文档中描述的生成的代码中,而不是基本消息类/接口中,这两个版本中的基本消息类/接口是相同的。在阅读本文档之前,您应该阅读proto2 语言指南和/或proto3 语言指南

编译器调用

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

无论您的 .proto 文件是否包含以下类似行

option java_multiple_files = true;

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

每个文件的 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/combuild/gen/kotlin/com/example 目录。但是,它不会创建 build/gen/kotlinbuild/genbuild;它们必须已经存在。您可以在单个调用中指定多个 .proto 文件;所有输出文件将一次生成。

消息

给定一个简单的消息声明

message FooBar {}

Protocol Buffer 编译器除了生成 Java 代码之外,还会生成一个名为 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 中推断出消息对象上的只读属性。)

请注意,属性始终使用驼峰命名法,即使 .proto 文件中的字段名称使用带有下划线的 小写字母(应该如此)。大小写转换的工作原理如下

  1. 对于名称中的每个下划线,都会删除下划线,并大写后面的字母。
  2. 如果名称将附加前缀(例如,“clear”),则首字母大写。否则,它将小写。

因此,字段 foo_bar_baz 变成 fooBarBaz

在一些特殊情况下,字段名称与 Kotlin 中的保留字或 protobuf 库中已定义的方法冲突,会附加额外的下划线。例如,名为 in 的字段的 clearer 是 clearIn_()

单一字段 (proto2)

对于以下任何字段定义

optional int32 foo = 1;
required 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 代码生成。

单一字段 (proto3)

对于此字段定义

int32 foo = 1;

编译器将在 DSL 中生成以下属性

  • var foo: Int:返回字段的当前值。如果未设置字段,则返回该字段类型的默认值。
  • fun clearFoo():清除字段的值。调用此方法后,getFoo() 将返回该字段类型的默认值。

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

嵌入式消息字段

对于消息字段类型,在 DSL 中会生成一个额外的访问器方法

  • boolean hasFoo():如果已设置字段,则返回 true

请注意,没有基于 DSL 设置子消息的快捷方式。例如,如果您有一个字段

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(仅限 proto2):如果 oneof 案例为 FOO,则返回 true
  • val foo: Int:如果 oneof 案例为 FOO,则返回 oneof_name 的当前值。否则,返回此字段的默认值。

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

映射字段

对于此映射字段定义

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)

给定一条带有扩展范围的消息

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>:在 DSL 中获取重复扩展字段的当前值,作为只读 List

  • 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 {
  optional int32 bar = 123;
}

Java 生成“扩展标识符”bar,用于“键控”上面的扩展操作。