本文翻譯自 Kotlin DSL: from Theory to Practice，并且做了精簡(jiǎn)，只摘出了重要的部分，并且配合上自己的理解。

主要的語(yǔ)言工具

下面我們先列舉寫(xiě)出我們自己的 DSL 所需要的 Kotlin 特性：

最終結(jié)果

schedule {
    data {
        startFrom("08:00")
        subjects("Russian",
                "Literature",
                "Algebra",
                "Geometry")
        student {
            name = "Ivanov"
            subjectIndexes(0, 2)
        }
        student {
            name = "Petrov"
            subjectIndexes(1, 3)
        }
        teacher {
           subjectIndexes(0, 1)
           availability {
             monday("08:00")
             wednesday("09:00", "16:00")
           } 
        }
        teacher {
            subjectIndexes(2, 3)
            availability {
                thursday("08:00") + sameDay("11:00") + sameDay("14:00")
            }
        }
        // data { } won't be compiled here because there is scope control with
        // @DataContextMarker
    } assertions {
        for ((day, lesson, student, teacher) in scheduledEvents) {
            val teacherSchedule: Schedule = teacher.schedule
            teacherSchedule[day, lesson] shouldNotEqual null
            teacherSchedule[day, lesson]!!.student shouldEqual student
            val studentSchedule = student.schedule
            studentSchedule[day, lesson] shouldNotEqual null
            studentSchedule[day, lesson]!!.teacher shouldEqual teacher
        }
    }
}

工具箱

我們將使用第一節(jié)表格中列出的「語(yǔ)言工具」來(lái)構(gòu)建出上面的代碼。下面我們一個(gè)一個(gè)來(lái)說(shuō)。

Lambda out of parentheses

lambda 表達(dá)式不用多說(shuō)了。我們看「最終結(jié)果」中的代碼，幾乎所有使用花括號(hào)的地方都是 lambda 表達(dá)式。
我們有兩種方式來(lái)寫(xiě)出 x { ... } 這樣的構(gòu)造函數(shù)：

• x 是一個(gè) object，然后調(diào)用它的 invoke 方法（這個(gè)我們后面會(huì)討論）
• 函數(shù) x 接收一個(gè) lambda
  不管是哪一種，其實(shí)我們都使用了 lambda。我們來(lái)看看第二種函數(shù) x() 的方式。在 Kotlin 中，如果 lambda 是函數(shù)的最后一個(gè)參數(shù)，那么它可以放在括號(hào)外面。如果 lambda 還是這個(gè)函數(shù)的唯一參數(shù)，那么函數(shù)的括號(hào)也可以省略。結(jié)果就是 x({...}) -> x() {...} -> x {...}。函數(shù) x 的聲明如下所示：

fun x(lambda: () -> Unit) { lambda() }

或者

fun x(lambda: () -> Unit) = lambda()

但是如果 x 是一個(gè)類(lèi)實(shí)例，或者一個(gè) object 呢？下面是另一種常用于 DSL 的方法：操作符重載。

Operator overloading

實(shí)際上，我們?cè)?Kotlin 中經(jīng)常使用「操作符重載」，比如在兩個(gè)集合間使用的 +。
這一節(jié)，我們討論一個(gè)更加小眾的操作符 invoke。本文「最終結(jié)果」中的代碼是以 schedule {} 構(gòu)造開(kāi)始的。這個(gè)構(gòu)造不同于我們上一小節(jié)中提到的 「Lambda out of a parentheses」，而是使用了 invoke 操作符與「Lambda out of a parentheses」。只要我們重載了 invoke 操作符，即使 schedule 是一個(gè) object，我們依然可以寫(xiě)成 schedule()（這樣 schedule 就像是一個(gè)函數(shù)了，因?yàn)?invoke 操作符就是 ()）。事實(shí)上，當(dāng)你調(diào)用 schedule(...) 時(shí)，編譯器會(huì)將其翻譯為 schedule.invoke()。下面我們看看是如何定義 schedule 的：

object schedule {
    operator fun invoke(init: SchedulingContext.() -> Unit) {
        SchedulingContext().init()
    }
}

所以，當(dāng)我們調(diào)用 schedule 時(shí)，其實(shí)是調(diào)用的 object schedule 的 invoke 方法。又因?yàn)?invoke 方法接收唯一的 lambda 參數(shù)，所以當(dāng)我們寫(xiě) schedule {...} 時(shí)，其實(shí)是調(diào)用的：

