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/com
和 build/gen/kotlin/com/example
目录。但是,它不会创建 build/gen/kotlin
、build/gen
或 build
;它们必须已经存在。您可以在单个调用中指定多个 .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
文件中的字段名称使用带有下划线的 小写字母(应该如此)。大小写转换的工作原理如下
- 对于名称中的每个下划线,都会删除下划线,并大写后面的字母。
- 如果名称将附加前缀(例如,“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
:如果扩展字段有值,则返回 truefun 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
,用于“键控”上面的扩展操作。