# Lambda 表达式

Source: https://codewiki.com/zh/kotlin/lambdas/

> - **what**: Lambda 表达式是没有声明名称的函数字面量，可以保存到变量、传给函数或由函数返回；函数类型规定它接收什么、返回什么。
> - **trap**: Lambda 可以共享捕获的可变变量，而裸 `return` 的目标又取决于调用是否内联；这两处最容易让短代码产生隐藏控制流。
> - **fix**: 写出清楚的函数类型和参数名，明确捕获状态的所有者，并用带标签返回、普通循环或具名函数表达控制流。

## 是什么，为什么存在

Lambda 表达式（lambda expression）是用花括号写出的函数字面量。它没有声明名称，却能生成一个可以调用的值。Kotlin 把函数作为一等函数（first-class function）处理，因此这个值可以存入属性和集合、作为实参传递，也可以由另一个函数返回。

函数类型（function type）描述这个值的调用契约。`(Order) -> Boolean` 接收一个 `Order` 并返回 `Boolean`，`() -> Unit` 不接收参数且只产生副作用，`suspend (Request) -> Response` 则表示可挂起调用。静态类型让高阶函数能够接收行为，同时让编译器检查参数与结果。

Lambda 解决的是“把一段行为交给另一段代码”的问题。集合操作用它定义筛选与转换规则，事件 API 用它保存回调，资源函数用它包住一段受控操作，构建器用它提供局部配置语法。行为只用一次或紧邻调用点时，lambda 通常比单独声明函数更紧凑。

Lambda 并不自动带来纯函数、惰性求值、并发安全或更高性能。它只是一种函数值写法；是否立即调用、调用几次、在哪个线程调用、能否保存，以及异常由谁处理，都由接收它的 API 决定。阅读调用点时，函数参数的契约比花括号本身更重要。

## 工作原理

### 函数类型规定调用形状

普通函数类型写成 `(P1, P2) -> R`。参数类型位于箭头左侧，结果类型位于右侧；参数名称可以写进类型中帮助阅读和 IDE 提示，但不影响类型兼容性。函数类型本身可空时必须加括号，例如 `((String) -> Int)?`，这与返回可空值的 `(String) -> Int?` 不同。

带接收者的函数类型在参数列表前增加接收者，例如 `ReceiptBuilder.() -> Unit`。调用这种值时要提供一个 `ReceiptBuilder`；lambda 体内，该对象成为隐式 `this`。可挂起函数类型带有 `suspend`，只能在允许挂起调用的上下文中执行。

常见形状如下：

| 类型 | 含义 | 典型用途 |
| --- | --- | --- |
| `() -> Unit` | 无参数操作 | 完成回调 |
| `(T) -> Boolean` | 接收一个值并作判断 | 谓词与筛选 |
| `(T) -> R` | 把一种值转换成另一种值 | 映射与适配 |
| `A.(B) -> C` | 在 `A` 接收者上接收 `B` 并返回 `C` | 构建器与领域 API |
| `suspend () -> T` | 可调用挂起函数并返回 `T` | 协程任务 |

函数参数具有逆变方向，结果具有协变方向。能处理任意 `Number` 并返回 `String` 的函数，也能放到只会传入 `Int`、只要求得到 `Any` 的位置。判断兼容性时，要问候选函数能否接住调用方可能传入的每个值，以及它的结果是否满足调用方承诺的类型。

### 预期类型驱动推断

Lambda 的完整形状是 `{ 参数 -> 函数体 }`，最后一个表达式成为结果。若赋值目标或函数形参已经给出预期类型，参数类型通常可以省略。只有一个可推断参数时，还可以省略参数列表与箭头，并用隐式名称 `it`。

推断需要上下文。单独写 `{ value -> value.length }` 时，编译器不知道 `value` 的类型；把它赋给 `(String) -> Int`，或传给形参类型明确的函数后，`String` 才能确定。重载让预期类型不唯一时，应写出变量类型、参数类型或具名实参，缩小解析空间。