schedule.invoke( { code inside lambda } )

最后，你再仔細(xì)看 invoke 方法，會(huì)發(fā)現(xiàn)它接收的不是一個(gè)普通的 lambda 表達(dá)式，而是一個(gè)帶接收者的 lambda（「lambda with a handler」）表達(dá)式。它的類(lèi)型定義如下：

SchedulingContext.() -> Unit

注意，上面的 invoke 操作符其實(shí)就是 ()

Lambda with a handler

Kotlin 允許開(kāi)發(fā)者為 lambda 表達(dá)式設(shè)置一個(gè) context（本文中 context 和 handler 是同一個(gè)意思）。Context 其實(shí)就是一個(gè)對(duì)象，Context 的類(lèi)型在 lambda 表達(dá)式定義時(shí)一同被指明。這樣的 lambda 表達(dá)式能夠訪(fǎng)問(wèn)到 Context 中的非靜態(tài) public 方法。
普通的 lambda 表達(dá)式是像這樣定義：() -> Unit，但是帶有 Context X 的 lambda 表達(dá)式是這樣定義的：X.() -> Unit。而且，普通的 lambda 表達(dá)式能夠像下面這樣調(diào)用：

val x: () -> Unit = {}
x()

而帶有 Context 的 lambda 表達(dá)式則需要傳入一個(gè) context：

class MyContext
val x: MyContext.() -> Unit = {}
// x() // 不會(huì)通過(guò)編譯，因?yàn)?context 沒(méi)有被定義
val c = MyContext() // 創(chuàng)建一個(gè) context
c.x() // 正確
x(c) // 正確

記住，在前面章節(jié)中我們重載了 schedule 的 invoke 操作符，并使其接收一個(gè) lambda 表達(dá)式，這使得我們可以這樣寫(xiě)：

schedule { }

invoke 接收的 lambda 是一個(gè)帶 context 的 lambda，context 類(lèi)型為 SchedulingContext。而 SchedulingContext 有一個(gè) data 方法，因此我們可以這樣寫(xiě)：

schedule {
    data {
        // ...
    }
}

你或許已經(jīng)猜到了，data 也是一個(gè)接收帶 context 的 lambda 表達(dá)式的方法，只不過(guò)這是另外一個(gè) context。這樣我們就得到了一個(gè)嵌套的結(jié)構(gòu)，而且同時(shí)有多個(gè) context。我們把所有的語(yǔ)法糖都去掉之后，應(yīng)該寫(xiě)成下面這樣：

schedule.invoke({
    this.data({
        // ...
    })
})

我們?cè)賮?lái)看一下 invoke 操作符的實(shí)現(xiàn)：

operator fun invoke(init: SchedulingContext.() -> Unit) {
    SchedulingContext().init()
}

我們首先構(gòu)造了 context SchedulingContext()，讓后我們?cè)?context 上調(diào)用傳入進(jìn)來(lái)的 lambda 參數(shù)名 init，這樣我們就在 context SchedulingContext() 中執(zhí)行了 lambda 表達(dá)式。

get/set methods convention

在創(chuàng)建 DSL 時(shí)，我們可以實(shí)現(xiàn)一種方式，以一個(gè)或多個(gè) key 來(lái)訪(fǎng)問(wèn) map：

availabilityTable[DayOfWeek.MONDAY, 0] = true
println(availabilityTable[DayOfWeek.MONDAY, 0]) // output: true

為了使用方括號(hào)，我們需要實(shí)現(xiàn) get 或 set 的操作符方法（帶有 operator 的方法）。如下所示：

class Matrix(...) {
    private val content: List<MutableList<T>>
    operator fun get(i: Int, j: Int) = content[i][j]
    operator fun set(i: Int, j: Int, value: T) { content[i][j] = value }
}

事實(shí)上，你可以向 get 和 set 操作符方法傳任意參數(shù)，來(lái)完成許多有趣的功能。

Type aliases

類(lèi)型別名沒(méi)什么好說(shuō)的，就是為一個(gè)類(lèi)型取一個(gè)別名，使其更具表意性。比如 Pair，它雖然可以方便地接收一對(duì)兒數(shù)據(jù)，但是我們卻丟失了這對(duì)兒數(shù)據(jù)需要綁定在一起的原因信息。通過(guò)別名，我們可以在不新增類(lèi)型的情況下保留描述數(shù)據(jù)的信息：

