Flow基础使用
这里是基础代码
interface FlowDemo {
val level: FlowDemoLevel
val title: String
val summary: String
val sourceTrace: String
suspend fun run(log: suspend (String) -> Unit)
}
冷流 Flow + colloct
object ColdFlowBuilderDemo : FlowDemo {
override val level = FlowDemoLevel.Basic
override val title = "冷流 flow + collect"
override val summary = "无 collect 不执行;每次 collect 都会重新跑 flow builder。"
override val sourceTrace = """
特性:冷流;默认无缓冲,emit 会挂起直到下游 collect 处理完当前值。
源码(kotlinx-coroutines 1.9.0):
- kotlinx-coroutines-core/common/src/flow/Builders.kt
— flow、SafeFlow
- kotlinx-coroutines-core/common/src/flow/Flow.kt
— AbstractFlow.collect(上下文检查后调用 collectSafely)
- kotlinx-coroutines-core/common/src/flow/FlowCollector.kt
— emit
""".trimIndent()
override suspend fun run(log: suspend (String) -> Unit) {
val numbers = flow {
log("builder 开始")
emit(1)
emit(2)
log("builder 结束")
}
log("已创建同一个 Flow 实例,但还没有 collect,builder 不会执行")
log("—— 第 1 次 collect ——")
numbers.collect { value ->
log("第 1 次收到 $value")
delay(40)
}
log("—— 第 2 次 collect ——")
numbers.collect { value ->
log("第 2 次收到 $value")
delay(40)
}
}
}
输出结果
已创建同一个 Flow 实例,但还没有 collect,builder 不会执行
—— 第 1 次 collect ——
builder 开始
第 1 次收到 1
第 1 次收到 2
builder 结束
—— 第 2 次 collect ——
builder 开始
第 2 次收到 1
第 2 次收到 2
builder 结束
flowOf 与 asFlow
object FlowOfAsFlowDemo : FlowDemo {
override val level = FlowDemoLevel.Basic
override val title = "flowOf 与 asFlow"
override val summary = "固定元素的冷流简写:flowOf 与 Iterable.asFlow。"
override val sourceTrace = """
特性:仍是冷流,只是用已有数据包装成 flow builder 的简写。
源码(kotlinx-coroutines 1.9.0):
- kotlinx-coroutines-core/common/src/flow/Builders.kt
— flowOf、Iterable.asFlow
""".trimIndent()
override suspend fun run(log: suspend (String) -> Unit) {
log("flowOf(1, 2, 3) collect:")
flowOf(1, 2, 3).collect { log(" 收到 $it") }
log("listOf("a", "b").asFlow() collect:")
listOf("a", "b").asFlow().collect { log(" 收到 "$it"") }
}
}
结果输出
flowOf(1, 2, 3) collect:
收到 1
收到 2
收到 3
listOf("a", "b").asFlow() collect:
收到 "a"
收到 "b"
map 与 filter
object FlowOfAsFlowDemo : FlowDemo {
override val level = FlowDemoLevel.Basic
override val title = "flowOf 与 asFlow"
override val summary = "固定元素的冷流简写:flowOf 与 Iterable.asFlow。"
override val sourceTrace = """
特性:仍是冷流,只是用已有数据包装成 flow builder 的简写。
源码(kotlinx-coroutines 1.9.0):
- kotlinx-coroutines
-core/common/src/flow/Builders.kt
— flowOf、Iterable.asFlow
""".trimIndent()
override suspend fun run(log: suspend (String) -> Unit) {
log("flowOf(1, 2, 3) collect:")
flowOf(1, 2, 3).collect { log(" 收到 $it") }
log("listOf("a", "b").asFlow() collect:")
listOf("a", "b").asFlow().collect { log(" 收到 "$it"") }
}
}
结果输出
flowOf(1..4).filter(偶数).map(*10) collect:
收到 20
收到 40
终端操作符 first / toList / fold
object TerminalOperatorsDemo : FlowDemo {
override val level = FlowDemoLevel.Basic
override val title = "终端操作符 first / toList / fold"
override val summary = "终端操作符内部会 collect;first 取首值后提前结束上游。"
override val sourceTrace = """
特性:终端操作符内部 collect;first 拿到第一个值后抛出内部 AbortFlowException 提前结束上游,用户代码不要 catch 它。
源码(kotlinx-coroutines 1.9.0):
- kotlinx-coroutines-core/common/src/flow/terminal/Reduce.kt
— first、toList、fold
- kotlinx-coroutines
-core/common/src/flow/internal/FlowExceptions.common.kt
— AbortFlowException
""".trimIndent()
override suspend fun run(log: suspend (String) -> Unit) {
val source = flowOf(1, 2, 3, 4)
log("first() = ${source.first()}")
log("toList() = ${source.toList()}")
log("fold(0, +) = ${source.fold(0) { acc, value -> acc + value }}")
log("同一个冷流实例被三个终端操作符各 collect 了一次")
}
}
结果输出
first() = 1
toList() = [1, 2, 3, 4]
fold(0, +) = 10
同一个冷流实例被三个终端操作符各 collect 了一次
take 与 drop
object TakeDropDemo : FlowDemo {
override val level = FlowDemoLevel.Basic
override val title = "take 与 drop"
override val summary = "drop 跳过前 n 个;take 满额后取消上游,后面的 emit 不再继续。"
override val sourceTrace = """
特性:take 达到数量后会取消上游;drop 先丢弃再向下游传递。
源码(kotlinx-coroutines 1.9.0):
- kotlinx-coroutines-core/common/src/flow/operators/Limit.kt
— drop、take
""".trimIndent()
override suspend fun run(log: suspend (String) -> Unit) {
log("drop(2).take(2),期望下游收到 3、4:")
flow {
for (n in 1..5) {
log(" 上游准备 emit $n")
emit(n)
log(" 上游 emit $n 完成")
}
log(" 上游 builder 正常结束")
}
.drop(2)
.take(2)
.collect { log(" 下游收到 $it") }
}
}
结果输出
drop(2).take(2),期望下游收到 3、4:
上游准备 emit 1
上游 emit 1 完成
上游准备 emit 2
上游 emit 2 完成
上游准备 emit 3
下游收到 3
上游 emit 3 完成
上游准备 emit 4
下游收到 4
zip 与 combine
object ZipCombineDemo : FlowDemo {
override val level = FlowDemoLevel.Basic
override val title = "zip 与 combine"
override val summary = "zip 按序配对且以较短流为准结束;combine 用各流最新值重组。"
override val sourceTrace = """
特性:zip 一对一配对;combine 等各流都有值后发射,之后任一侧更新即再发射一对最新值。
源码(kotlinx-coroutines 1.9.0):
- kotlinx-coroutines-core/common/src/flow/operators/Zip.kt
— zip、combine
""".trimIndent()
override suspend fun run(log: suspend (String) -> Unit) {
log("zip:flowOf(1,2) zip flowOf("a","b","c")")
flowOf(1, 2)
.zip(flowOf("a", "b", "c")) { n, s -> n to s }
.collect { (n, s) -> log(" zip 收到 ($n, "$s")") }
log("combine:两个 MutableStateFlow(均有初值)")
coroutineScope {
val nums = MutableStateFlow(1)
val tags = MutableStateFlow("x")
val job = launch {
combine(nums, tags) { n, t -> n to t }
.collect { (n, t) -> log(" combine 收到 ($n, "$t")") }
} delay(30)
log(" 更新 nums = 2")
nums.value = 2
delay(30)
log(" 更新 tags = "y"")
tags.value = "y"
delay(30)
job.cancel()
}
}
}
结果输出
zip:flowOf(1,2) zip flowOf("a","b","c")
zip 收到 (1, "a")
zip 收到 (2, "b")
combine:两个 MutableStateFlow(均有初值)
combine 收到 (1, "x")
更新 nums = 2
combine 收到 (2, "x")
更新 tags = "y"
combine 收到 (2, "y")
flowOn 切换上游调度器
object FlowContextDemo : FlowDemo {
override val level = FlowDemoLevel.Basic
override val title = "flowOn 切换上游调度器"
override val summary = "flowOn 只影响其上游;collect 仍在调用者协程(如 Main)执行。"
override val sourceTrace = """
特性:flowOn 只改变它上游的协程上下文,不改下游;实现插入 channel,上下游可并发。
源码(kotlinx-coroutines 1.9.0):
- kotlinx-coroutines-core/common/src/flow/operators/Context.kt
— flowOn
""".trimIndent()
override suspend fun run(log: suspend (String) -> Unit) {
flow {
log("上游 collect 线程:${Thread.currentThread().name}")
emit(1)
}
.flowOn(Dispatchers.Default)
.collect { value ->
log("下游 collect 线程:${Thread.currentThread().name},收到 $value")
}
}
}
结果输出
上游 collect 线程:DefaultDispatcher-worker-2
下游 collect 线程:main,收到 1
StateFlow 入门
object StateFlowBasicDemo : FlowDemo {
override val level = FlowDemoLevel.Basic
override val title = "StateFlow 入门"
override val summary = "热流、replay=1、equals 合并相等值、永不 complete。"
override val sourceTrace = """
特性:热流;永不 complete;按 Any.equals 合并连续相等值;新订阅者立刻收到当前值(replay = 1)。
源码(kotlinx-coroutines 1.9.0):
- kotlinx-coroutines-core/common/src/flow/StateFlow.kt
— MutableStateFlow
""".trimIndent()
override suspend fun run(log: suspend (String) -> Unit) {
val state = MutableStateFlow(0)
log("先设置 value = 1(尚未 collect)")
state.value = 1
coroutineScope {
val job = launch {
state.collect { log("StateFlow 收到 $it") }
}
delay(40)
log("再次 value = 1(与当前相等,不应再发射)")
state.value = 1
delay(40)
log("设置 value = 2")
state.value = 2
delay(40)
job.cancel()
}
log("已取消 collect,避免 StateFlow 永不完成")
}
}
结果输出
先设置 value = 1(尚未 collect)
StateFlow 收到 1
再次 value = 1(与当前相等,不应再发射)
设置 value = 2
StateFlow 收到 2
已取消 collect,避免 StateFlow 永不完成
高级用法
buffer 与 conflate
object BufferConflateDemo : FlowDemo {
override val level = FlowDemoLevel.Advanced
override val title = "buffer 与 conflate"
override val summary = "无缓冲时 emit 与 collect 交替;buffer 让上游超前;conflate 只保留最新值。"
override val sourceTrace = """
特性:buffer 用 Channel 解耦上下游;conflate 等价 buffer(Channel.CONFLATED),慢消费者会丢中间值。
BufferOverflow 还有 SUSPEND / DROP_OLDEST / DROP_LATEST(本 demo 主要跑 buffer 与 conflate)。
源码(kotlinx-coroutines 1.9.0):
- kotlinx/coroutines/flow/operators/Context.kt
— buffer、conflate
""".trimIndent()
override suspend fun run(log: suspend (String) -> Unit) {
fun fastZeroToFour(tag: String) = flow {
for (i in 0..4) {
log("[$tag] 上游 emit $i")
emit(i)
}
log("[$tag] 上游 emit 完毕")
}
log("—— 无缓冲:emit 会挂起直到 collect 处理完 ——")
fastZeroToFour("无缓冲").collect { value ->
log("[无缓冲] 下游收到 $value,处理中…")
delay(40)
}
log("—— buffer(2):上游可最多超前 2 个元素 ——")
fastZeroToFour("buffer(2)").buffer(2).collect { value ->
log("[buffer(2)] 下游收到 $value,处理中…")
delay(40)
}
log("—— conflate():处理慢时只保留最新值 ——")
fastZeroToFour("conflate").conflate().collect { value ->
log("[conflate] 下游收到 $value,处理中…")
delay(40)
}
}
}
结果输出
—— 无缓冲:emit 会挂起直到 collect 处理完 ——
[无缓冲] 上游 emit 0
[无缓冲] 下游收到 0,处理中…
[无缓冲] 上游 emit 1
[无缓冲] 下游收到 1,处理中…
[无缓冲] 上游 emit 2
[无缓冲] 下游收到 2,处理中…
[无缓冲] 上游 emit 3
[无缓冲] 下游收到 3,处理中…
[无缓冲] 上游 emit 4
[无缓冲] 下游收到 4,处理中…
[无缓冲] 上游 emit 完毕
—— buffer(2):上游可最多超前 2 个元素 ——
[buffer(2)] 上游 emit 0
[buffer(2)] 上游 emit 1
[buffer(2)] 上游 emit 2
[buffer(2)] 上游 emit 3
[buffer(2)] 下游收到 0,处理中…
[buffer(2)] 下游收到 1,处理中…
[buffer(2)] 上游 emit 4
[buffer(2)] 下游收到 2,处理中…
[buffer(2)] 上游 emit 完毕
[buffer(2)] 下游收到 3,处理中…
[buffer(2)] 下游收到 4,处理中…
—— conflate():处理慢时只保留最新值 ——
[conflate] 上游 emit 0
[conflate] 上游 emit 1
[conflate] 上游 emit 2
[conflate] 上游 emit 3
[conflate] 上游 emit 4
[conflate] 上游 emit 完毕
[conflate] 下游收到 0,处理中…
[conflate] 下游收到 4,处理中…
flatMapConcat / Merge / Latest
object FlatMapDemo : FlowDemo {
override val level = FlowDemoLevel.Advanced
override val title = "flatMapConcat / Merge / Latest"
override val summary = "同一外层流对比三种 flatMap:串行、并发交织、新外层取消旧内层。"
override val sourceTrace = """
特性:flatMapMerge 默认并发度 DEFAULT_CONCURRENCY = 16;flatMapLatest 依赖 transformLatest 取消旧 action。
源码(kotlinx-coroutines 1.9.0):
- kotlinx/coroutines/flow/operators/Merge.kt
— flatMapConcat、flatMapMerge、flatMapLatest
- kotlinx/coroutines/flow/operators/Transform.kt
— transformLatest(flatMapLatest 实现依赖)
""".trimIndent()
override suspend fun run(log: suspend (String) -> Unit) {
fun outerKeys() = flow {
log("外层 emit A")
emit("A")
delay(25)
log("外层 emit B")
emit("B")
}
fun innerFor(key: String) = flow {
log("内层[$key] emit ${key}-1")
emit("${key}-1")
delay(35)
log("内层[$key] emit ${key}-2")
emit("${key}-2")
}
log("—— flatMapConcat:A 的内层全部完成才轮到 B ——")
outerKeys().flatMapConcat { key -> innerFor(key) }.collect { value ->
log("[concat] 收到 $value")
}
log("—— flatMapMerge:内层并发,日志可能交织 ——")
outerKeys().flatMapMerge { key -> innerFor(key) }.collect { value ->
log("[merge] 收到 $value")
}
log("—— flatMapLatest:B 到达时取消 A 的内层,A-2 通常不会出现 ——")
outerKeys().flatMapLatest { key -> innerFor(key) }.collect { value ->
log("[latest] 收到 $value")
}
}
}
结果输出
—— flatMapConcat:A 的内层全部完成才轮到 B ——
外层 emit A
内层[A] emit A-1
[concat] 收到 A-1
内层[A] emit A-2
[concat] 收到 A-2
外层 emit B
内层[B] emit B-1
[concat] 收到 B-1
内层[B] emit B-2
[concat] 收到 B-2
—— flatMapMerge:内层并发,日志可能交织 ——
外层 emit A
内层[A] emit A-1
[merge] 收到 A-1
外层 emit B
内层[B] emit B-1
[merge] 收到 B-1
内层[A] emit A-2
[merge] 收到 A-2
内层[B] emit B-2
[merge] 收到 B-2
—— flatMapLatest:B 到达时取消 A 的内层,A-2 通常不会出现 ——
外层 emit A
内层[A] emit A-1
[latest] 收到 A-1
外层 emit B
内层[B] emit B-1
[latest] 收到 B-1
内层[B] emit B-2
[latest] 收到 B-2
stateln 把冷流变热
object ShareInStateInDemo : FlowDemo {
override val level = FlowDemoLevel.Advanced
override val title = "stateIn 把冷流变热"
override val summary = "冷流每次 collect 重启上游;stateIn 后多收藏者共享,上游只启动一次。"
override val sourceTrace = """
特性:stateIn 得到 StateFlow(replay = 1);SharingStarted 有 Lazily / Eagerly / WhileSubscribed。
源码(kotlinx-coroutines 1.9.0):
- kotlinx/coroutines/flow/operators/Share.kt
— stateIn
- kotlinx/coroutines/flow/SharingStarted.kt
— Lazily、Eagerly、WhileSubscribed
""".trimIndent()
override suspend fun run(log: suspend (String) -> Unit) {
fun coldSource() = flow {
log("上游启动")
emit(1)
delay(40)
emit(2)
}
log("—— 冷流:两次 collect 会两次「上游启动」 ——")
coldSource().take(2).collect { log("冷流收藏 1 收到 $it") }
coldSource().take(2).collect { log("冷流收藏 2 收到 $it") }
log("—— stateIn(Lazily):共享上游,只应出现一次「上游启动」 ——")
coroutineScope {
val hot = coldSource().stateIn(this, SharingStarted.Lazily, initialValue = 0)
val job1 = launch {
hot.take(3).collect { log("热流收藏者 A 收到 $it") }
}
delay(15)
val job2 = launch {
hot.take(2).collect { log("热流收藏者 B 收到 $it") }
}
job1.join()
job2.cancel()
}
log("已结束收藏,避免 StateFlow 永不完成")
}
}
结果输出
—— 冷流:两次 collect 会两次「上游启动」 ——
上游启动
冷流收藏 1 收到 1
冷流收藏 1 收到 2
上游启动
冷流收藏 2 收到 1
冷流收藏 2 收到 2
—— stateIn(Lazily):共享上游,只应出现一次「上游启动」 ——
热流收藏者 A 收到 0
上游启动
热流收藏者 A 收到 1
热流收藏者 B 收到 1
热流收藏者 A 收到 2
热流收藏者 B 收到 2
已结束收藏,避免 StateFlow 永不完成
ShareFlow 的 replay 与 缓冲
object SharedFlowReplayDemo : FlowDemo {
override val level = FlowDemoLevel.Advanced
override val title = "SharedFlow 的 replay 与缓冲"
override val summary = "没有订阅者时 tryEmit 返回 true 但值会被丢掉;replay=1 的新订阅者能拿到最近一条。"
override val sourceTrace = """
特性:热流;emit 挂起,tryEmit 不挂起;新订阅者只拿 replay 缓存,拿不到更早历史。
源码(kotlinx-coroutines 1.9.0):
- kotlinx-coroutines-core/common/src/flow/SharedFlow.kt
— tryEmit 没有订阅者时不使用 extraBufferCapacity,只保留 replay 缓存;replay=0 则值直接丢失,tryEmit 仍返回 true。
""".trimIndent()
override suspend fun run(log: suspend (String) -> Unit) {
coroutineScope {
log("—— replay=0,extraBufferCapacity=1,DROP_OLDEST ——")
val noReplay = MutableSharedFlow<Int>(
replay = 0,
extraBufferCapacity = 1,
onBufferOverflow = BufferOverflow.DROP_OLDEST,
)
val tryOk = noReplay.tryEmit(1)
log("无订阅者时 tryEmit(1) 返回 $tryOk。这里应是 true,但 1 不会留给后面的收藏者;extraBufferCapacity 只服务已经在订阅的慢消费者")
val collectJob = launch {
noReplay.collect { value -> log("[noReplay] 收藏收到 $value") }
}
delay(20)
noReplay.emit(2)
delay(30)
collectJob.cancel()
log("—— replay=1:先 emit,后到的收藏者应立刻拿到 7 ——")
val withReplay = MutableSharedFlow<Int>(replay = 1)
launch {
withReplay.emit(7)
log("replay=1 流已 emit 7")
}
delay(25)
val lateJob = launch {
withReplay.take(1).collect { value ->
log("[replay=1] 晚到收藏者收到 $value")
}
}
lateJob.join()
}
log("已取消 SharedFlow 收藏,避免永不完成")
}
}
结果输出
—— replay=0,extraBufferCapacity=1,DROP_OLDEST ——
无订阅者时 tryEmit(1) 返回 true。这里应是 true,但 1 不会留给后面的收藏者;extraBufferCapacity 只服务已经在订阅的慢消费者
[noReplay] 收藏收到 2
—— replay=1:先 emit,后到的收藏者应立刻拿到 7 ——
replay=1 流已 emit 7
[replay=1] 晚到收藏者收到 7
已取消 SharedFlow 收藏,避免永不完成
catch 与 retry 的异常透明性
object CatchRetryDemo : FlowDemo {
override val level = FlowDemoLevel.Advanced
override val title = "catch 与 retry 的异常透明性"
override val summary = "retry 可恢复上游失败;catch 只捕上游;下游异常会逃出 catch 操作符。"
override val sourceTrace = """
特性:异常透明性;CancellationException 不会被 retry 当成业务失败。
源码(kotlinx-coroutines 1.9.0):
- kotlinx/coroutines/flow/operators/Errors.kt
— catch、retry、retryWhen
""".trimIndent()
override suspend fun run(log: suspend (String) -> Unit) {
var attempts = 0
log("—— retry(1):第一次上游失败,第二次成功 ——")
flow {
attempts++
if (attempts == 1) {
log("上游第 $attempts 次:抛 IllegalStateException")
throw IllegalStateException("upstream fail")
}
log("上游第 $attempts 次:emit 100")
emit(100)
}
.retry(1) { cause ->
log("retry:捕获 ${cause.javaClass.simpleName},准备重试")
true
}
.collect { log("retry 后收到 $it") }
log("—— catch 只捕它上游的异常 ——")
flow {
emit(1)
error("up")
}
.catch { cause ->
log("catch 捕到上游:${cause.message}")
emit(-1)
}
.collect { log("catch 段收到 $it") }
log("—— 下游 collect 抛异常:不会进上游 catch ——")
try {
flow { emit(1) }
.catch { log("不该出现:下游异常不应被此 catch 处理") }
.collect { throw IllegalStateException("down") }
} catch (e: IllegalStateException) {
log("异常逃到 collect 外:${e.message}(不是 catch 操作符处理的)")
}
}
}
结果输出
—— retry(1):第一次上游失败,第二次成功 ——
上游第 1 次:抛 IllegalStateException
retry:捕获 IllegalStateException,准备重试
上游第 2 次:emit 100
retry 后收到 100
—— catch 只捕它上游的异常 ——
catch 段收到 1
catch 捕到上游:up
catch 段收到 -1
—— 下游 collect 抛异常:不会进上游 catch ——
异常逃到 collect 外:down(不是 catch 操作符处理的)
debounce、sample、distinctUntilChanged
object DebounceSampleDistinctDemo : FlowDemo {
override val level = FlowDemoLevel.Advanced
override val title = "debounce、sample、distinctUntilChanged"
override val summary = "去连续重复;debounce 等安静期;sample 按周期取最新。"
override val sourceTrace = """
特性:distinctUntilChanged 比较相邻元素;debounce/sample 基于时间窗口。
源码(kotlinx-coroutines 1.9.0):
- kotlinx/coroutines/flow/operators/Distinct.kt
— distinctUntilChanged
- kotlinx/coroutines/flow/operators/Delay.kt
— debounce、sample
""".trimIndent()
override suspend fun run(log: suspend (String) -> Unit) {
log("—— distinctUntilChanged ——")
flowOf(1, 1, 2, 2, 3).distinctUntilChanged().collect { value ->
log("[distinct] 收到 $value")
}
log("—— debounce(60ms):连续 emit 后安静才下发最新 ——")
flow {
emit("d1")
delay(15)
emit("d2")
delay(15)
emit("d3")
delay(80)
}
.debounce(60)
.collect { value -> log("[debounce] 收到 $value") }
log("—— sample(70ms):周期采样当前最新 ——")
flow {
emit("s0")
delay(25)
emit("s1")
delay(25)
emit("s2")
delay(25)
emit("s3")
delay(100)
}
.sample(70)
.collect { value -> log("[sample] 收到 $value") }
}
}
结果输出
—— distinctUntilChanged ——
[distinct] 收到 1
[distinct] 收到 2
[distinct] 收到 3
—— debounce(60ms):连续 emit 后安静才下发最新 ——
[debounce] 收到 d3
—— sample(70ms):周期采样当前最新 ——
[sample] 收到 s2
[sample] 收到 s3
chanelFlow 与 callbackFlow
object CallbackChannelFlowDemo : FlowDemo {
override val level = FlowDemoLevel.Advanced
override val title = "channelFlow 与 callbackFlow"
override val summary = "channelFlow 可从子协程 send;callbackFlow 必须 awaitClose 清理回调。"
override val sourceTrace = """
特性:普通 flow { emit } 不能跨协程;channelFlow/callbackFlow 底层走 Channel;callbackFlow 必须以 awaitClose 收尾。
源码(kotlinx-coroutines 1.9.0):
- kotlinx-coroutines-core/common/src/flow/Builders.kt
— channelFlow、callbackFlow
- kotlinx-coroutines-core/common/src/channels/Produce.kt
— awaitClose(block 是普通 lambda,不能在里面调用挂起函数)
""".trimIndent()
override suspend fun run(log: suspend (String) -> Unit) {
log("—— channelFlow:子协程里 send 合法 ——")
coroutineScope {
channelFlow {
launch {
send("来自子协程")
}
send("来自 builder 协程")
}.take(2).collect { value ->
log("[channelFlow] 收到 $value")
}
}
log("说明:普通 flow { } 里在 launch 中 emit 会违反上下文规则")
log("—— callbackFlow:trySend + awaitClose ——")
val unregistered = AtomicBoolean(false)
callbackFlow {
log("模拟注册回调")
trySend("回调数据")
// awaitClose 的 block 不是挂起函数,不能在里面调用 log。
awaitClose { unregistered.set(true) }
}.take(1).collect { value ->
log("[callbackFlow] 收到 $value")
}
log(
if (unregistered.get()) {
"take(1) 取消收藏后已执行 awaitClose,回调已取消注册"
} else {
"awaitClose 未执行"
},
)
delay(20)
}
}
结果输出
—— channelFlow:子协程里 send 合法 ——
[channelFlow] 收到 来自 builder 协程
[channelFlow] 收到 来自子协程
说明:普通 flow { } 里在 launch 中 emit 会违反上下文规则
—— callbackFlow:trySend + awaitClose ——
模拟注册回调
[callbackFlow] 收到 回调数据
take(1) 取消收藏后已执行 awaitClose,回调已取消注册
collect 与 collectLatest
object CollectLatestDemo : FlowDemo {
override val level = FlowDemoLevel.Advanced
override val title = "collect 与 collectLatest"
override val summary = "慢 action 时 collect 会排队处理全部;collectLatest 新值会取消上一次。"
override val sourceTrace = """
特性:collectLatest 在新值到来时取消上一次 action 协程。
源码(kotlinx-coroutines 1.9.0):
- kotlinx/coroutines/flow/terminal/Collect.kt
— collect、collectLatest
""".trimIndent()
override suspend fun run(log: suspend (String) -> Unit) {
fun fastOneTwoThree() = flow {
for (i in 1..3) {
log("上游 emit $i")
emit(i)
}
}
log("—— collect + delay(50):三个值都会处理完 ——")
fastOneTwoThree().collect { value ->
log("[collect] 开始处理 $value")
delay(50)
log("[collect] 完成处理 $value")
}
log("—— collectLatest + delay(50):只有最后一个通常能跑完 ——")
fastOneTwoThree().collectLatest { value ->
log("[collectLatest] 开始处理 $value")
delay(50)
log("[collectLatest] 完成处理 $value")
}
}
}
日志输出
—— collect + delay(50):三个值都会处理完 ——
上游 emit 1
[collect] 开始处理 1
[collect] 完成处理 1
上游 emit 2
[collect] 开始处理 2
[collect] 完成处理 2
上游 emit 3
[collect] 开始处理 3
[collect] 完成处理 3
—— collectLatest + delay(50):只有最后一个通常能跑完 ——
上游 emit 1
[collectLatest] 开始处理 1
上游 emit 2
[collectLatest] 开始处理 2
上游 emit 3
[collectLatest] 开始处理 3
[collectLatest] 完成处理 3
常用场景
搜索框:去抖、去重、取消上一次请求
object SearchQueryDemo : FlowDemo {
override val level = FlowDemoLevel.Scenario
override val title = "搜索框:去抖、去重、取消上一次请求"
override val summary =
"debounce + distinctUntilChanged + flatMapLatest:快速输入只保留最后一次搜索,相同 query 不重复请求。"
override val sourceTrace = """
特性:debounce 静默后取最新值;distinctUntilChanged 跳过连续相同值;flatMapLatest 新 query 会取消上一段搜索流。
源码(kotlinx-coroutines 1.9.0):
- kotlinx-coroutines-core/common/src/flow/operators/Delay.kt
— debounce
- kotlinx-coroutines-core/common/src/flow/operators/Distinct.kt
— distinctUntilChanged
- kotlinx-coroutines-core/common/src/flow/operators/Merge.kt
— flatMapLatest
- kotlinx-coroutines-core/common/src/flow/operators/Errors.kt
— catch
""".trimIndent()
override suspend fun run(log: suspend (String) -> Unit) {
// SharedFlow 能重复 emit 同一个 query。StateFlow 会按 equals 丢掉重复值,看不出 distinctUntilChanged。
val input = MutableSharedFlow<String>()
val results = input
.debounce(50)
.distinctUntilChanged()
.flatMapLatest { query ->
flow {
log("搜索开始: 「$query」")
delay(120)
if (query == "__fail__") error("模拟网络错误")
emit("结果: $query")
log("搜索完成: 「$query」")
}
}
.catch { e ->
log("catch 捕到上游: ${e.message}")
emit("错误: ${e.message}")
}
coroutineScope {
val collectJob = launch {
results.collect { log("UI 展示 → $it") }
}
delay(20)
log("输入 a,等去抖触发,让这次搜索先跑起来")
input.emit("a")
delay(80)
log("a 的搜索还没结束就输入 ab。若 a 只有「开始」没有「完成」,就是被 flatMapLatest 取消了")
input.emit("ab")
delay(220)
log("再 emit 一次相同的 ab。distinctUntilChanged 应跳过,不再出现新的「搜索开始」")
input.emit("ab")
delay(80)
log("输入 __fail__,catch 把上游异常收成一条错误结果")
input.emit("__fail__")
delay(220)
collectJob.cancel()
}
}
}
输入 a,等去抖触发,让这次搜索先跑起来
搜索开始: 「a」
a 的搜索还没结束就输入 ab。若 a 只有「开始」没有「完成」,就是被 flatMapLatest 取消了
搜索开始: 「ab」
搜索完成: 「ab」
UI 展示 → 结果: ab
再 emit 一次相同的 ab。distinctUntilChanged 应跳过,不再出现新的「搜索开始」
输入 __fail__,catch 把上游异常收成一条错误结果
搜索开始: 「__fail__」
catch 捕到上游: 模拟网络错误
UI 展示 → 错误: 模拟网络错误
界面状态 StateFlow
sealed interface UiState {
data object Loading : UiState
data class Success(val data: String) : UiState
data class Error(val message: String) : UiState
}
object UiStateDemo : FlowDemo {
override val level = FlowDemoLevel.Scenario
override val title = "界面状态 StateFlow"
override val summary =
"用 StateFlow 持有 Loading / Success / Error;新订阅者立刻拿到当前态,相等值不会重复发射。"
override val sourceTrace = """
特性:热流 replay=1;按 equals 合并连续相等值;新 collect 立即收到当前 value;适合 UI 状态而非一次性事件。
源码(kotlinx-coroutines 1.9.0):
- kotlinx-coroutines-core/common/src/flow/StateFlow.kt
— MutableStateFlow、StateFlow
""".trimIndent()
override suspend fun run(log: suspend (String) -> Unit) {
val uiState = MutableStateFlow<UiState>(UiState.Loading)
suspend fun logState(state: UiState) {
when (state) {
UiState.Loading -> log("界面状态 → 加载中…")
is UiState.Success -> log("界面状态 → 成功: ${state.data}")
is UiState.Error -> log("界面状态 → 错误: ${state.message}")
}
}
coroutineScope {
val mainCollector = launch {
uiState.collect { logState(it) }
}
delay(50)
log("模拟请求成功")
uiState.value = UiState.Success("用户 #42")
delay(50)
log("再次加载(先 Loading,再失败)")
uiState.value = UiState.Loading
delay(50)
uiState.value = UiState.Error("网络超时")
delay(50)
log("重复设置相同 Error(equals 相同,不应再发射)")
uiState.value = UiState.Error("网络超时")
delay(50)
log("新订阅者加入(StateFlow 立刻 replay 当前 Error,不会错过)")
val lateCollector = launch {
uiState.collect { log("晚到订阅者看到: $it") }
}
delay(50)
lateCollector.cancel()
mainCollector.cancel()
}
}
}
结果输出
界面状态 → 加载中…
模拟请求成功
界面状态 → 成功: 用户 #42
再次加载(先 Loading,再失败)
界面状态 → 加载中…
界面状态 → 错误: 网络超时
重复设置相同 Error(equals 相同,不应再发射)
新订阅者加入(StateFlow 立刻 replay 当前 Error,不会错过)
晚到订阅者看到: Error(message=网络超时)
一次性事件用 SharedFlow
object OneShotEventDemo : FlowDemo {
override val level = FlowDemoLevel.Scenario
override val title = "一次性事件用 SharedFlow"
override val summary =
"导航、Toast 等只消费一次的事件用 SharedFlow;无订阅时会丢,有订阅时按次交付。"
override val sourceTrace = """
特性:没有订阅者时 tryEmit 返回 true,但 replay=0 的值会被直接丢掉;有订阅者时事件只交给当前订阅者一次。
为何导航/Toast 不用 StateFlow:StateFlow replay=1 且按 equals 合并,旋转屏后可能重复触发导航,或两次相同 Toast 被合并吞掉。
源码(kotlinx-coroutines 1.9.0):
- kotlinx-coroutines-core/common/src/flow/SharedFlow.kt
— MutableSharedFlow.tryEmit
没有订阅者时,tryEmit 返回 true,但 replay=0 的值会被丢掉,不会进 extraBufferCapacity。
""".trimIndent()
override suspend fun run(log: suspend (String) -> Unit) {
val events = MutableSharedFlow<String>(
replay = 0,
extraBufferCapacity = 1,
onBufferOverflow = BufferOverflow.DROP_OLDEST,
)
log("尚无订阅者,tryEmit「离线提示」")
val accepted = events.tryEmit("离线提示")
log("tryEmit 返回 $accepted。返回 true 只表示调用方不用挂起;replay=0 且当时没人订阅,这个值已被丢掉")
coroutineScope {
log("—— 订阅者 A 上线 ——")
val collectorA = launch {
events.collect { log("订阅者 A 收到: $it") }
}
delay(30)
log("emit「Toast: 保存成功」")
events.emit("Toast: 保存成功")
delay(30)
collectorA.cancel()
log("订阅者 A 已取消")
log("—— 订阅者 B 晚到(看不到刚才的 Toast)——")
val collectorB = launch {
events.collect { log("订阅者 B 收到: $it") }
}
delay(30)
log("emit「导航: 详情页」")
events.emit("导航: 详情页")
delay(30)
collectorB.cancel()
}
}
}
结果输出
尚无订阅者,tryEmit「离线提示」
tryEmit 返回 true。返回 true 只表示调用方不用挂起;replay=0 且当时没人订阅,这个值已被丢掉
—— 订阅者 A 上线 ——
emit「Toast: 保存成功」
订阅者 A 收到: Toast: 保存成功
订阅者 A 已取消
—— 订阅者 B 晚到(看不到刚才的 Toast)——
emit「导航: 详情页」
订阅者 B 收到: 导航: 详情页
表单: combine 多字段
object FormValidationDemo : FlowDemo {
override val level = FlowDemoLevel.Scenario
override val title = "表单:combine 多字段"
override val summary = "name 与 email 两个 StateFlow,用 combine 推导「是否可提交」。"
override val sourceTrace = """
特性:combine 等所有上游各至少 emit 一次后才发第一次组合;任一上游更新时用各流最新值再算。
源码(kotlinx-coroutines 1.9.0):
- kotlinx-coroutines-core/common/src/flow/operators/Zip.kt
— combine
""".trimIndent()
override suspend fun run(log: suspend (String) -> Unit) {
val name = MutableStateFlow("")
val email = MutableStateFlow("")
val isValid = combine(name, email) { n, e ->
n.isNotBlank() && e.contains('@')
}
coroutineScope {
val job = launch {
isValid.collect { valid ->
log(
"可提交=${valid}(name=「${name.value}」, email=「${email.value}」)",
)
}
}
delay(40)
log("填写 name")
name.value = "张三"
delay(40)
log("填写 email(缺 @,仍无效)")
email.value = "zhangsan"
delay(40)
log("补全 email")
email.value = "zhangsan@example.com"
delay(40)
log("清空 name(应立刻变无效)")
name.value = ""
delay(40)
job.cancel()
}
}
}
结果输出
可提交=false(name=「」, email=「」)
填写 name
可提交=false(name=「张三」, email=「」)
填写 email(缺 @,仍无效)
可提交=false(name=「张三」, email=「zhangsan」)
补全 email
可提交=true(name=「张三」, email=「zhangsan@example.com」)
清空 name(应立刻变无效)
可提交=false(name=「」, email=「zhangsan@example.com」)
轮询与 retryWhen
object PollingRetryDemo : FlowDemo {
override val level = FlowDemoLevel.Scenario
override val title = "轮询与 retryWhen"
override val summary =
"网络失败用 retryWhen 限次重试;轮询用 while + delay,cancel 后协作式停止。"
override val sourceTrace = """
特性:retryWhen 按 cause 与 attempt 决定是否继续;CancellationException 必须原样抛出,不能当业务错误重试。
delay 为挂起函数,协程 cancel 时会抛 CancellationException,轮询自然结束。
源码(kotlinx-coroutines 1.9.0):
- kotlinx-coroutines-core/common/src/flow/operators/Errors.kt
— retryWhen
- kotlinx-coroutines-core/common/src/Delay.kt
— delay
""".trimIndent()
override suspend fun run(log: suspend (String) -> Unit) {
var upstreamCalls = 0
log("—— retryWhen:首次 IOException,重试后成功 ——")
flow {
upstreamCalls++
log("上游第 $upstreamCalls 次调用")
if (upstreamCalls == 1) throw IOException("连接重置")
emit("payload-v$upstreamCalls")
}
.retryWhen { cause, attempt ->
if (cause is CancellationException) return@retryWhen false
if (cause is IOException && attempt < 1) {
log("retryWhen: IOException,短 delay 后重试(attempt=$attempt)…")
delay(40)
true
} else {
false
}
}
.collect { log("收到数据: $it") }
log("—— 可取消轮询 ——")
coroutineScope {
val pollJob = launch {
flow {
var tick = 0
while (true) {
emit(tick++)
delay(40)
}
}.collect { log("轮询 tick=$it") }
}
delay(100)
pollJob.cancel()
pollJob.join()
log("已 cancel 并 join 轮询 Job。delay 在取消时抛出 CancellationException,循环停住")
}
}
}
结果输出
—— retryWhen:首次 IOException,重试后成功 ——
上游第 1 次调用
retryWhen: IOException,短 delay 后重试(attempt=0)…
上游第 2 次调用
收到数据: payload-v2
—— 可取消轮询 ——
轮询 tick=0
轮询 tick=1
轮询 tick=2
已 cancel 并 join 轮询 Job。delay 在取消时抛出 CancellationException,循环停住