Lambda、匿名函数和函数引用都能产生函数类型值。`::parseRecord` 引用已有函数，`parser::parse` 把接收者绑定到特定对象，`Record::id` 可以把属性读取当作函数传递。已有声明正好表达意图时，函数引用能保留名称；需要捕获局部配置或组合几步操作时，lambda 更直接。

### 调用与尾随 lambda

函数值可用普通调用语法 `predicate(order)` 执行，也可以显式写成 `predicate.invoke(order)`。前一种更像普通函数，通常更易读。调用方无法仅凭语法知道实现来自 lambda、匿名函数、函数引用还是实现了调用约定的对象。

当函数的最后一个形参是函数类型时，对应的 lambda 实参可以移到圆括号外，这叫尾随 lambda（trailing lambda）。如果它是唯一实参，圆括号也可以省略。该规则只改变调用语法，不改变参数顺序，也不会自动把任何花括号变成异步任务或新的语言结构。

尾随位置始终对应最后一个形参。一个 API 若有多个函数形参且都带默认值，`load { handle() }` 可能绑定到最后的失败回调，而不是前面的成功回调。此类调用应写具名实参，让回调角色在源码中可见。

### 捕获形成闭包

Lambda 可以访问定义位置可见的局部变量。函数值与这些外部绑定共同形成闭包（closure）。Kotlin 允许 lambda 读取并修改捕获的 `var`，所以同一作用域创建的多个 lambda 可能共享一份不断变化的状态。

捕获不是并发原语。多个线程调用同一个闭包时，普通 `var` 的读写不会因此变成原子操作，也不会自动建立可见性保证。跨线程保存回调时，状态应由锁、原子类型、消息传递或单线程所有权保护，而不是依赖 lambda 的简短外观。

长期保存的 lambda 还会延长其捕获对象的可达时间。只需要请求 ID 的监听器若捕获整个请求上下文，就可能连带保留缓存、缓冲区或服务引用。先提取所需的小型稳定值，再创建长期回调，可以让生命周期边界更清楚。

### 接收者与 SAM 是两种契约

带接收者的 lambda（lambda with receiver）把一个对象作为隐式 `this`，适合表达层级构建或在受限对象上执行一组操作。它仍是普通函数值，不会增加解析器，也不会自动限制嵌套接收者。复杂 DSL 的作用域控制属于 `@DslMarker` 与专门的 DSL 设计。

函数式接口（functional interface）使用 `fun interface` 声明，并且只有一个抽象方法。SAM 转换（SAM conversion）可以把签名匹配的 lambda 转成这种名义接口的实例；Kotlin/JVM 也支持 Java 单抽象方法接口。接口可以拥有名称、非抽象成员和独立扩展，普通函数类型则只表达输入与结果。

若 API 只需要调用某段行为，优先使用函数类型，必要时用 `typealias` 提供领域名称。若调用方必须承诺一个有身份的领域角色，或契约还包含其他成员，`fun interface` 更合适。两者看起来都能接收 lambda，但它们不是可随意互换的 API 边界。

## 示例

下面四个程序分别展示函数类型、闭包状态、接收者和返回控制。它们都是独立文件，已使用 Kotlin 2.4.10 编译器编译，并在 JRE 21 上运行；紧随代码的输出来自实际执行。

### 把筛选规则作为值传递

第一个程序声明一个明确的谓词类型，并把同一个高阶函数分别与变量 lambda 和尾随 lambda 一起使用。`Order::id` 则把属性引用作为映射函数。

<!-- quick -->

```kotlin
// file: order_filters.kt
data class Order(val id: String, val total: Int, val paid: Boolean)

fun selectIds(
    orders: List<Order>,
    predicate: (Order) -> Boolean,
): List<String> = orders.filter(predicate).map(Order::id)

fun main() {
    val orders = listOf(
        Order("A-101", 40, true),
        Order("A-102", 120, false),
        Order("A-103", 180, true),
    )

    // 预期类型让 order 被推断为 Order。
    val expensive: (Order) -> Boolean = { order -> order.total >= 100 }

    println(selectIds(orders, expensive))
    println(selectIds(orders) { it.paid })
}
```