typealias Point = Pair
val point = Point(0, 0)

類(lèi)型別名其實(shí)只是將類(lèi)型的構(gòu)造函數(shù)用別名進(jìn)行調(diào)用而已，因此沒(méi)有新增類(lèi)型。

Destructing declaration

「解構(gòu)聲明」的意思就是能夠拆解一個(gè)對(duì)象為幾個(gè)變量。舉個(gè)我們常用的例子：

val (x, y) = Point(0, 0)

「解構(gòu)聲明」的主要是通過(guò) componentN 操作符來(lái)實(shí)現(xiàn)的，主要使用場(chǎng)景也是一次性聲明多個(gè)變量。上面的代碼實(shí)際上是像如下調(diào)用的：

val pair = Point(0, 0)
val x = pair.component1()
val y = pair.component2()

上面的 component1() 和 component2() 都是操作符。如果 Point 是 Pair 的別名，那么 Pair 是自帶 componentN() 操作符的。如果 Point 是普通的類(lèi)，我們自定義 componentN() 一樣可以實(shí)現(xiàn)上面的效果：

class Point(val x: Int, val y: Int) {
    operator fun component1(): Int {
        return this.x
    }

    operator fun component2(): Int {
        return this.y
    }
}

除了 Pair，還有 data class 也是自帶 componentN() 的?？梢钥吹健缸罱K結(jié)果」代碼中有：

for ((day, lesson, student, teacher) in scheduledEvents) { ... }

其中 scheduledEvents 就是一個(gè) Set，通過(guò) for 循環(huán)遍歷其中的每一個(gè)元素。而每一個(gè)元素類(lèi)型都是一個(gè) data class，因此能夠直接被「解構(gòu)聲明」為 4 個(gè)屬性。

Extension functions

「擴(kuò)展函數(shù)」也不必多說(shuō)，我們經(jīng)常使用：

fun Availability.monday(from: String, to: String? = null)

Availability 是 Matrix 的別名，因此上面的聲明等同于：

fun Matrix.monday(from: String, to: String? = null)

擴(kuò)展函數(shù)不僅可以用于類(lèi)，還可以用于接口：

fun Iterable.first(): T

這樣，任何一個(gè)實(shí)現(xiàn)了 Iterable 的集合類(lèi)都擁有了 first 方法。

Infix functions

「中綴函數(shù)」主要是為了讓我們擺脫過(guò)多的代碼?！缸罱K結(jié)果」代碼中有使用的地方：

teacherSchedule[day, lesson] shouldNotEqual null

上面代碼等同于：

teacherSchedule[day, lesson].shouldNotEqual(null)

在某些情況下，括號(hào)和點(diǎn)號(hào)都是多余的。這種情況下我們就可以使用「中綴函數(shù)」。上面的代碼中，teacherSchedule[day, lesson] 返回一個(gè) schedule 元素，然后 shouldNotEqual 函數(shù)會(huì)檢查該元素是否為 null。
聲明「中綴函數(shù)」，你需要：

• 使用 infix 修飾符
• 只有一個(gè)參數(shù)

shouldNotEqual 中綴函數(shù)實(shí)現(xiàn)：

infix fun <T: Any?> T.shouldNotEqual(expected: T) {
    Assert.assertThat(this, not(equalTo(expected)))
}

注意，所有的泛型默認(rèn)都是 Any 的子類(lèi)（非空的），這種情況下我們就不能使用 null。所以我們上面需要讓 T 顯式地繼承自 Any?。

Context control

當(dāng)我們嵌套了太多 context 時(shí)，在內(nèi)層的 context 就變得異常復(fù)雜。

schedule { // context SchedulingContext
    data { // context DataContext + external context ShedulingContext
        data {  } // possible, as there is no context control
    }
}

在 Kotlin 1.1 以前有一種方法能夠避免上面的混亂情況。當(dāng)我們?cè)趦?nèi)層的 DataContext 中創(chuàng)建 data 方法時(shí)，用 @Deprecated 注解該方法，并將其設(shè)置為 ERROR 級(jí)別。

class DataContext {
    @Deprecated(level = DeprecationLevel.ERROR, message = "Incorrect context")
    fun data(init: DataContext.() -> Unit) {}
}

這種注解的方法可以消除創(chuàng)建錯(cuò)誤 DSL 的可能性。然而，當(dāng)我們的 context 有大量方法時(shí)，我們需要給每一個(gè)方法都寫(xiě)上注解，這是非常難以接受的。

