Kotlin contract 用法及原理

Kotlin contract 用法及原理

在阅读Kotlin源码的时候，会发现很多常用方法里都有contract的身影：

/**
     * Calls the specified function [block] with `this` value as its receiver and returns `this` value.
     *
     * For detailed usage information see the documentation for [scope functions](https://kotlinlang.org/docs/reference/scope-functions.html#apply).
     */
    public inline fun <T> T.apply(block: T.() -> Unit): T {
        contract {
            callsInPlace(block, InvocationKind.EXACTLY_ONCE)
        }
        block()
        return this
    }

    /**
     * Calls the specified function [block] with `this` value as its argument and returns `this` value.
     *
     * For detailed usage information see the documentation for [scope functions](https://kotlinlang.org/docs/reference/scope-functions.html#also).
     */
    public inline fun <T> T.also(block: (T) -> Unit): T {
        contract {
            callsInPlace(block, InvocationKind.EXACTLY_ONCE)
        }
        block(this)
        return this
    }

contract(契约)是一种 Kotlin 面向编译器约定的一种规则，它帮助编译器更加智能地识别某些需要特定的代码条件，为代码创建更加友好的上下文关联环境。

1、contract定义

Kotlin在1.3版本以实验室功能的方式开始引入contract，截止至当前Kotlin最新版本1.6.10，contract方法依然添加有@ExperimentalContracts注解，这说明官方认为其能力还不够稳定。

/**
     * Specifies the contract of a function.
     *
     * The contract description must be at the beginning of a function and have at least one effect.
     *
     * Only the top-level functions can have a contract for now.
     *
     * @param builder the lambda where the contract of a function is described with the help of the [ContractBuilder] members.
     *
     */
    @ContractsDsl
    @ExperimentalContracts
    @InlineOnly
    @SinceKotlin("1.3")
    @Suppress("UNUSED_PARAMETER")
    public inline fun contract(builder: ContractBuilder.() -> Unit) { }

在其构造类ContractBuilder中定义了四种方法：returns()、returns(value: Any?)、returnsNotNull()、callsInPlace(...)，方法的作用后面举例子详细说明就会明白它的作用。

public interface ContractBuilder {
        @ContractsDsl public fun returns(): Returns

        @ContractsDsl public fun returns(value: Any?): Returns
 
        @ContractsDsl public fun returnsNotNull(): ReturnsNotNull
        
        @ContractsDsl public fun <R> callsInPlace(lambda: Function<R>, kind: InvocationKind = InvocationKind.UNKNOWN): CallsInPlace
    }

有三种返回类型：Returns、ReturnsNotNull、CallsInPlace，均继承自Effect接口：

/**
     * Describes a situation when a function returns normally with a given return value.
     *
     * @see ContractBuilder.returns
     */
    public interface Returns : SimpleEffect

    /**
     * Describes a situation when a function returns normally with any non-null return value.
     *
     * @see ContractBuilder.returnsNotNull
     */
    public interface ReturnsNotNull : SimpleEffect

    /**
     * An effect of calling a functional parameter in place.
     *
     * A function is said to call its functional parameter in place, if the functional parameter is only invoked
     * while the execution has not been returned from the function, and the functional parameter cannot be
     * invoked after the function is completed.
     *
     * @see ContractBuilder.callsInPlace
     */
    public interface CallsInPlace : Effect

Returns和 ReturnsNotNull代表的是返回结果的效果导向、CallsInPlace则代表的是执行次数的效果导向。

2、使用场景

为什么需要contract呢？它的作用是什么，继续往下看。声明一个抽象接口File：

abstract class File

子类 PdfFile继承自 File，并且定义了一个专属的子类方法。

class PdfFile: File() {
        fun convertToWord() {
            // do 
        }
    }

在Kotlin中，有自动类型推断，一但判断过类型，后面会自动转换成对应类型使用。这个叫做智能类型转换：Smart cast to PdfFile。

fun move(file: File) {
        if (file is PdfFile) {
            //Smart cast to PdfFile
            file.convertToWord()
        }
    }

但是如果通过方法判断的呢？判断逻辑抽取到独立的方法中：

fun isPDF(file: File): Boolean {
        //逻辑可能更复杂
        return file is PdfFile
    }

由于没有直接上下文，这时候编译器就不能帮我们自动类型转换，会报错：Unresolved reference: convertToWord。

fun move2(file: File) {
        if (isPDF(file)) {
            //Unresolved reference: convertToWord
            file.convertToWord()
        }
    }

