补充篇 9.2：Ktor DSL 深入——为什么 install、get、headers 可以这样写？

在上一篇 Logging 深入中我们遇到了这样一段代码install(Logging) { logger Logger.DEFAULT level LogLevel.ALL sanitizeHeader { it HttpHeaders.Authorization } }当时我们留下了一个问题logger Logger.DEFAULT这里为什么可以直接写logger为什么不是config.logger Logger.DEFAULT甚至连this.logger Logger.DEFAULT都不用写类似的代码在 Ktor 中还有很多client.get(/users) { headers { append(Authorization, token) } timeout { requestTimeoutMillis 10_000 } }这里的headers append timeout requestTimeoutMillis又都是从哪里来的如果不了解 Kotlin DSL这些代码看起来确实有一点“魔法”。但理解原理以后会发现Ktor DSL 并没有创造新的语法它本质上还是 Kotlin只是大量使用了 Lambda with Receiver带接收者 Lambda。这篇我们就把这层原理彻底拆开。一、先不要看 Ktor先看一个普通 Lambda假设我们自己定义一个配置类class LoggingConfig { var level: String INFO var enabled: Boolean true }现在写一个方法fun logging( block: (LoggingConfig) - Unit ) { val config LoggingConfig() block(config) }这里(LoggingConfig) - Unit就是一个普通 Lambda。意思是传进来的 Lambda 会接收一个LoggingConfig参数。所以调用时通常要写logging { config - config.level ALL config.enabled true }这里很好理解。Lambda 接收到一个config然后我们通过config.level config.enabled修改这个对象。二、如果我不想一直写config.呢Kotlin 提供了一种特殊的 LambdaLambda with Receiver中文通常叫带接收者 Lambda我们把刚才的方法改一下fun logging( block: LoggingConfig.() - Unit ) { val config LoggingConfig() config.block() }注意这里发生了一个非常重要的变化。原来是(LoggingConfig) - Unit现在变成LoggingConfig.() - Unit只多了一个.但是意义发生了变化。三、LoggingConfig.() - Unit到底是什么意思可以简单理解为这个 Lambda 执行的时候把一个LoggingConfig对象作为当前 Receiver也就是当前接收者。因此在 Lambda 内部this就是一个LoggingConfig对象。于是我们可以这样调用logging { this.level ALL this.enabled true }而 Kotlin 中成员访问时this通常可以省略。所以最终就变成logging { level ALL enabled true }这是不是已经开始很像 Ktor 了四、普通 Lambda 和带 Receiver Lambda 的区别可以直接这样理解普通 Lambda (LoggingConfig) - Unit ↓ logging { config - config.level ALL }而Lambda with Receiver LoggingConfig.() - Unit ↓ logging { level ALL }本质区别就是普通 Lambda ↓ 把对象作为参数传进来 Lambda with Receiver ↓ 把对象变成当前作用域的 Receiver所以level ALL实际上仍然可以理解为this.level ALL只不过 Kotlin 帮我们把this.省略了。五、现在重新回头看 Ktor Logging再来看install(Logging) { logger Logger.DEFAULT level LogLevel.ALL }前一篇我们已经知道logger来自 Logging 的配置对象。可以近似把 Logging 的配置类理解为class LoggingConfig { var logger: Logger var level: LogLevel // ... }而install(Logging) { ... }里面的配置块本质上就是类似LoggingConfig.() - Unit因此进入{ ... }以后当前 Receiver 就是LoggingConfig所以logger Logger.DEFAULT level LogLevel.ALL实际上可以理解成this.logger Logger.DEFAULT this.level LogLevel.ALL这里this ↓ LoggingConfig因此logger其实就是LoggingConfig.logger而level就是LoggingConfig.level现在是不是就不神秘了六、DSL 中“凭空出现”的方法也是一样再来看install(Logging) { sanitizeHeader { it HttpHeaders.Authorization } }为什么sanitizeHeader()可以直接调用同样的原因。因为它本身就是当前配置对象能够调用的方法。可以简单理解成class LoggingConfig { var logger: Logger var level: LogLevel fun sanitizeHeader( predicate: (String) - Boolean ) { // ... } }因此install(Logging) { sanitizeHeader { it HttpHeaders.Authorization } }实际可以理解成install(Logging) { this.sanitizeHeader { it HttpHeaders.Authorization } }所以以后在 DSL 中看到一个似乎突然出现的方法不要先认为它是什么全局函数。先问当前{}的 Receiver 是谁然后去 Receiver 对应的类型里找。七、Ktor 为什么这么喜欢 DSL如果 Ktor 不使用 DSL代码可能会更像这样val loggingConfig LoggingConfig() loggingConfig.logger Logger.DEFAULT loggingConfig.level LogLevel.ALL loggingConfig.sanitizeHeader { it HttpHeaders.Authorization } install(Logging, loggingConfig)从功能上来说当然也能做。但是配置越来越多以后就会出现大量loggingConfig.xxx requestConfig.xxx headerConfig.xxx timeoutConfig.xxxKtor 使用 Lambda with Receiver 以后install(Logging) { logger Logger.DEFAULT level LogLevel.ALL sanitizeHeader { it HttpHeaders.Authorization } }代码就变成了一种“配置语言”。这就是 DSL。DSL 全称Domain-Specific Language也就是领域特定语言它并不是创造一种新的编程语言。而是利用 Kotlin 本身的语法能力让代码写起来更接近当前业务领域的描述方式。例如headers { append(...) }看起来就像在说配置 Headers然后向里面添加一个 Header。这就是 DSL 带来的可读性。八、再看client.get {}理解 Logging 以后再看我们平时写的网络请求client.get(/users) { parameter(page, 1) header( HttpHeaders.Authorization, Bearer $token ) }为什么这里又能直接调用parameter() header()因为进入client.get { ... }这个配置块以后当前作用域又有了对应的 Request Builder。可以近似理解成client.get { ↓ HttpRequestBuilder }因此parameter(page, 1)本质上可以理解为this.parameter(page, 1)这里的this指向当前请求的 Builder。所以Logging DSL install(Logging) { ↓ LoggingConfig }而Request DSL client.get { ↓ HttpRequestBuilder }这两个{}长得一样但是里面的 Receiver 完全不同。这点非常重要。九、为什么进入headers {}后又能直接写append()再看client.get(/users) { headers { append( HttpHeaders.Authorization, Bearer $token ) } }这里其实发生了 DSL 的嵌套。外层client.get { ... }当前 Receiver 可以理解为HttpRequestBuilder但是进入headers { ... }以后又进入了一个新的 DSL 作用域。此时我们主要操作的对象变成了 Header Builder。于是append(...)就可以直接调用。可以画成client.get { │ │ Receiver ↓ HttpRequestBuilder │ │ └── headers { │ │ Receiver ↓ HeadersBuilder │ └── append(...) } }所以append(...)并不是突然出现的。它来自当前headers {}对应的 Receiver。十、timeout {}也是完全一样例如client.get(/users) { timeout { requestTimeoutMillis 10_000 connectTimeoutMillis 5_000 socketTimeoutMillis 10_000 } }为什么requestTimeoutMillis可以直接赋值还是一样。进入timeout { ... }以后当前配置作用域发生了变化。可以近似理解为timeout { ↓ HttpTimeoutConfig }所以requestTimeoutMillis 10_000其实就是this.requestTimeoutMillis 10_000这里的this就是 timeout 对应的配置对象。十一、真正理解 Ktor DSLReceiver 会不断变化现在看一个完整的例子client.get(/users) { parameter(page, 1) headers { append( HttpHeaders.Authorization, Bearer $token ) } timeout { requestTimeoutMillis 10_000 } }不要只是从上往下看代码。可以把它理解成不同 Receiver 作用域不断切换client.get { │ ↓ HttpRequestBuilder │ ├── parameter() │ ├── headers { │ │ │ ↓ │ HeadersBuilder │ │ │ └── append() │ └── timeout { │ ↓ Timeout 配置对象 │ └── requestTimeoutMillis } }这就是阅读 Ktor DSL 非常重要的一个思维方式不要只盯着函数名看要时刻知道自己现在处于哪个 Receiver 作用域。十二、install()和 Plugin 又是什么关系前面我们已经学习过 Ktor Plugininstall(Logging) { ... }这里不要把Logging和LoggingConfig混为一谈。可以这样理解HttpClient │ │ install ↓ Logging Plugin │ │ 配置 ↓ LoggingConfig也就是说install(Logging) { logger Logger.DEFAULT }里面Logging ↓ Plugin而logger level sanitizeHeader ↓ Logging 对应配置对象提供的能力所以 Ktor 的很多 Plugin 都会形成类似的结构install(ContentNegotiation) { ... }install(HttpTimeout) { ... }install(Logging) { ... }形式非常统一。区别只在于每一个 Plugin 的配置 Receiver 不一样因此{}里面能够使用的属性和函数也不一样。十三、为什么 IDE 自动补全这么重要理解 DSL 后你会发现学习 Ktor 有一个非常实用的方法假设看到install(Logging) { logger Logger.DEFAULT }不知道logger哪里来的。不要靠猜。直接Command / Ctrl 点击查看定义。你通常会发现它属于某个配置类。再例如timeout { requestTimeoutMillis 10_000 }不知道requestTimeoutMillis哪里来的。一样可以顺着 DSL 的 Receiver 找到对应配置对象。所以以后阅读 Ktor API可以养成一个习惯看到 {} ↓ 先看这个 Lambda 的类型 ↓ 找到 Receiver ↓ 再看 Receiver 提供了什么属性和方法十四、以后怎么看懂一个陌生的 Ktor DSL假设以后遇到一段完全没见过的代码xxx { abc 123 def { foo() } }先不要纠结abc 从哪来的 def 从哪来的 foo 又是什么按照下面这个方法拆。第一步看xxx {}的 Lambda 类型如果发现类似SomeConfig.() - Unit那么当前 Receiver 就是SomeConfig第二步去SomeConfig里找那么abc大概率就是SomeConfig.abc而def()也可能是SomeConfig.def()第三步如果又进入一层{}重新判断 Receiver例如def { foo() }进入def {}后Receiver 可能已经变了所以foo()不一定属于外面的SomeConfig。它可能属于新的 Receiver。这也是为什么复杂 DSL 中经常会出现一层套一层的结构。十五、自己写一个 DSL就彻底明白了理解一个东西最好的方式之一就是自己实现一次。例如我们想写出network { baseUrl https://api.example.com timeout { request 10_000 connect 5_000 } }先定义class TimeoutConfig { var request: Long 0 var connect: Long 0 }然后class NetworkConfig { var baseUrl: String val timeoutConfig TimeoutConfig() fun timeout( block: TimeoutConfig.() - Unit ) { timeoutConfig.block() } }最后定义fun network( block: NetworkConfig.() - Unit ) { val config NetworkConfig() config.block() }现在就可以写network { baseUrl https://api.example.com timeout { request 10_000 connect 5_000 } }展开以后其实就是val networkConfig NetworkConfig() networkConfig.baseUrl https://api.example.com networkConfig.timeoutConfig.request 10_000 networkConfig.timeoutConfig.connect 5_000你会发现所谓 DSL并没有什么神秘的。它只是把对象.属性 对象.方法通过 Receiver 作用域组织成了一种更加自然的配置形式。十六、Ktor DSL 和我们之前理解的 Plugin 是两件事这里还需要特别区分两个概念。我们前面学习 Ktor Plugin 时讲过install(Logging)本质上是在给HttpClient安装一种能力。例如Logging Auth ContentNegotiation HttpTimeout这些属于Ktor Plugin 机制而install(Logging) { logger Logger.DEFAULT level LogLevel.ALL }为什么里面可以这么写则属于Kotlin DSL Lambda with Receiver因此Plugin ↓ 解决“给 HttpClient 增加什么能力” DSL ↓ 解决“这些能力如何优雅地配置”两者不是一回事。但是 Ktor 把它们结合在了一起。因此我们最终看到的代码才会非常自然HttpClient { install(Logging) { level LogLevel.ALL } install(ContentNegotiation) { json() } install(HttpTimeout) { requestTimeoutMillis 15_000 } }表面看起来像一份配置文件。但实际上每一层依然都是 Kotlin 对象、函数和 Lambda。十七、再回头看logger Logger.DEFAULT现在再看上一篇留下来的问题install(Logging) { logger Logger.DEFAULT }就可以完整解释了。首先Logging ↓ Ktor 的 Logging Plugin然后进入它的配置 DSL{} ↓ Logging 对应的配置作用域因此logger其实是当前配置对象中的属性。所以logger Logger.DEFAULT可以理解成this.logger Logger.DEFAULT而这里的this就是 Logging 的配置 Receiver。最终logger ↓ 配置属性 Logger ↓ 接口 / 类型 Logger.DEFAULT ↓ Ktor 提供的默认 Logger 实现于是logger Logger.DEFAULT真正表达的是把 Ktor 默认提供的 Logger 实现设置给 Logging 插件的 logger 配置属性。到这里上一篇留下来的问题也就彻底解决了。十八、最后总结以后看到 Ktor DSL先找 Receiver这篇真正需要记住的并不是某一个 Ktor API。而是一套阅读方式。以后看到xxx { abc ... def() }第一反应不要是abc是什么神秘变量而应该是当前{}的 Receiver 是谁因为DSL 中看起来“凭空出现”的属性和函数 大多数时候 ↓ 都是当前 Receiver 的成员Ktor DSL 可以总结成三个核心点。第一Ktor DSL 没有创造新的 Kotlin 语法。第二它大量使用 Lambda with Receiver SomeConfig.() - Unit第三进入不同的 {} Receiver 可能会发生变化。因此阅读 Ktor DSL 时可以始终记住一句话看到{}先找 Receiver不知道属性从哪来就去 Receiver 里找。掌握这一点以后再看install {}get {}headers {}timeout {}json {}这些代码就不会再觉得是某种“特殊的 Ktor 语法”。它们本质上都是 Kotlin。只不过 Ktor 利用了 Kotlin DSL 的能力把 API 设计得更加像一种描述网络配置和请求行为的语言。