```text
[A-102, A-103]
[A-101, A-103]
```

<!-- /quick -->

`selectIds` 决定何时以及对哪些元素调用谓词；lambda 只提供判断规则。第一处调用把函数值放在圆括号内，第二处把最后一个 lambda 移到括号外，两者传递的是同一种 `(Order) -> Boolean` 契约。

属性引用 `Order::id` 的形状可视为 `(Order) -> String`。它接收一个未绑定的 `Order`，返回该实例的 `id`。如果改为 `orders.first()::id`，得到的是已绑定属性引用，不再需要 `Order` 参数。

### 每个工厂调用拥有独立状态

第二个程序返回捕获 `next` 的函数。两次调用 `ticketSequence` 会创建两份状态，而给同一函数值增加别名不会复制状态。

```kotlin
// file: ticket_sequences.kt
fun ticketSequence(prefix: String): () -> String {
    var next = 1
    return { "$prefix-${next++}" }
}

fun main() {
    val web = ticketSequence("WEB")
    val batch = ticketSequence("BATCH")

    println(listOf(web(), web(), batch(), web(), batch()))

    // 别名仍指向同一个闭包。
    val sameWeb = web
    println(sameWeb())
}
```

```text
[WEB-1, WEB-2, BATCH-1, WEB-3, BATCH-2]
WEB-4
```

`web` 与 `batch` 来自不同工厂调用，因此各自从 `1` 开始。`sameWeb` 只是复制函数值引用；它调用后得到 `WEB-4`，证明它与 `web` 操作同一个捕获状态。

这种小型状态机适合只有一个操作的接口。若状态需要重置、检查、持久化或并发控制，带明确方法和所有权的类通常更容易维护。函数值隐藏了状态表示，却没有消除状态设计。

### 用接收者限定配置词汇

第三个程序接收 `ReceiptBuilder.() -> Unit`。调用块中的 `item` 会解析到隐式 `ReceiptBuilder` 接收者，入口函数则负责创建、调用并最终构建结果。

```kotlin
// file: receipt_builder.kt
class ReceiptBuilder {
    private val lines = mutableListOf<String>()

    fun item(name: String, cents: Int) {
        require(name.isNotBlank()) { "name must not be blank" }
        require(cents > 0) { "cents must be positive" }
        lines += "$name=${cents}c"
    }

    fun build(): String = lines.joinToString("|")
}

fun receipt(block: ReceiptBuilder.() -> Unit): String {
    val builder = ReceiptBuilder()
    builder.block()
    return builder.build()
}

fun main() {
    val summary = receipt {
        item("coffee", 450)
        item("cake", 325)
    }

    println(summary)
}
```

```text
coffee=450c|cake=325c
```

`builder.block()` 同时完成两件事：调用函数值，并把 `builder` 作为接收者提供给它。也可以把接收者函数值写成 `block(builder)` 调用，但点号形式更能显出接收者关系。

块内简洁的调用来自静态接收者类型，不是任意名称查找。公开给 `ReceiptBuilder` 的成员都会成为块内词汇，因此构建器应保持狭窄，并在返回最终结果前完成校验和所有权转换。

### 区分非局部返回与带标签返回

第四个程序展示两种不同目标。传给内联 `forEach` 的裸 `return` 会从 `firstReady` 返回；`return@transform` 只结束本次 `mapNotNull` 调用。

```kotlin
// file: return_targets.kt
fun firstReady(records: List<String>): String? {
    records.forEach { record ->
        if (record.startsWith("ready:")) {
            // forEach 是内联函数，因此这里返回 firstReady。
            return record.removePrefix("ready:").trim()
        }
    }
    return null
}

fun normalized(records: List<String>): List<String> =
    records.mapNotNull transform@{ record ->
        val value = record.substringAfter(':', missingDelimiterValue = "")
        // 带标签返回只跳过当前元素。
        if (value.isBlank()) return@transform null
        value.trim().uppercase()
    }

fun main() {
    val records = listOf("skip", "ready: alpha", "ready: beta", "bad:")

    println(firstReady(records))
    println(normalized(records))
}
```

