initTag(tag: T, init: T.() -> Unit): T {
tag.init()
children.add(tag)
return tag
}
override fun render(builder: StringBuilder, indent: String) {
builder.append("$indent<$name${renderAttributes()}>\n")
for (c in children) {
c.render(builder, indent + " ")
}
builder.append("$indent\n")
}
private fun renderAttributes(): String {
val builder = StringBuilder()
for ((attr, value) in attributes) {
builder.append(" $attr=\"$value\"")
}
return builder.toString()
}
override fun toString(): String {
val builder = StringBuilder()
render(builder, "")
return builder.toString()
}
}
abstract class TagWithText(name: String) : Tag(name) {
operator fun String.unaryPlus() {
children.add(TextElement(this))
}
}
class HTML() : TagWithText("html") {
fun head(init: Head.() -> Unit) = initTag(Head(), init)
fun body(init: Body.() -> Unit) = initTag(Body(), init)
}
class Head() : TagWithText("head") {
fun title(init: Title.() -> Unit) = initTag(Title(), init)
}
class Title() : TagWithText("title")
abstract class BodyTag(name: String) : TagWithText(name) {
fun b(init: B.() -> Unit) = initTag(B(), init)
fun p(init: P.() -> Unit) = initTag(P(), init)
fun h1(init: H1.() -> Unit) = initTag(H1(), init)
fun ul(init: UL.() -> Unit) = initTag(UL(), init)
fun a(href: String, init: A.() -> Unit) {
val a = initTag(A(), init)
a.href = href
}
}
class Body() : BodyTag("body")
class UL() : BodyTag("ul") {
fun li(init: LI.() -> Unit) = initTag(LI(), init)
}
class B() : BodyTag("b")
class LI() : BodyTag("li")
class P() : BodyTag("p")
class H1() : BodyTag("h1")
class A : BodyTag("a") {
var href: String
get() = attributes["href"]!!
set(value) {
attributes["href"] = value
}
}
fun html(init: HTML.() -> Unit): HTML {
val html = HTML()
html.init()
return html
}
```
```
HTML encoding with Kotlin
HTML encoding with Kotlin
this format can be used as an
alternative markup to HTML
Kotlin
This is some
mixed
text. For more see the
Kotlin
project
some text
-
1*2 = 2
-
2*2 = 4
-
3*2 = 6
-
4*2 = 8
-
5*2 = 10
```
## 工作原理
假设你需要用 Kotlin 来实现一个类型安全的构建器.
首先, 要对你想要构建的东西定义一组模型. 在这个示例中, 需要对 HTML 标签建模.
这个任务很简单, 只需要定义一组对象就可以了.
比如, `HTML` 是一个类, 负责描述 `` 标签, 它可以定义子标签, 比如 `` 和 ``.
(这个类的具体定义请参见[下文](#full-definition-of-the-com-example-html-package).)
现在, 回忆一下为什么你可以写这样的代码:
```KOTLIN
html {
// ...
}
```
`html` 实际上是一个函数调用, 它接受一个 [Lambda 表达式](lambdas.html) 作为参数.
这个函数的定义如下:
```KOTLIN
fun html(init: HTML.() -> Unit): HTML {
val html = HTML()
html.init()
return html
}
```
这个函数只接受唯一一个参数, 名为 `init`, 这个参数本身又是一个函数.
其类型是 `HTML.() -> Unit`, 它是一个 带接受者的函数类型.
也就是说, 你应该向这个函数传递一个 `HTML` 的实例(一个 接收者)作为参数,
而且在函数内, 你可以调用这个实例的成员.
接受者可以通过 `this` 关键字来访问:
```KOTLIN
html {
this.head { ... }
this.body { ... }
}
```
(`head` 和 `body` 是 `HTML` 类的成员函数.)
现在, `this` 关键字可以省略, 通常都是如此, 省略之后你的代码就已经非常接近一个构建器了:
```KOTLIN
html {
head { ... }
body { ... }
}
```
那么, 这个函数调用做了什么? 我们来看看上面定义的 `html` 函数体.
首先它创建了一个 `HTML` 类的新实例, 然后它调用通过参数得到的函数, 来初始化这个 `HTML` 实例
(在这个示例中, 这个初始化函数对 `HTML` 实例调用了 `head` 和 `body` 方法), 然后, 这个函数返回这个 `HTML` 实例.
这正是构建器应该做的.
`HTML` 类中 `head` 和 `body` 函数的定义与 `html` 函数类似.
唯一的区别是, 这些函数会将自己创建的对象实例添加到自己所属的 `HTML` 实例的 `children` 集合中:
```KOTLIN
fun head(init: Head.() -> Unit): Head {
val head = Head()
head.init()
children.add(head)
return head
}
fun body(init: Body.() -> Unit): Body {
val body = Body()
body.init()
children.add(body)
return body
}
```
实际上这两个函数做的事情完全相同, 因此你可以编写一个泛型化的函数, 名为 `initTag`:
```KOTLIN
protected fun initTag(tag: T, init: T.() -> Unit): T {
tag.init()
children.add(tag)
return tag
}
```
然后, 这你的函数就变得很简单了:
```KOTLIN
fun head(init: Head.() -> Unit) = initTag(Head(), init)
fun body(init: Body.() -> Unit) = initTag(Body(), init)
```
现在你可以使用这两个函数来构建 `` 和 `` 标签了.
还需要讨论的一个问题是, 你要如何在标签内部添加文本.
在上面的示例程序中, 你写了这样的代码:
```KOTLIN
html {
head {
title {+"XML encoding with Kotlin"}
}
// ...
}
```
你所作的, 仅仅只是将一个字符串放在一个标签之内, 但在字符串之前有一个小小的 `+`,
所以, 它是一个函数调用, 被调用的是前缀操作符函数 `unaryPlus()`.
这个操作符实际上是由扩展函数 `unaryPlus()` 定义的,
这个扩展函数是抽象类 `TagWithText` 的成员 (这个抽象类是 `Title` 类的祖先类):
```KOTLIN
operator fun String.unaryPlus() {
children.add(TextElement(this))
}
```
所以, 前缀操作符 `+` 所作的, 是将一个字符串封装到 `TextElement` 的一个实例中,
然后将这个实例添加到 `children` 集合中, 然后这个字符串就会成为标签树中一个适当的部分.
以上所有类和函数都定义在 `com.example.html` 包中, 上面的构建器示例程序的最上部引入了这个包.
在最后一节中, 你可以读到这个包的完整定义.
## 控制接受者的作用范围: @DslMarker
使用 DSL 时, 可能遇到的一个问题就是, 当前上下文中存在太多可供调用的函数.
在 Lambda 表达式内, 你可以调用所有 [隐含接受者](lambdas.html#function-literals-with-receiver) 的所有方法,
因此造成一种不正确的结果, 比如一个 `head` 之内可以嵌套另一个 `head` 标签:
```KOTLIN
html {
head {
head {} // 应该禁止这样的调用
}
// ...
}
```
在这个示例中, 应该只允许调用离当前代码最近的隐含接受者 `this@head` 的成员函数;
`head()` 是更外层接受者 `this@html` 的成员函数,因此调用它应该是不允许的.
为了解决这个问题, 有一种特殊机制来控制接受者的作用范围.
要让编译器控制接受者的作用范围, 你只需要用一个相同的注解, 对 DSL 中用到的所有接受者的类型进行标注.
比如, 对 HTML 构建器你可以定义一个注解 `@HtmlTagMarker`:
```KOTLIN
@DslMarker
@Target(AnnotationTarget.CLASS)
annotation class HtmlTagMarker
```
如果对一个注解类标注了 `@DslMarker` 注解, 我们将它称作一个 DSL 标记.
`@Target` 注解限制了 `@HtmlTagMarker` 能够使用的范围.
DSL 标记只有在应用于以下目标时, 才会影响作用范围控制:
* 类型声明 (`CLASS`): 用作 DSL 接受者的类或接口.
* 类型使用 (`TYPE`): 在函数类型签名中的接受者类型.
* 类型别名 (`TYPEALIAS`): 对 DSL 接受者类型进行扩展的类型别名.
将 DSL 标记应用到其他目标 (例如函数或属性), 不会对作用范围控制造成影响.
Note:
关于 DSL 标记的工作方式, 详情请参见相应的 [KEEP 文档](https://github.com/Kotlin/KEEP/blob/main/notes/0005-dsl-marker.md).
在我们的 DSL 中, 所有的标签类都继承自相同的超类 `Tag`.
只需要对超类标注 `@HtmlTagMarker` 注解就够了,
然后 Kotlin 编译器会将所有的派生类都看作已被标注了同样的注解:
```KOTLIN
@HtmlTagMarker
abstract class Tag(val name: String) { ... }
```
你不必对 `HTML` 或 `Head` 类再标注 `@HtmlTagMarker` 注解, 因为它们的超类已经标注过了这个注解:
```KOTLIN
class HTML() : Tag("html") { ... }
class Head() : Tag("head") { ... }
```
标注这个注解之后, Kotlin 编译器就可以知道哪些隐含的接受者属于相同的 DSL, 因此编译器只允许代码调用离当前位置最近的接受者的成员函数:
```KOTLIN
html {
head {
head { } // 编译错误: 这是外层接受者的成员函数, 因此不允许在这里调用
}
// ...
}
```
注意, 如果确实需要调用外层接受者的成员函数, 仍然是可以实现的, 但这时你必须明确指定具体的接受者:
```KOTLIN
html {
head {
this@html.head { } // 仍然可以调用外层接受者的成员函数
}
// ...
}
```
你也可以直接对 [函数类型](lambdas.html#function-types) 使用 `@DslMarker` 注解.
这需要在注解的使用目标(Target)中包含 `AnnotationTarget.TYPE`:
```KOTLIN
@DslMarker
@Target(AnnotationTarget.CLASS, AnnotationTarget.TYPE)
annotation class HtmlTagMarker
```
这样做之后, `@DslMarker` 注解就可以被用于函数类型了, 最常见的情况是用于带接受者的 Lambda 表达式.
例如:
```KOTLIN
fun html(init: @HtmlTagMarker HTML.() -> Unit): HTML { ... }
fun HTML.head(init: @HtmlTagMarker Head.() -> Unit): Head { ... }
fun Head.title(init: @HtmlTagMarker Title.() -> Unit): Title { ... }
```
当你调用这些函数时, 在标注了 `@DslMarker` 注解的 Lambda 表达式的 body 部中, 这个注解会限制对外层接受者的访问,
除非你明确的指明接受者:
```KOTLIN
html {
head {
title {
// 在这里, 会禁止访问外层接受者的 title, head 或其它函数.
}
}
}
```
在 Lambda 表达式内, 只有最内层的接受者的成员和扩展可以访问, 防止在嵌套的作用域之间发生意外的交互.
如果一个作用域中存在相同名称的隐含接受者成员和来自 [上下文参数](context-parameters.html) 的声明,
编译器会报告警告信息, 因为隐含接受者会被上下文参数遮盖.
要解决这个问题, 请使用 `this` 限定符, 明确的调用接受者, 或者使用 `contextOf()` 调用上下文声明:
```KOTLIN
interface HtmlTag {
fun setAttribute(name: String, value: String)
}
// 声明相同名称的顶层函数,
// 这个函数可以通过上下文参数访问
context(tag: HtmlTag)
fun setAttribute(name: String, value: String) { tag.setAttribute(name, value) }
fun test(head: HtmlTag, extraInfo: HtmlTag) {
with(head) {
// 在内层作用域中引入一个相同类型的上下文值
context(extraInfo) {
// 这里会出现警告:
// Uses an implicit receiver shadowed by a context parameter
setAttribute("user", "1234")
// 明确的调用接受者的成员
this.setAttribute("user", "1234")
// 明确的调用上下文声明
contextOf().setAttribute("user", "1234")
}
}
}
```
### com.example.html 包的完整定义
下面是 `com.example.html` 包的完整定义(但只包含上文示例程序使用到的元素).
它可以构建一个 HTML 树.
这段代码大量使用了 [扩展函数](extensions.html) 和 [带接受者的 Lambda 表达式](lambdas.html#function-literals-with-receiver).
```KOTLIN
package com.example.html
interface Element {
fun render(builder: StringBuilder, indent: String)
}
class TextElement(val text: String) : Element {
override fun render(builder: StringBuilder, indent: String) {
builder.append("$indent$text\n")
}
}
@DslMarker
@Target(AnnotationTarget.CLASS, AnnotationTarget.TYPE)
annotation class HtmlTagMarker
@HtmlTagMarker
abstract class Tag(val name: String) : Element {
val children = arrayListOf()
val attributes = hashMapOf()
protected fun initTag(tag: T, init: T.() -> Unit): T {
tag.init()
children.add(tag)
return tag
}
override fun render(builder: StringBuilder, indent: String) {
builder.append("$indent<$name${renderAttributes()}>\n")
for (c in children) {
c.render(builder, indent + " ")
}
builder.append("$indent\n")
}
private fun renderAttributes(): String {
val builder = StringBuilder()
for ((attr, value) in attributes) {
builder.append(" $attr=\"$value\"")
}
return builder.toString()
}
override fun toString(): String {
val builder = StringBuilder()
render(builder, "")
return builder.toString()
}
}
abstract class TagWithText(name: String) : Tag(name) {
operator fun String.unaryPlus() {
children.add(TextElement(this))
}
}
class HTML : TagWithText("html") {
fun head(init: Head.() -> Unit) = initTag(Head(), init)
fun body(init: Body.() -> Unit) = initTag(Body(), init)
}
class Head : TagWithText("head") {
fun title(init: Title.() -> Unit) = initTag(Title(), init)
}
class Title : TagWithText("title")
abstract class BodyTag(name: String) : TagWithText(name) {
fun b(init: B.() -> Unit) = initTag(B(), init)
fun p(init: P.() -> Unit) = initTag(P(), init)
fun h1(init: H1.() -> Unit) = initTag(H1(), init)
fun a(href: String, init: A.() -> Unit) {
val a = initTag(A(), init)
a.href = href
}
}
class Body : BodyTag("body")
class B : BodyTag("b")
class P : BodyTag("p")
class H1 : BodyTag("h1")
class A : BodyTag("a") {
var href: String
get() = attributes["href"]!!
set(value) {
attributes["href"] = value
}
}
fun html(init: HTML.() -> Unit): HTML {
val html = HTML()
html.init()
return html
}
```
# 通过构建器类型推断(Builder Type Inference)使用构建器
Kotlin 支持 构建器类型推断(Builder Type Inference) (或者叫构建器推断),
当你使用泛型构建器时, 这个功能可以很有用.
它能够帮助编译器, 通过构建器的 Lambda 表达式参数内的其它调用的类型信息, 推断出构建器调用的类型参数.
请参考下面的示例程序中对
[buildMap()](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.collections/build-map.html)
的使用:
```KOTLIN
fun addEntryToMap(baseMap: Map, additionalEntry: Pair?) {
val myMap = buildMap {
putAll(baseMap)
if (additionalEntry != null) {
put(additionalEntry.first, additionalEntry.second)
}
}
}
```
这里没有足够的类型信息来通过通常的方式推断类型参数, 但构建器推断能够分析 Lambda 表达式参数内的函数调用.
根据 `putAll()` 和 `put()` 调用的类型信息, 编译器可以自动将 `buildMap()` 调用的类型参数推断为 `String` 和 `Number`.
使用泛型构建器时, 构建器推断功能允许我们省略类型参数.
## 编写你自己的构建器
### 启用构建器推断的要求条件
Note:
在 Kotlin 1.7.0 以前, 对一个构建器函数启用构建器推断, 需要添加编译器选项 `-Xenable-builder-inference`.
在 1.7.0 中, 这个选项会默认启用.
要对你自己的构建器使用构建器推断, 请确认它的声明有一个构建器 Lambda 表达式参数, 类型为带接受者的函数类型.
对接受者类型还有 2 个要求:
1. 它应该使用构建器推断需要推断的那个类型参数. 比如:
```KOTLIN
fun buildList(builder: MutableList.() -> Unit) { ... }
```
Note:
注意, 直接传递类型参数的类型, 比如 `fun myBuilder(builder: T.() -> Unit)`, 目前还不支持.
2. 它应该提供 public 成员函数, 或扩展函数, 签名中包含对应的类型参数. 比如:
```KOTLIN
class ItemHolder {
private val items = mutableListOf()
fun addItem(x: T) {
items.add(x)
}
fun getLastItem(): T? = items.lastOrNull()
}
fun ItemHolder.addAllItems(xs: List) {
xs.forEach { addItem(it) }
}
fun itemHolderBuilder(builder: ItemHolder.() -> Unit): ItemHolder =
ItemHolder().apply(builder)
fun test(s: String) {
val itemHolder1 = itemHolderBuilder { // itemHolder1 的类型是 ItemHolder
addItem(s)
}
val itemHolder2 = itemHolderBuilder { // itemHolder2 的类型是 ItemHolder
addAllItems(listOf(s))
}
val itemHolder3 = itemHolderBuilder { // itemHolder3 的类型是 ItemHolder
val lastItem: String? = getLastItem()
// ...
}
}
```
### 支持的功能
构建器推断支持以下功能:
* 推断多个类型参数 ```KOTLIN fun myBuilder(builder: MutableMap.() -> Unit): Map { ... } ```
* 推断一个调用之内, 相互依赖的多个构建器 Lambda 表达式的类型参数 ```KOTLIN fun myBuilder( listBuilder: MutableList.() -> Unit, mapBuilder: MutableMap.() -> Unit ): Pair, Map> = mutableListOf().apply(listBuilder) to mutableMapOf().apply(mapBuilder) fun main() { val result = myBuilder( { add(1) }, { put("key", 2) } ) // result 的类型是 Pair, Map> } ```
* 推断 Lambda 表达式的参数或返回类型中出现的类型参数 ```KOTLIN fun myBuilder1( mapBuilder: MutableMap.() -> K ): Map = mutableMapOf().apply { mapBuilder() } fun myBuilder2( mapBuilder: MutableMap.(K) -> Unit ): Map = mutableMapOf().apply { mapBuilder(2 as K) } fun main() { // result1 推断得到的类型是 Map val result1 = myBuilder1 { put(1L, "value") 2 } val result2 = myBuilder2 { put(1, "value 1") // 你可以将 `it` 用作 "推迟类型变量" 类型 // 详情请参见以下章节 put(it, "value 2") } } ```
## 构建器推断的工作原理
### 推迟类型变量(Postponed Type Variable)
构建器推断使用 推迟类型变量(Postponed Type Variable), 在构建器推断分析时, 它出现在构建器的 Lambda 表达式之内.
一个推迟类型变量的类型是类型参数中的一个, 具体类型还在推断过程中.
编译器使用它来收集类型参数的类型信息.
我们来看看下面示例中的 [buildList()](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.collections/build-list.html):
```KOTLIN
val result = buildList {
val x = get(0)
}
```
这里 `x` 的类型是推迟类型变量: `get()` 调用返回一个类型 `E` 的值, 但 `E` 自身还未确定.
在这个时刻, 还不知道 `E` 的确定类型.
当一个推迟类型变量的值关联到一个确定的类型, 构建器推断会收集这个信息, 在构建器推断分析结束后, 推断对应的类型参数的结果类型.
比如:
```KOTLIN
val result = buildList {
val x = get(0)
val y: String = x
} // result 的类型推断为 List
```
在推迟类型变量赋值给一个 `String` 类型变量之后, 构建器推断得到信息, `x` 是 `String` 的子类型.
这个赋值是构建器 Lambda 表达式内的最后一条语句, 因此构建器推断分析结束, 结果是将类型参数 `E` 推断为 `String`.
注意, 你总是可以将推迟类型变量作为接受者, 调用 `equals()`, `hashCode()`, 和 `toString()` 函数.
### 向构建器推断结果贡献信息
构建器推断可以收集不同种类的类型信息, 这些信息都会贡献到分析结果.
它会考虑以下信息:
* 对 Lambda 表达式的接受者, 使用类型参数的类型调用方法 ```KOTLIN val result = buildList { // 根据传递的 "value" 参数, 类型参数被推断为 String add("value") } // result 的类型被推断为 List ```
* 对返回类型参数类型的调用, 指定期望的类型 ```KOTLIN val result = buildList { // 根据期待的类型, 类型参数被推断为 Float val x: Float = get(0) } // result 的类型被推断为 List ``` ```KOTLIN class Foo { val items = mutableListOf() } fun myBuilder(builder: Foo.() -> Unit): Foo = Foo().apply(builder) fun main() { val result = myBuilder { val x: List = items // ... } // result 的类型被推断为 Foo } ```
* 向期待确定类型的方法传递推迟类型变量的类型 ```KOTLIN fun takeMyLong(x: Long) { ... } fun String.isMoreThat3() = length > 3 fun takeListOfStrings(x: List) { ... } fun main() { val result1 = buildList { val x = get(0) takeMyLong(x) } // result1 的类型为 List val result2 = buildList { val x = get(0) val isLong = x.isMoreThat3() // ... } // result2 的类型为 List val result3 = buildList { takeListOfStrings(this) } // result3 的类型为 List } ```
* 取得一个指向 Lambda 表达式接受者的成员的可调用的引用 ```KOTLIN fun main() { val result = buildList { val x: KFunction1 = ::get } // result 的类型为 List } ``` ```KOTLIN fun takeFunction(x: KFunction1) { ... } fun main() { val result = buildList { takeFunction(::get) } // result 的类型为 List } ```
在分析结束后, 构建器推断考虑收集的所有类型信息, 尝试合并这些信息得到结果类型. 请看下面的示例.
```KOTLIN
val result = buildList { // 开始推断推迟类型变量 E
// 认为 E 是 Number 或 Number 的一个子类型
val n: Number? = getOrNull(0)
// 认为 E 是 Int 或 Int 的一个超类型
add(1)
// E 被推断为 Int
} // result 的类型为 List
```
结果类型是与分析过程中收集到的类型信息对应的最具体的类型.
如果给定的类型信息是发生矛盾, 无法合并, 编译器会报告错误.
注意, 只有在通常的类型推断无法推断类型参数时, Kotlin 编译器才会使用构建器推断.
也就是说, 你可以在构建器 Lambda 表达式之外贡献类型信息, 那么就不需要构建器推断分析了. 请看下面的示例:
```KOTLIN
fun someMap() = mutableMapOf()
fun MutableMap.f(x: MutableMap) { ... }
fun main() {
val x: Map = buildMap {
put("", "")
f(someMap()) // 类型不匹配 (要求 String 类型, 但实际是 CharSequence 类型)
}
}
```
这里会出现类型不匹配, 因为在构建器 Lambda 表达式之外指定了期待的 Map 类型.
编译器会使用固定的接受者类型 `Map` 来分析 Lambda 表达式内的所有的语句.
# 上下文参数(Context Parameter)
Tip:
上下文参数替代了旧的实验性功能 [上下文接受者(Context Receiver)](whatsnew1620.html#prototype-of-context-receivers-for-kotlin-jvm).
你可以在 [上下文参数的设计文档](https://github.com/Kotlin/KEEP/blob/master/proposals/context-parameters.md#summary-of-changes-from-the-previous-proposal) 中找到它们的主要差别.
要从上下文接受者迁移到上下文参数, 你可以使用 IntelliJ IDEA 中的辅助支持,
详情请参见相关的 [blog](https://blog.jetbrains.com/kotlin/2025/04/update-on-context-parameters/).
上下文参数(Context Parameter) 允许函数和属性声明在周围上下文(Surrounding Context)中隐含可用的依赖项.
使用上下文参数, 在一组函数调用中, 你就不需要手动的反复传递那些共用而且极少变更的值, 例如服务或依赖项.
要对属性和函数声明上下文参数, 请使用 `context` 关键字, 之后是参数列表, 每个参数声明为 `name: Type`.
下面是一个示例, 依赖于 `UserService` 接口:
```KOTLIN
// UserService 定义上下文中需要的依赖项
interface UserService {
fun log(message: String)
fun findUserById(id: Int): String
}
// 声明一个带有上下文参数的函数
context(users: UserService)
fun outputMessage(message: String) {
// 使用上下文中的 log
users.log("Log: $message")
}
// 声明一个带有上下文参数的属性
context(users: UserService)
val firstUser: String
// 使用上下文中的 findUserById
get() = users.findUserById(1)
fun main() {
val users = object : UserService {
override fun log(message: String) {
println(message)
}
override fun findUserById(id: Int): String {
return "User $id"
}
}
context(users) {
outputMessage("Looking up the first user")
println(firstUser)
// 输出结果为: User 1
}
}
```
可以使用 `_` 作为上下文参数的名称.
这种情况下, 参数值可以用来解析, 但在代码段内不能通过名称访问:
```KOTLIN
// 使用 "_" 作为上下文参数名称
context(_: UserService)
fun logWelcome() {
// 解析结果仍然能够从 UserService 找到适当的 log 函数
outputMessage("Welcome!")
}
```
## 上下文参数的解析
Kotlin 通过在当前的范围(Scope) 中搜索匹配的上下文值, 在调用端解析上下文参数.
Kotlin 会根据它们的类型进行匹配.
如果在同一个范围层级存在多个兼容的值, 编译器会报告歧义:
```KOTLIN
// UserService 定义上下文中需要的依赖项
interface UserService {
fun log(message: String)
}
// 声明一个带有上下文参数的函数
context(users: UserService)
fun outputMessage(message: String) {
users.log("Log: $message")
}
fun main() {
// 实现 UserService
val serviceA = object : UserService {
override fun log(message: String) = println("A: $message")
}
// 实现 UserService
val serviceB = object : UserService {
override fun log(message: String) = println("B: $message")
}
// 在调用端, serviceA 和 serviceB 都匹配期望的 UserService 类型
context(serviceA, serviceB) {
// 这会导致歧义错误
outputMessage("This will not compile")
}
}
```
### 明确的传递上下文参数
当多个函数重载的区别仅仅只是上下文参数不同, 如果存在多个匹配的上下文值, 那么函数调用就会发生歧义.
为了解决这种歧义, 请在调用处明确指定上下文参数:
```KOTLIN
class EmailSender
class SmsSender
context(emailSender: EmailSender)
fun sendNotification() {
println("Sent email notification")
}
context(smsSender: SmsSender)
fun sendNotification() {
println("Sent SMS notification")
}
context(defaultEmailSender: EmailSender, defaultSmsSender: SmsSender)
fun notifyUser() {
// 选择使用 EmailSender 上下文参数的重载函数
sendNotification(emailSender = defaultEmailSender)
// 选择使用 SmsSender 上下文参数的重载函数
sendNotification(smsSender = defaultSmsSender)
}
```
你也可以使用明确的上下文参数, 在某些函数调用中减少嵌套:
* 对单个调用, 使用明确的上下文参数, 可以让调用更加易读.
* 如果多个调用使用相同的上下文参数, 请使用 `context()` 函数.
这个功能是 [实验性功能](components-stability.html#stability-levels-explained).
要表示使用者同意(Opt-in), 请向你的构建脚本文件添加以下编译器选项:
Gradle:
```KOTLIN
kotlin {
compilerOptions {
freeCompilerArgs.add("-Xexplicit-context-arguments")
}
}
```
Maven:
```XML
org.jetbrains.kotlin
kotlin-maven-plugin
-Xexplicit-context-arguments
```
## 限制
上下文参数还在不断改进中, 目前的一些限制包括:
* 构造器不能声明上下文参数.
* 上下文参数的属性不能拥有后端域变量(Backing Field), 也不能拥有初始化器.
* 带上下文参数的属性 不能使用委托.
尽管存在这些限制, 上下文参数通过简化依赖项注入, 改进 DSL 设计, 以及范围操作, 简化了依赖的管理.
# 内联函数(Inline Function)
使用 [高阶函数](lambdas.html) 在运行时会带来一些不利: 每个函数都是一个对象, 而且它还要捕获一个闭包,
闭包是指一个环境范围, 在这个范围内, 函数体内部可以访问外层变量.
内存占用(函数对象和类都会占用内存) 以及虚方法调用都会带来运行时的消耗.
但在很多情况下, 通过将 Lambda 表达式内联在使用处, 可以消除这些运行时消耗.
下文中的函数就是很好的例子. `lock()` 函数可以很容易地内联在调用处.
看看下面的例子:
```KOTLIN
lock(l) { foo() }
```
编译器可以直接产生下面的代码, 而不必为参数创建函数对象, 然后再调用这个参数指向的函数:
```KOTLIN
l.lock()
try {
foo()
} finally {
l.unlock()
}
```
为了让编译器做到这点, 需要对 `lock()` 函数标记 `inline` 修饰符:
```KOTLIN
inline fun lock(lock: Lock, body: () -> T): T { ... }
```
`inline` 修饰符既会影响到函数本身, 也影响到传递给它的 Lambda 表达式: 这两者都会被内联到调用处.
函数内联也许会导致编译产生的代码尺寸变大.
但只要你合理的使用(不要内联太大的函数), 就可以换来性能的提高, 尤其是在循环内发生的 "megamorphic" 函数调用.
(译注: 关于 megamorphic 请参见 [Inline caching](https://en.wikipedia.org/wiki/Inline_caching#Megamorphic_inline_caching))
## noinline
如果一个内联函数的参数中有多个 Lambda 表达式, 而你只希望内联其中的一部分,
可以对函数的一部分参数添加 `noinline` 修饰符:
```KOTLIN
inline fun foo(inlined: () -> Unit, noinline notInlined: () -> Unit) { ... }
```
可内联的 Lambda 表达式只能在内联函数内部调用, 或者再作为可内联的参数传递给其他函数,
而 `noinline` 的 Lambda 表达式可以按照你喜欢的方式任意使用:
可以保存在域内, 也可以当作参数传递, 等等.
Note:
如果一个内联函数不存在可以内联的函数类型参数, 而且没有 [实体化的类型参数](#reified-type-parameters),
编译器将会产生一个警告, 因为将这样的函数内联不太可能带来任何益处.
(如果你确信需要内联, 可以使用 `@Suppress("NOTHING_TO_INLINE")` 注解关闭这个警告)
## 非局部(non-local)的跳转表达式
### return
在 Kotlin 中, 使用无限定符的通常的 `return` 语句, 只能用来退出一个有名称的函数, 或匿名函数.
要退出一个 Lambda 表达式, 可以使用一个 [标签](returns.html#return-to-labels).
在 Lambda 表达式内禁止使用无标签的 `return`, 因为 Lambda 表达式不允许强制包含它的函数 `return`:
```KOTLIN
fun ordinaryFunction(block: () -> Unit) {
println("hi!")
}
//sampleStart
fun foo() {
ordinaryFunction {
return // 错误: 这里不允许让 `foo` 函数返回
}
}
//sampleEnd
fun main() {
foo()
}
```
但是, 如果 Lambda 表达式被传递去的函数是内联函数, 那么 `return` 语句也可以内联, 因此 `return` 是允许的:
```KOTLIN
inline fun inlined(block: () -> Unit) {
println("hi!")
}
//sampleStart
fun foo() {
inlined {
return // OK: 这里的 Lambda 表达式是内联的
}
}
//sampleEnd
fun main() {
foo()
}
```
这样的 `return` 语句(位于 Lambda 表达式内部, 但是退出包含 Lambda 表达式的函数) 称为 非局部(non-local) 返回.
这样的结构经常出现在循环中, 而循环也常常就是包含内联函数的地方:
```KOTLIN
fun hasZeros(ints: List): Boolean {
ints.forEach {
if (it == 0) return true // 从 hasZeros 函数返回
}
return false
}
```
注意, 有些内联函数可能并不在自己的函数体内直接调用传递给它的 Lambda 表达式参数, 而是通过另一个执行环境来调用,
比如通过一个局部对象, 或者一个嵌套函数. 这种情况下, 在 Lambda 表达式内, 非局部的控制流同样是禁止的.
为了标识内联函数的 Lambda 表达式参数不能使用非局部(non-local)返回,
需要对 Lambda 表达式参数添加 `crossinline` 修饰符:
```KOTLIN
inline fun f(crossinline body: () -> Unit) {
val f = object: Runnable {
override fun run() = body()
}
// ...
}
```
### break 和 continue
与非局部的(non-local) `return` 类似, 对于包含循环的内联函数, 在作为参数传递给内联函数的 Lambda 表达式中,
你也可以使用 `break` 和 `continue` [跳转表达式](returns.html):
```KOTLIN
fun processList(elements: List): Boolean {
for (element in elements) {
val variable = element.nullableMethod() ?: run {
log.warning("Element is null or invalid, continuing...")
continue
}
if (variable == 0) return true
}
return false
}
```
## 实体化的类型参数(Reified type parameter)
有些时候你需要访问作为参数传递来的类型:
```KOTLIN
fun TreeNode.findParentOfType(clazz: Class): T? {
var p = parent
while (p != null && !clazz.isInstance(p)) {
p = p.parent
}
@Suppress("UNCHECKED_CAST")
return p as T?
}
```
这里, 你向上遍历一颗树, 然后使用反射来检查节点是不是某个特定的类型.
这些都没问题, 但这个函数的调用代码不太漂亮:
```KOTLIN
treeNode.findParentOfType(MyTreeNode::class.java)
```
更好的解决方案是简单地将一个类型传递给这个函数, 可以像这样调用它:
```KOTLIN
treeNode.findParentOfType()
```
为了达到这个目的, 内联函数支持 实体化的类型参数(reified type parameter), 使用这个功能你可以将代码写成:
```KOTLIN
inline fun TreeNode.findParentOfType(): T? {
var p = parent
while (p != null && p !is T) {
p = p.parent
}
return p as T?
}
```
上面的代码给类型参数添加了 `reified` 修饰符, 使得它可以在函数内部访问, 就好像它是一个普通的类一样.
由于函数是内联的, 因此不必使用反射, 而且通常的操作符都可以使用, 比如 `!is` 和 `as`.
此外, 你可以通过上面提到那种方式来调用这个函数: `myTree.findParentOfType()`.
虽然很多情况下并不需要, 但你仍然可以对一个实体化的类型参数使用反射:
```KOTLIN
inline fun membersOf() = T::class.members
fun main(s: Array