android-frame/frame/coroutine/CLAUDE.md

Coroutine 模块

模块概述

Coroutine 模块是 Kotlin 协程工具封装模块，提供了统一的线程池管理、协程调度器、异常处理机制和 Flow 扩展功能。该模块简化了协程的使用，提供了高效的线程管理策略和便捷的异常处理方案。

主要功能

1. 线程池统一管理

• Dispatcher: 统一的线程调度器管理
• 智能的线程池策略设计
• 基于 CPU 核心数的线程分配
• 串行和并行线程池支持

2. 协程扩展工具

• CoroutineExt: 协程扩展函数
• 支持全局异常捕获的协程启动
• 便捷的作用域创建工具
• 异常处理链式调用

3. Flow 扩展

• FlowExt: Flow 扩展功能
• 节流 (throttleFirst) 支持
• 防止重复触发机制

4. 线程工厂

• NamedThreadFactory: 命名线程工厂
• 支持线程优先级设置
• 便于调试和监控

核心类和接口

Dispatcher

object Dispatcher {
    // UI 主线程调度器
    val UI: CoroutineDispatcher
    
    // 获取串行处理 Handler
    fun getSerialHandler(): Handler
    
    // 通用线程池调度器
    val WENEXT_THREAD_POOL: CoroutineDispatcher
    
    // Handler 扩展方法
    fun Handler.submit(runnable: Runnable, delay: Long = 0L)
    fun Handler.remove(runnable: Runnable)
}

协程扩展

// 创建 IO 作用域
fun createIOScope(context: CoroutineContext = EmptyCoroutineContext): CoroutineScope

// 创建主线程作用域
fun createMainScope(context: CoroutineContext = EmptyCoroutineContext): CoroutineScope

// 带异常捕获的协程启动
fun CoroutineScope.launchWithCatch(
    context: CoroutineContext = coroutineContext,
    start: CoroutineStart = CoroutineStart.DEFAULT,
    block: suspend CoroutineScope.() -> Unit
): CoroutineCatcher

Flow 扩展

// 节流操作，防止频繁触发
fun <T> Flow<T>.throttleFirst(duration: Long): Flow<T>

使用方式

1. 使用 Dispatcher 进行线程调度

// 在主线程执行
launch(Dispatcher.UI) {
    // UI 操作
    updateUI()
}

// 在后台线程执行
launch(Dispatcher.WENEXT_THREAD_POOL) {
    // 耗时操作
    val result = networkCall()
}

// 使用串行 Handler
val serialHandler = Dispatcher.getSerialHandler()
serialHandler.submit({
    // 串行执行的任务
    processData()
}, delay = 1000L)

2. 使用协程作用域扩展

// 创建 IO 作用域
val ioScope = createIOScope()
ioScope.launch {
    // IO 操作
    val data = loadFromDatabase()
}

// 创建主线程作用域
val mainScope = createMainScope()
mainScope.launch {
    // 主线程操作
    updateView()
}

3. 使用异常捕获协程

// 链式异常处理
viewModelScope.launchWithCatch {
    // 可能抛出异常的操作
    val result = riskyOperation()
    updateUI(result)
}.catch { context, throwable ->
    // 统一异常处理
    Log.e("TAG", "Coroutine error", throwable)
    showError(throwable.message)
}

4. 使用 Flow 扩展

// 防止频繁点击
clickFlow
    .throttleFirst(1000L) // 1秒内只响应第一次点击
    .collect { 
        handleClick() 
    }

// 搜索防抖
searchFlow
    .throttleFirst(300L) // 300ms 防抖
    .collect { query ->
        performSearch(query)
    }

线程池管理策略

1. 线程分配策略

• UI 线程: 1 个主线程处理器
• 串行线程: (CPU 核心数 - 1) 个串行处理线程
• IO 线程池: 最少 2 个，最多基于 CPU 核心数动态调整

2. 线程池配置

// 主线程池配置
ThreadPoolExecutor(
    1,                                    // 核心线程数
    20.coerceAtLeast(AVAILABLE_PROCESSORS), // 最大线程数
    3, TimeUnit.SECONDS,                  // 空闲超时
    SynchronousQueue(),                   // 同步队列
    NamedThreadFactory("wenext-thread-pool") // 命名工厂
)

// 备用线程池（用于拒绝策略）
ThreadPoolExecutor(
    IO_CORE_POOL_SIZE,
    IO_CORE_POOL_SIZE,
    3, TimeUnit.SECONDS,
    LinkedBlockingQueue(),               // 无界队列
    NamedThreadFactory("wenext-backup-thread-pool")
)

依赖关系

编译时依赖

• kotlinx.coroutines.core - Kotlin 协程核心库
• kotlinx.coroutines.android - Android 协程支持

被依赖关系

• frame:base - 基础模块使用协程调度器
• frame:mvvm - MVVM 模块使用协程作用域
• 其他需要异步处理的模块

构建配置

implementation "com.wenext.android:frame-coroutine:6.0.0"

注意事项

1. 线程池管理: Dispatcher 使用单例模式，自动管理线程生命周期
2. 异常处理: launchWithCatch 提供全局异常捕获，子协程的异常会统一处理
3. 内存泄漏: 使用协程作用域时注意及时取消，避免内存泄漏
4. 线程切换: Handler.submit 会根据当前线程智能选择立即执行或调度执行
5. 性能优化: 串行 Handler 使用轮询分配，避免单一线程过载
6. 拒绝策略: 主线程池满载时会自动降级到备用线程池
7. Flow 节流: throttleFirst 基于时间窗口，适用于防重复点击场景