```text
alpha
[ALPHA, BETA]
```

裸 `return` 能穿过 `forEach`，是因为标准库在调用点内联了这个 lambda。把同样的 lambda 传给普通非内联函数会编译失败；编译器不能让稍后保存或间接调用的回调返回一个已经不存在的调用帧。

`return@transform null` 的目标由显式标签确定。使用调用名称的隐式标签 `return@mapNotNull` 也可行，但在嵌套调用或同名函数较多时，显式标签更易审查。只需要提前结束遍历时，普通 `for` 循环往往最直接。

## 陷阱

> **陷阱:** 把 lambda 中的裸 `return` 一律理解为“只返回 lambda”，会导致提前退出外层函数；反过来，把它放进普通回调又可能直接编译失败。

**修复方法：** 先确认接收函数是否内联以及 lambda 是否可非局部返回。只结束本次 lambda 调用时使用 `return@label`，局部返回逻辑复杂时使用匿名函数，只想结束遍历时考虑普通循环。不要仅凭 `forEach` 看起来像循环就猜测控制流。

> **陷阱:** 嵌套 lambda 都使用 `it` 时，内层参数会遮蔽外层参数，生成代码很容易对错对象读取属性或执行更新。

**修复方法：** 嵌套后立即给参数命名，例如 `order` 与 `lineItem`。单参数、单表达式且含义显然时再使用 `it`。审查时逐个标出每个名称的静态类型，而不是从属性名推测它指向谁。

> **陷阱:** 多个监听器捕获同一个可变变量时，它们共享的是状态，不是创建时的独立快照；并发调用还可能丢失更新。

**修复方法：** 需要独立状态时，为每个所有者调用一次工厂；需要快照时，先复制出本轮不可变值；有意跨线程共享时，明确同步策略。用交错调用和并发测试验证所有权，不要只逐个调用每个回调一次。

> **陷阱:** 多个函数形参都带默认值时，尾随 lambda 绑定最后一个形参，可能让本来表示成功处理的代码进入失败处理位置。

**修复方法：** 对角色不同的回调写具名实参，例如 `onSuccess = { ... }` 与 `onFailure = { ... }`。设计新 API 时，避免让多个同形状回调仅靠位置区分；名义接口或事件对象可以让含义进入类型和名称。

> **陷阱:** 把函数类型、`typealias` 与 `fun interface` 当成同一个类型，会破坏重载、扩展或 Java 互操作边界。

**修复方法：** 只描述调用形状时使用函数类型；`typealias` 仅提供别名，不创建新类型；需要名义身份或额外成员时使用函数式接口。修改公开 API 前，同时编译 Kotlin 与 Java 调用方，而不是只看 lambda 调用是否仍然简短。

<!-- deep -->

## 函数值的运行时边界

### 源码契约与 JVM 表示

在源码层面，函数类型的核心契约是参数、接收者、结果以及是否可挂起。Kotlin/JVM 使用 `FunctionN` 家族所代表的调用约定承载普通函数值，并通过 `invoke` 执行。具体生成类的名称、是否复用无捕获实例，以及某个调用是否仍保留对象，都属于编译器和后端细节。

因此，不要用 lambda 的运行时类名、对象身份或 `toString()` 结果建立业务规则。一次编译可能把调用内联掉，另一次可能为捕获状态创建对象，函数引用和 SAM 实例又有不同表示。需要稳定身份时，应在领域对象上定义键，而不是比较两个看起来相同的 lambda。

捕获的 `var` 必须让 lambda 与外层代码观察到一致更新。在 JVM 上，编译器可以为这种可变捕获安排共享存储；这不等于语言承诺了某个可反射的包装类名称。诊断生成物时可以使用 `javap`，生产代码则应只依赖源码级闭包语义。

### 内联改变可用控制流

`inline` 会请求编译器把函数体及可内联 lambda 展开到调用点。它既可能避免函数对象与间接调用，也会让 lambda 中的裸 `return` 能够退出外层函数。没有实测数据时，不应把内联写成无条件的性能优化；代码体积、调用形状和后端优化都会影响结果。

