前言
对于Kotlin DSL不熟悉的同学建议先阅读
《Kotlin in Action》第11章 DSL构建
本文主要探讨Kotlin Contract DSL，熟悉源码的同学应该都不陌生.在我们经常使用的语法糖let,apply,isNullOrBlank 等中都有它们的身影出现，但是平时的开发我们可能都不会关心这个到底是做什么用的.但是随着Kotlin 1.3版本发布，contract渐渐放开了部分权限让开发者可以去使用，但是到底该如何使用？它有什么作用呢？本文将结合源码分析contract的设计、使用及其原理
Contract DSL 用武之地
我们平时开发中都会注意到编译器会对kotlin进行smartcasts，比如以下情况：
fun test(a: String?) {
if (a != null) {
a.length //在这里类型从String?智能转换成了String
}
}
但是，如果你在使用自定义的函数去处理检查，那么smartcasts就会消失, 比如以下情况：
fun String?.isNotNull(): Boolean = this != null
fun test(s: String?) {
if (s.isNotNull()) {
s.length //在这里不加？则无法通过编译 smartcasts消失了
}
}
为了改善这种情况，Kotlin 1.3引入了contract的实验机制.
contract允许函数以编译器理解的方式显式地描述其行为，其实就是告诉编译器我代码是1000%是正确的，你不要再来多此一举再做检查了！.
目前，该特性广泛应用以下两种场景：
- 通过声明函数的调用结果与传递的参数值之间的关系来改进智能广播分析
/**
* 需要在编译选项中开启实验功能-Xuse-experimental=kotlin.Experimental
* 并且kotlin版本要>=1.3
*/
@UseExperimental(ExperimentalContracts::class)
fun require(condition: Boolean) {
// 这是一种告诉编译器的语法方式
// 如果函数正常返回，则condition为true
contract { returns() implies condition }
if (!condition) throw IllegalArgumentException("NPE")
}
fun foo(s: String?) {
require(s is String)
s.length //如果s为非null值时,智能转换将会生效，后续操作将不需要再进行判空，否则将会抛出一个参数异常
}
- 在存在高阶函数的情况下改进变量初始化分析
/**
* 需要在编译选项中开启实验功能-Xuse-experimental=kotlin.Experimental
* 并且kotlin版本要>=1.3
*/
@UseExperimental(ExperimentalContracts::class)
fun synchronizeFunc(lock: Any?, block: () -> Unit) {
//告诉编译器这个block只会执行一次
contract {
callsInPlace(block, InvocationKind.EXACTLY_ONCE)
}
}
fun foo() {
val x: Int
synchronizeFunc(lock) {
x = 42 //编译器知道这个方法会只会执行一次，不会存在对一个val变量进行多次赋值的情况
}
println(x) // 编译器知道lambda将被明确调用，执行初始化
// 因此'x'被认为是在这里初始化的
}
stdlib已经大量使用了contract，所以大家不要担心之后contract是不是不会转正的问题.
contract目前表现十分稳定，大家可以放心大胆的去使用它.以下场景中，就是stdlib中的contract效果：
fun test(s: String?) {
if (!s.isNullOrEmpty()) {
println(s.length) //smartcast to not-null
}
}
Contract DSL 设计之路
在前面的例子中，我们看到contract callsInPlace InvocationKind.EXACTLY_ONCE returns implies等一大堆平时都没有见过的方法和字段. 这些字段其实分别在Effect和ContractBuilder两个类中，PY关系如下：
Effect: 该基础接口表示函数的调用效果，要么是直接可以观察的（正常返回的函数），要么可能是间接作用的(函数的Lambda参数调用).
ConditionalEffect: 该接口在Effect的基础之上，在观察函数的调用效果之后，某些条件是否会为true. 常用在contract{ }中指定,通过使用函数[SimpleEffect.implies]将布尔表达式附加到另一个[SimpleEffect]效果，
SimpleEffect: 表示函数调用之后可以观察的效果
- implies(booleanExpression: Boolean): ConditionalEffect: 指定此效果在观察时保证[booleanExpression]为true。 注意：[booleanExpression]只能接受布尔表达式的子集，
例如以下示例:
public inline fun CharSequence?.isNullOrEmpty(): Boolean {
contract {
returns(false) implies (this@isNullOrEmpty != null)
}
return this == null || this.length == 0
}
implies接收了(this@isNullOrEmpty != null)表示当前字符串为null时，直接告诉编译器当前条件为false，这有什么用呢？如果我们使用了!xxx.isNullOrEmpty,那么编译就会智能认定后续的xxx肯定不为null，则不会在提示你去加?进行防御编程.
关于为什么是returns而不是return？我们在后面讲解ContractBuilder时详细介绍.
Returns: 该接口描述函数正常返回给定值的情况
ReturnsNotNull: 该接口描述函数正常返回任何非null返回值的情况
CallsInPlace: 该接口表示调用函数式参数(lambda表达式参数)的效果，并且函数式参数(lambda表达式参数)只能在自己函数被调用期间被调用，当自己函数被调用结束后，函数式参数(lambda表达式参数)不能被执行.
大家看是不是觉得很眼熟啊？
| 方法 | 返回值 |
|---|---|
| returns | Returns |
| returnsNotNull | ReturnsNotNull |
| callsInPlace | CallsInPlace |
这么一看，其实就是对应方法调用之后的返回效果.
我们再来看一看这些方法都是什么意思，怎么用的?
ContractBuilder
注解ExperimentalContracts: 由于目前合同还是属于实现API,所以在声明合同的地方加上该注解.
returns(): 描述函数正常返回(无返回值)但没有抛出任何异常的情况。不能单独使用，需要使用[SimpleEffect.Implies]函数来描述在这种情况下发生的条件效果。
fun embedVariable(x: Any, b: Boolean) {
contract {
//当b==true并且x是一个非空String时正常返回（无返回值）
returns() implies (b && x is String)
}
}
returns(value: Any?): 描述函数以指定的return [value]正常返回的情况。同样的也要配合使用[SimpleEffect.Implies]函数来描述在这种情况下发生的条件效果
[value]的可能值限于true，false或null。
fun threeReturnsValue(b: Boolean?) {
contract {
returns(true) implies (b == true)
returns(null) implies (b == null)
returns(false) implies (b == false)
}
}
returnsNotNull(): 描述函数正常返回任何非“null”值的情况。使用[SimpleEffect.Implies]函数来描述在这种情况下发生的条件效果。
fun threeReturnsValue(b: Boolean) {
contract {
returnsNotNull() implies (b != null)
returns(true) implies (b)
returns(false) implies (!b)
}
}
callsInPlace: 用于在适当的位置调用函数参数[lambda]，该合同有以下规定：
- 函数[lambda]只能在所有者函数调用期间调用，并且在完成所有者函数调用后不会调用它;
- （可选）函数[lambda]被调用[kind]参数指定的次数，请参阅[InvocationKind]枚举以获取可能的值。
声明callsInPlace效果的函数必须是inline。
@kotlin.internal.InlineOnly
public inline fun <T> T.apply(block: T.() -> Unit): T {
contract {
//该block在所有者函数调用期间只会执行一次
callsInPlace(block, InvocationKind.EXACTLY_ONCE)
}
block()
return this
}
InvocationKind
- AT_MOST_ONCE: 函数参数将被调用一次或根本不被调用
- AT_LEAST_ONCE: 函数参数将被调用一次或多次。
- EXACTLY_ONCE: 函数参数将被调用一次
- UNKNOWN: 函数参数就地调用，但不知道可以调用多少次。
总结
本文的内容收益主要是帮助我们去理解底层的实现与原理，仔细研究就会发现套路其实就那么几种，但是用的好就是奇淫技巧. 为了我们以后使用的得心应手，一起来研究吧 ~