虽然编译器完全可以在编译的时候深入方法分析，进而实现类型推断，但是会浪费编译时间，完全没必要。这时候contract契约就出现，通过人为的约定，告诉编译器一些信息。人是会出错的，所以这种方式对开发水平有要求，contract定义的契约一定要可靠。

3、使用contract

这种场景下contract就派上用场了，可以让参数类型在执行的方法上下文传递，方法执行完毕后，继续将类型等信息传递给后续的方法进行编译。

3.1、根据返回结果约定

借助returns()、returns(value: Any?)、returnsNotNull()可以根据方法执行的结果返回约定信息。

@OptIn(ExperimentalContracts::class)
    fun isPDF(file: File): Boolean {
        contract {
            returns(true) implies (file is PdfFile)
        }
        return file is PdfFile
    }

比如在前面的例子里，通过加入contract中的Returns效果，此时在调用 isPDF(file) 返回 true 后，编译器已经知道参数file就是 PdfFile类型，达到了类型转换在抽离到独立方法后，参数类型依然可以向下传递的作用，让代码更加地趋向了自然语言，提高代码的可读性和编码的便利性。

同时需要给调用的方法上也加上注解@ExperimentalContracts，这时候又可以愉快的进行自动类型转换了：Smart cast to PdfFile。

@ExperimentalContracts
    fun move2(file: File) {
        if (isPDF(file)) {
            //Smart cast to PdfFile
            file.convertToWord()
        }
    }

看一下字节码对应的java代码，其实就是编译器根据contract提供的约定条件进行强制类型转换：

@ExperimentalContracts
   public static final void move2(@NotNull File file) {
      Intrinsics.checkNotNullParameter(file, "file");
      if (isPDF(file)) {
          //编译器根据contract提供的约定条件进行强制类型转换
         ((PdfFile)file).convertToWord();
      }
   }

3.2、根据执行次数约定

常用的kotlin方法apply中就使用了contract中的callsInPlace约定，标识该lambda只会执行一次。

@kotlin.internal.InlineOnly
    public inline fun <T> T.apply(block: T.() -> Unit): T {
        contract {
            callsInPlace(block, InvocationKind.EXACTLY_ONCE)
        }
        block()
        return this
    }

编译器通过该 contract 得以知道扩展方法 block 的被执行次数的情况。

/**
     * Specifies that the function parameter [lambda] is invoked in place.
     *
     * This contract specifies that:
     * 1. the function [lambda] can only be invoked during the call of the owner function,
     *  and it won't be invoked after that owner function call is completed;
     * 2. _(optionally)_ the function [lambda] is invoked the number of times specified by the [kind] parameter,
     *  see the [InvocationKind] enum for possible values.
     *
     * A function declaring the `callsInPlace` effect must be _inline_.
     *
     */
    @ContractsDsl public fun <R> callsInPlace(lambda: Function<R>, kind: InvocationKind = InvocationKind.UNKNOWN): CallsInPlace

InvocationKind有四种类：AT_MOST_ONCE、AT_LEAST_ONCE、EXACTLY_ONCE、UNKNOWN。

public enum class InvocationKind {
        /**
         * 最多执行一次
         */
        @ContractsDsl AT_MOST_ONCE,
    
        /**
         * 至少执行一次
         */
        @ContractsDsl AT_LEAST_ONCE,
    
        /**
         * 只执行一次
         */
        @ContractsDsl EXACTLY_ONCE,
    
        /**
         * 未知、默认值
         */
        @ContractsDsl UNKNOWN
    }

同样的再举个例子，方便理解callsInPlace的效果。定义了一个方法，接受一个lambda表达式作为参数

fun init(block: () -> Unit) {
        block()
    }

当借助该方法初始化值时，编译器会报错，因为后续用到了这个值，编译器不知道有没有初始化：Variable 'data' must be initialized。

fun test() {
        var data: String
        
        //初始化放到lambda中执行
        init {
            data = ""
        }
        
        //编译器无法知道是否成功执行初始化
        data.length
    }

这时候就需要用到约定，告诉编译器，该lambda至少会执行一次，相应的变量一定会初始化。

@ExperimentalContracts
    fun init(block: () -> Unit) {
        contract {
            callsInPlace(block, InvocationKind.EXACTLY_ONCE)
        }
        block()
    }

给调用的方法也加上@ExperimentalContracts注解，编译器就知道block初始化快会执行一次这个约定，后续再访问data变量就知道已经初始化过了。

@ExperimentalContracts
    fun test() {
        var data: String
        init {
            data = ""
        }
        data.length
    }

由于是人为的约定，编译器也会无条件相信并执行这些约定。所以对开发的水平有要求，不能马虎，约定的场景不能存在漏洞，否则执行过程中会出现异常。