可内联参数不能逃逸：不能保存到字段、作为普通值返回，或捕获到稍后运行的对象中。确实需要保存某个参数时使用 `noinline`，它恢复普通函数值的用法。需要在另一个执行上下文调用、但仍希望内联其代码时使用 `crossinline`；代价是调用方不能再执行非局部返回。

公开内联函数的实现会进入调用方产物。库升级后，如果调用方没有重新编译，旧调用点仍携带旧实现。公共 API 的内联函数还受可见性限制，因为调用方模块不能直接引用库的私有实现细节；稳定的库边界需要把这一点纳入兼容性审查。

### 函数引用不等于普通 lambda

函数引用使用 `::` 指向已有声明，并且可作为匹配的函数类型调用。未绑定成员引用把接收者放进参数列表，例如 `Regex::matches` 需要一个 `Regex`；绑定引用 `numberRegex::matches` 已携带接收者，因此只需要待匹配的字符序列。

可调用引用还属于反射类型层级，可公开名称等声明信息；普通 lambda 没有对应的源码声明名称。只为调用行为编写 API 时，应接收函数类型，而不是无故要求 `KFunction`。只有确实需要检查声明元数据时，反射类型才是合适边界，并且 JVM 完整反射能力可能需要 `kotlin-reflect` 依赖。

## 设计可审查的回调 API

### 把调用时机写进契约

`() -> Unit` 只说明如何调用，没有说明何时调用。回调 API 还应记录它是同步还是异步、最多调用一次还是可以重复调用、由哪个线程或调度器调用、异常向哪里传播，以及调用方能否在返回后继续持有它。这些事实决定捕获对象的生命周期和允许的控制流。

同步且恰好一次调用的操作，可以直接返回 lambda 的结果，让异常按普通调用栈传播。长期监听器通常需要返回取消句柄，或接收明确的注册令牌，帮助调用方解除引用。把回调保存在集合中却没有注销路径，会把闭包捕获的对象一起变成长生命周期状态。

若回调允许缺省，`(() -> Unit)?` 与默认空 lambda 表达不同语义。可空值能区分“没有订阅者”，默认空实现则把缺席变成一次什么也不做的调用。选择应由领域是否需要观察缺席状态决定，不能只为了少写一次空检查。

### 让角色区别进入名称

两个参数都是 `(Result) -> Unit` 时，类型检查无法阻止调用方交换它们。具名实参能改善调用点，但函数引用或 Java 调用方可能仍依赖位置。若角色具有不同数据或生命周期，应使用不同结果类型、密封事件或带名称的方法，而不是继续堆叠同形状函数。

`typealias` 可以把 `(Order) -> Boolean` 命名为 `OrderRule`，提高签名可读性，但别名仍与原函数类型赋值兼容。`fun interface OrderRule` 才创建独立名义类型，也可以携带文档与非抽象成员。选择名义边界的理由应是契约，而不是只为获得 SAM 构造语法。

需要挂起调用时，把 `suspend` 放进函数类型，让约束进入编译器。不要接收普通回调后在内部偷偷创建无所有者协程；这会分离完成、取消和异常传播。结构化并发的具体所有权规则属于协程主题，但函数签名应先准确表达能否挂起。

## 验证函数边界

### 编译失败也是证据

函数类型的大量错误本应由编译器阻止。测试一个回调 API 时，除了运行成功路径，还应保留预期无法编译的调用，例如把普通函数值传到 `suspend` 位置、从非内联 lambda 裸返回，或交换不兼容的输入类型。编译测试能证明边界确实由类型系统承担，而不是只存在于文档中。

只编译正向示例无法证明错误调用会被拒绝。项目可以把负向源码放进专门的编译测试，断言失败阶段与关键诊断；升级 Kotlin 时再检查诊断意图，而不要过度绑定完整错误文本。对于公开库，还应从独立模块编译调用方，避免同模块可见性掩盖边界。

运行期测试负责类型无法表达的事实。回调是否恰好调用一次、是否按注册顺序执行、抛出的异常是否传播、取消后是否解除捕获引用，都必须通过行为测试验证。若 API 允许异步调用，测试还要控制调度，不能依赖偶然的线程时序。

