契约 API (Contract) Standard

源：Kotlin 契约提案

契约如同给编译器看的“说明书”，告知其某些隐含的逻辑（如：如果返回 true，则参数一定不为 null；或者 Lambda 一定会被执行一次）。

核心能力

需要 OptIn: @OptIn(ExperimentalContracts::class)

1. 智能转换 (implies)

fun isString(o: Any?): Boolean {
    contract {
        returns(true) implies (o is String)
    }
    return o is String
}

fun test(obj: Any?) {
    if (isString(obj)) {
        // 编译器现在知道 obj 是 String
        println(obj.length) 
    }
}

2. 初始化保证 (callsInPlace)

告知编译器 Lambda 的执行频率，从而允许在 Lambda 内部初始化本地变量。

inline fun synchronizedRun(lock: Any, block: () -> Unit) {
    contract {
        // 保证 block 执行且仅执行一次
        callsInPlace(block, InvocationKind.EXACTLY_ONCE)
    }
    synchronized(lock) { block() }
}

fun main() {
    val x: Int
    synchronizedRun(lock) {
        x = 42 // ✅ 如果没有契约，编译器会报错 "x 未初始化"
    }
    println(x)
}