Kotlin Flows中single()与first()的区别及适用场景示例

核心行为差异 #

• 元素数量校验规则不同
  • single()：严格要求Flow必须恰好发射一个元素。如果Flow为空（没发射任何元素），会抛出NoSuchElementException；如果Flow发射了两个及以上元素，会抛出IllegalArgumentException。简单说就是“不多不少，只能一个”。
  • first()：只要求Flow至少发射一个元素，拿到第一个元素后就立刻取消收集，完全不管后续有没有更多元素。只有当Flow为空时才会抛出NoSuchElementException，元素多了不会报错。

代码示例：single()的行为 #

import kotlinx.coroutines.*
import kotlinx.coroutines.flow.*

fun main() = runBlocking {
    // 正常情况：恰好一个元素
    val singleValidFlow = flow { emit("唯一数据") }
    println(singleValidFlow.single()) // 输出：唯一数据

    // 异常情况1：无元素
    val emptyFlow = flow<Nothing> {}
    try {
        emptyFlow.single()
    } catch (e: NoSuchElementException) {
        println("捕获异常：${e.message}") // 输出：Flow has no elements
    }

    // 异常情况2：多个元素
    val multiFlow = flow {
        emit("数据1")
        emit("数据2")
    }
    try {
        multiFlow.single()
    } catch (e: IllegalArgumentException) {
        println("捕获异常：${e.message}") // 输出：Flow has more than one element
    }
}

代码示例：first()的行为 #

import kotlinx.coroutines.*
import kotlinx.coroutines.flow.*

fun main() = runBlocking {
    // 正常情况1：一个元素
    val singleFlow = flow { emit("第一条数据") }
    println(singleFlow.first()) // 输出：第一条数据

    // 正常情况2：多个元素，仅取第一个
    val multiFlow = flow {
        emit("数据1")
        emit("数据2")
        emit("数据3")
    }
    println(multiFlow.first()) // 输出：数据1

    // 异常情况：无元素
    val emptyFlow = flow<Nothing> {}
    try {
        emptyFlow.first()
    } catch (e: NoSuchElementException) {
        println("捕获异常：${e.message}") // 输出：Flow has no elements
    }
}

适用场景 #

• single()的适用场景
  当你明确知道Flow只会产生一个且仅一个结果时使用，它相当于一个校验器，确保数据流符合预期，避免后续逻辑处理错误的数据。比如：

  • 根据唯一ID从数据库查询单条记录（比如用户详情、订单详情）
  • 网络请求返回单个实体（比如获取当前登录用户信息）
  • 状态流中确保只有初始状态的单次发射

  示例代码：

  // 模拟根据ID查询唯一用户
  fun getUserById(userId: String): Flow<User> = flow {
      // 数据库逻辑：ID唯一，最多返回一个用户
      val user = User(userId, "张三")
      emit(user)
  }
  
  runBlocking {
      val user = getUserById("1001").single()
      println("获取到用户：${user.name}")
      // 后续处理用户信息
  }
  
  data class User(val id: String, val name: String)
  

• first()的适用场景
  当你只关心Flow的第一个元素，不需要处理后续发射的数据时使用。比如：

  • 监听UI事件，只处理第一次触发（比如首次点击按钮、首次进入页面的初始化请求）
  • 从持续发射的数据流中获取初始状态（比如状态流的第一个值用于页面初始化）
  • 批量数据流中仅需要第一条记录（比如日志流中取最新的一条日志）

  示例代码：

  // 模拟按钮点击事件流，只处理第一次点击
  val buttonClickFlow = flow {
      var count = 0
      while (true) {
          delay(1000)
          count++
          emit("第$count次点击")
      }
  }
  
  runBlocking {
      val firstClick = buttonClickFlow.first()
      println("处理第一次点击：$firstClick") // 输出：处理第一次点击：第1次点击
      // 后续只执行第一次点击的逻辑
  }
  

内容的提问来源于stack exchange，提问作者Daniel Weidensdörfer