一组紧凑的验证矩阵如下：

| 边界 | 正向检查 | 负向或边界检查 |
| --- | --- | --- |
| 参数与结果类型 | 匹配的 lambda 能编译并返回预期值 | 不兼容类型被编译器拒绝 |
| 调用次数 | 记录每次参数与结果 | 零次、重复调用符合契约 |
| 返回目标 | 标签只结束当前调用 | 裸返回不会越过错误边界 |
| 捕获所有权 | 独立工厂拥有独立状态 | 交错调用不发生状态串扰 |
| 生命周期 | 注销后不再调用 | 长期注册不会意外保留所有者 |

### 测试替身要保留时序

函数类型很容易用 lambda 充当测试替身，但过于简单的替身会隐藏真实约束。生产回调可能重复调用、延迟调用或抛出异常，而测试替身若只立即返回常量，就无法暴露共享状态与生命周期问题。替身应模拟与当前需求有关的调用次数、顺序和失败方式。

记录型 lambda 可以把收到的参数追加到测试拥有的列表，再由断言检查顺序。若生产 API 可能并发执行，普通可变列表本身又会产生竞态，应改用线程安全记录器或受控调度器。测试工具的状态所有权必须比被测代码更清楚。

需要确认捕获对象能够释放时，可以在 JVM 测试中使用弱引用与有界等待作为辅助信号，但垃圾回收时机不是确定契约。更可靠的主断言是注销后注册表不再持有回调，并且后续事件不会触发它。弱引用只用于发现遗漏引用链，不应成为唯一证据。

## 在 lambda 与具名声明之间选择

lambda 最适合短小、局部且只在一个调用点有意义的行为。逻辑出现多个分支、需要独立单元测试、在多处复用，或其名称能表达重要领域规则时，提取为具名函数通常更清楚。判断标准是所有权与可读性，不是行数的固定阈值。

函数引用让具名函数重新进入高阶 API，因此提取并不会失去组合能力。`orders.filter(::isBillable)` 同时保留领域名称与函数类型检查。若引用发生重载歧义，可以先赋给带显式类型的变量，让预期类型选择正确声明。

匿名函数处在两者之间：它没有持久名称，却能显式写返回类型，并让裸 `return` 只返回匿名函数自身。只有返回规则确实比 lambda 标签更清楚时才使用它。尾随 lambda 语法不适用于匿名函数，因此调用形式也会变化。

不要为了“函数式风格”把清楚的循环强行改成一串高阶调用。需要 `break`、多处 `continue`、累积多种状态或精确控制异常边界时，普通循环往往更直接。函数值的价值在于表达行为边界，而不是消除每一个控制结构。

### 保持失败所有权可见

回调抛出异常时，接收方必须选择传播、转换、记录或隔离，不能因为调用写成 lambda 就忽略这项责任。调用方也不应假定异常总会回到注册位置；异步或长期保存的回调需要由执行它的组件定义失败通道，并用测试证明该通道有效。

<!-- /deep -->

[检查点: kotlin/lambdas](https://codewiki.com/zh/kotlin/lambdas/#checkpoint)

## 延伸阅读

以下链接指向 Kotlin 官方文档的源文件。它们分别覆盖函数类型与 lambda 语法、内联与非局部控制流、函数式接口及 SAM 转换，以及函数引用。

- [Kotlin 高阶函数与 lambda 文档源文件](https://raw.githubusercontent.com/JetBrains/kotlin-web-site/master/docs/topics/lambdas.md)
- [Kotlin 内联函数文档源文件](https://raw.githubusercontent.com/JetBrains/kotlin-web-site/master/docs/topics/inline-functions.md)
- [Kotlin 函数式接口文档源文件](https://raw.githubusercontent.com/JetBrains/kotlin-web-site/master/docs/topics/fun-interfaces.md)
- [Kotlin 函数引用文档源文件](https://raw.githubusercontent.com/JetBrains/kotlin-web-site/master/docs/topics/reflection.md)