Kotlin 1.1 提供了一個(gè)新的控制方法 —— @DslMarker 注解。這個(gè)注解用于標(biāo)注你自己的注解類(lèi)，然后你自己的注解類(lèi)可以用于標(biāo)注 context 類(lèi)。

@DslMarker
annotation class MyCustomDslMarker

現(xiàn)在我們需要注解 context。在「最終結(jié)果」中，context 是 SchedulingContext 和 DataContext：

@MyCustomDslMarker
class SchedulingContext { ... }

@MyCustomDslMarker
class DataContext { ... }

fun demo() {
    schedule { // context SchedulingContext
        data { // context DataContext + external context SchedulingContext is forbidden
            // data {} // will not compile, as context are annotated with the same DSK marker
        }
    }
}

工程實(shí)踐

上面都是翻譯自原文，所以上面「最終結(jié)果」中的代碼可以去原文的 github 工程中查看。下面看下使用上面的技術(shù)后，我們工程中是如何應(yīng)用的。工程中的例子如下：我們需要維護(hù)一個(gè)集合，它是一組遙控器到一組設(shè)備的映射，它的含義是，在遙控器組中的每一臺(tái)遙控器都能控制設(shè)備組中的所有設(shè)備。

/**
 * 所有遙控器 - 支持機(jī)型 的映射
 */
val RC_GROUP_TO_DEVICE_GROUP = rcGroupToDeviceGroup {
    group {
        rcGroup(
                RemoteControllerType.RC1,
                RemoteControllerType.RC2,
                RemoteControllerType.RC3
        )
        deviceGroup(
                ProductType.P1,
                ProductType.P2
        )
    }
    group {
        rcGroup(RemoteControllerType.RC4)
        deviceGroup(ProductType.P1)
    }
}

DSL 的實(shí)現(xiàn)如下，文章里所說(shuō)的 context，在我的工程代碼里叫做 builder，因?yàn)檫@個(gè) context 的作用其實(shí)就是構(gòu)建實(shí)例對(duì)象，因此也是 builder。：

/**
 * 用于遙控器組 <--> 設(shè)備組 的映射
 */
data class RcGroupToDeviceGroup(val rcToDeviceMap: ArrayMap<HashSet<RemoteControllerType>, HashSet<ProductType>>) {
    /**
     * 所有遙控器的集合
     */
    val remoteControllers = mutableSetOf<RemoteControllerType>().apply {
        rcToDeviceMap.forEach { (rcTypes, _) -> addAll(rcTypes) }
    }.toList()

    /**
     * 所有設(shè)備的集合
     */
    val productTypes = mutableSetOf<ProductType>().apply {
        rcToDeviceMap.forEach { (_, productTypes) -> addAll(productTypes) }
    }.toList()
}

@RcGroupToDeviceGroupDSLMarker
class RcGroupAndDeviceGroupBuilder {
    val rcs = mutableSetOf<RemoteControllerType>()
    val devices = mutableSetOf<ProductType>()

    fun rcGroup(vararg rcGroup: RemoteControllerType) {
        rcs.addAll(rcGroup)
    }

    fun deviceGroup(vararg deviceGroup: ProductType) {
        devices.addAll(deviceGroup)
    }
}

@RcGroupToDeviceGroupDSLMarker
class RcGroupToDeviceGroupBuilder {
    private var rcGroupToDeviceGroup = arrayMapOf<HashSet<RemoteControllerType>, HashSet<ProductType>>()

    fun group(block: RcGroupAndDeviceGroupBuilder.() -> Unit) {
        val builder = RcGroupAndDeviceGroupBuilder()
        block.invoke(builder)
        rcGroupToDeviceGroup[builder.rcs.toHashSet()] = builder.devices.toHashSet()
    }

    fun build(): RcGroupToDeviceGroup = RcGroupToDeviceGroup(rcGroupToDeviceGroup)
}

// DSL 的調(diào)用從這里開(kāi)始。這里使用的是方法直接調(diào)用，也可以使用文章中的 object 重載 invoke 來(lái)實(shí)現(xiàn)。
fun rcGroupToDeviceGroup(block: RcGroupToDeviceGroupBuilder.() -> Unit): RcGroupToDeviceGroup = RcGroupToDeviceGroupBuilder().apply(block).build()

@DslMarker
annotation class RcGroupToDeviceGroupDSLMarker