kotlin Flow 基础使用

0 阅读11分钟

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,循环停住