Android 协程集成

// CoroutineDispatcher 核心抽象（简化版）
public abstract class CoroutineDispatcher : AbstractCoroutineContextElement(ContinuationInterceptor) {
 
    // 判断是否需要进行线程调度
    // 绝大多数 Dispatcher 返回 true，表示需要把任务提交到目标线程
    // Unconfined 返回 false，表示直接在当前线程继续执行
    public open fun isDispatchNeeded(context: CoroutineContext): Boolean = true
 
    // 核心方法：将 block（Runnable）调度到目标线程执行
    // 不同子类有不同实现：Main 提交到 Handler、IO/Default 提交到线程池
    public abstract fun dispatch(context: CoroutineContext, block: Runnable)
}

// Dispatchers.Main 的使用示例
// 假设在 Activity 或 Fragment 中
lifecycleScope.launch(Dispatchers.Main) { // 在主线程启动协程
    // 第一步：切到 IO 线程执行网络请求
    val result = withContext(Dispatchers.IO) {
        // 这里运行在 IO 线程池中
        repository.fetchUserData() // 挂起函数，不会阻塞主线程
    }
    // 第二步：withContext 返回后，自动恢复到 Main 调度器
    // 以下代码运行在主线程，可以安全地更新 UI
    binding.tvUserName.text = result.name   // 更新用户名文本
    binding.tvEmail.text = result.email     // 更新邮箱文本
    binding.progressBar.isVisible = false   // 隐藏加载进度条
}

// Dispatchers.Default 的使用示例
lifecycleScope.launch {
    // 将 CPU 密集型计算切换到 Default 调度器
    val sortedList = withContext(Dispatchers.Default) {
        // 运行在 Default 线程池中（线程数 = CPU 核心数）
        val rawList = loadLargeDataSet()      // 假设加载了 100 万条数据
        rawList.sortedBy { it.timestamp }     // 排序操作消耗大量 CPU
    }
    // 回到 Main 调度器，安全地更新 UI
    adapter.submitList(sortedList) // 提交排序后的列表给 RecyclerView
}

// IO 与 Default 协作示例
lifecycleScope.launch {
    val processedData = withContext(Dispatchers.IO) {
        // 第一步：在 IO 调度器中进行网络请求
        val rawJson = apiService.fetchData()           // 网络请求，IO 等待
 
        // 第二步：切到 Default 进行 CPU 密集型解析
        // 由于共享线程池，这次切换的开销极低
        withContext(Dispatchers.Default) {
            JsonParser.parse(rawJson)                  // JSON 解析，消耗 CPU
        }
    }
    // 回到 Main，更新 UI
    renderData(processedData)
}

// 创建一个独立的调度器视图，限制并发度为 4
// 注意：这不会从 IO 的 64 个线程额度中扣除，而是独立的
val databaseDispatcher = Dispatchers.IO.limitedParallelism(4)
 
suspend fun queryDatabase(): List<User> {
    return withContext(databaseDispatcher) {           // 最多 4 个协程同时执行
        database.userDao().getAllUsers()               // Room 数据库查询
    }
}

// Dispatchers.Unconfined 的执行线程"漂移"演示
lifecycleScope.launch(Dispatchers.Unconfined) {
    // 启动时：运行在调用 launch 的线程（通常是主线程）
    println("Step 1: ${Thread.currentThread().name}")  // 输出: main
 
    // delay 是一个挂起函数，恢复由 kotlinx.coroutines 调度线程完成
    delay(100)
 
    // 恢复后：运行在 delay 内部使用的调度线程上
    println("Step 2: ${Thread.currentThread().name}")  // 输出: kotlinx.coroutines.DefaultExecutor
    // 注意！此时已经不在主线程了，操作 UI 会崩溃！
}

// ❌ 不推荐：循环内频繁切换调度器
lifecycleScope.launch {
    for (item in largeList) {
        val data = withContext(Dispatchers.IO) { fetchData(item) }     // 每次切到 IO
        val result = withContext(Dispatchers.Default) { parse(data) }  // 每次切到 Default
        withContext(Dispatchers.Main) { updateUI(result) }             // 每次切到 Main
        // 每轮循环至少 3 次调度器切换，累计开销巨大
    }
}
 
// ✅ 推荐：批量操作，减少切换
lifecycleScope.launch {
    // 在 IO 调度器中批量完成所有网络请求
    val allData = withContext(Dispatchers.IO) {
        largeList.map { fetchData(it) }          // 一次性完成全部 IO
    }
    // 在 Default 调度器中批量解析
    val allResults = withContext(Dispatchers.Default) {
        allData.map { parse(it) }                // 一次性完成全部解析
    }
    // 回到 Main，一次性更新 UI
    allResults.forEach { updateUI(it) }          // 只切换一次回主线程
}

// 基于 Java ExecutorService 创建自定义调度器
val singleThreadDispatcher = Executors
    .newSingleThreadExecutor()        // 创建单线程执行器
    .asCoroutineDispatcher()          // 转换为协程调度器
 
lifecycleScope.launch {
    withContext(singleThreadDispatcher) {
        // 所有在此块内的代码保证在同一个线程上串行执行
        // 适用于需要线程安全但不想用锁的场景
        sharedCounter++                // 无需同步，单线程保证安全
    }
}
 
// ⚠️ 重要：自定义调度器使用的线程池需要手动关闭
// 否则线程会一直存活，造成资源泄漏
// singleThreadDispatcher.close()

lifecycleScope.launch {
    Log.d("Test", "A: ${Thread.currentThread().name}")
    withContext(Dispatchers.IO) {
        Log.d("Test", "B: ${Thread.currentThread().name}")
        withContext(Dispatchers.Default) {
            Log.d("Test", "C: ${Thread.currentThread().name}")
        }
        Log.d("Test", "D: ${Thread.currentThread().name}")
    }
    Log.d("Test", "E: ${Thread.currentThread().name}")
}

// HandlerContext 是 Dispatchers.Main 在 Android 上的真正实现
// 它继承自 CoroutineDispatcher，额外实现了 Delay 接口以支持 delay() 挂起
internal class HandlerContext private constructor(
    private val handler: Handler,       // 指向主线程 Looper 的 Handler 实例
    private val name: String?,          // 调试用名称，如 "Dispatchers.Main"
    private val invokeImmediately: Boolean // 是否为 immediate 模式（关键区分点）
) : HandlerDispatcher(), Delay {
 
    // 构造函数：外部传入 handler，默认 name 为 null，非 immediate 模式
    constructor(
        handler: Handler,
        name: String? = null
    ) : this(handler, name, false)
 
    // immediate 属性：返回一个 invokeImmediately = true 的新 HandlerContext
    // 这就是 Dispatchers.Main.immediate 的来源
    override val immediate: HandlerContext =
        if (invokeImmediately) this  // 如果自身已经是 immediate，直接返回 this 避免重复包装
        else HandlerContext(handler, name, true) // 否则创建一个新的 immediate 版本
 
    // 核心方法：判断当前线程是否需要调度
    // 如果是 immediate 模式且当前已在主线程，返回 false 表示"不需要调度，直接执行"
    override fun isDispatchNeeded(context: CoroutineContext): Boolean {
        return !invokeImmediately || Looper.myLooper() != handler.looper
        // 非 immediate 模式 → 总是返回 true → 总是通过 Handler.post
        // immediate 模式 + 已在主线程 → 返回 false → 跳过 post，立即执行
        // immediate 模式 + 不在主线程 → 返回 true → 仍需 Handler.post
    }
 
    // 核心方法：将协程的 Runnable 投递到主线程执行
    override fun dispatch(context: CoroutineContext, block: Runnable) {
        // 使用 handler.post 将 Runnable 排入主线程的 MessageQueue
        if (!handler.post(block)) {
            // post 返回 false 说明 Looper 已退出（App 正在终止）
            // 此时调用 cancel 通知协程无法继续
            (block as? DispatchedContinuation<*>)?.cancelOnRejection(context)
        }
    }
 
    // 支持 delay() 挂起函数的实现
    // 底层使用 Handler.postDelayed，比 Thread.sleep 高效得多
    override fun scheduleResumeAfterDelay(
        timeMillis: Long,
        continuation: CancellableContinuation<Unit>
    ) {
        // 将 continuation 包装为 Runnable
        val block = Runnable { continuation.resume(Unit) }
        // 使用 Handler 的延迟投递
        handler.postDelayed(block, timeMillis.coerceAtLeast(0))
        // 注册取消回调：如果协程在 delay 期间被取消，移除 pending 的 Message
        continuation.invokeOnCancellation { handler.removeCallbacks(block) }
    }
}

// 一个封装好的工具方法，确保 UI 更新在主线程执行
suspend fun updateUi(text: String) {
    withContext(Dispatchers.Main) {  // 如果调用者已经在主线程呢？
        textView.text = text
    }
}
 
// 调用处：已经在主线程的协程中
lifecycleScope.launch {  // 默认 Dispatchers.Main
    val data = withContext(Dispatchers.IO) { fetchData() }
    updateUi(data)  // 此时已经在主线程，但 updateUi 内部又 withContext(Main)
}

// isDispatchNeeded 是协程调度的"守门人"
// 返回 true → 必须通过 dispatch() 投递（异步）
// 返回 false → 跳过 dispatch()，直接在当前线程执行（同步）
override fun isDispatchNeeded(context: CoroutineContext): Boolean {
    // 情况 1：非 immediate 模式（普通 Dispatchers.Main）
    //   → !false = true → 总是需要 dispatch → 总是 post
    // 情况 2：immediate 模式 + 当前不在主线程
    //   → !true || (myLooper != mainLooper) = true → 需要 dispatch → post
    // 情况 3：immediate 模式 + 当前已在主线程
    //   → !true || (mainLooper != mainLooper) = false → 不需要 dispatch → 立即执行
    return !invokeImmediately || Looper.myLooper() != handler.looper
}

// 实验：在主线程协程中分别使用 Main 和 Main.immediate
lifecycleScope.launch(Dispatchers.Main) {
    val start = System.nanoTime()
 
    // 方式 A：普通 Main（即使已在主线程，仍然 post）
    withContext(Dispatchers.Main) {
        val elapsed = (System.nanoTime() - start) / 1_000_000.0
        Log.d("Perf", "Dispatchers.Main: ${elapsed}ms")
        // 典型结果：0.5ms ~ 16ms（取决于 MessageQueue 负载）
        // 最差情况下会等待一整个 VSYNC 周期（~16.6ms）
    }
 
    val start2 = System.nanoTime()
 
    // 方式 B：Main.immediate（已在主线程，直接执行）
    withContext(Dispatchers.Main.immediate) {
        val elapsed = (System.nanoTime() - start2) / 1_000_000.0
        Log.d("Perf", "Main.immediate: ${elapsed}ms")
        // 典型结果：< 0.01ms（几乎为零，仅函数调用开销）
    }
}

// ❌ 传统 Handler.post 方式：回调嵌套，难以维护
// handler 指向主线程
val handler = Handler(Looper.getMainLooper())
 
fun loadDataTraditional() {
    // 在 IO 线程执行网络请求
    Executors.newSingleThreadExecutor().execute {
        try {
            // 网络请求（阻塞 IO 线程）
            val response = api.fetchDataSync()
            // 解析数据（仍在 IO 线程）
            val parsed = parser.parse(response)
            // 切回主线程更新 UI —— 回调嵌套第 1 层
            handler.post {
                textView.text = parsed.title
                // 假设还需要根据结果再请求一次
                Executors.newSingleThreadExecutor().execute {  // 嵌套第 2 层
                    val detail = api.fetchDetailSync(parsed.id)
                    handler.post {  // 嵌套第 3 层
                        detailView.text = detail.content
                    }
                }
            }
        } catch (e: Exception) {
            // 异常处理也要 post 到主线程
            handler.post {  // 又一层嵌套
                Toast.makeText(context, "Error: ${e.message}", Toast.LENGTH_SHORT).show()
            }
        }
    }
    // ⚠️ 如果 Activity 已销毁，上面的 handler.post 仍然会执行
    // 需要手动在 onDestroy 中取消，但 Executor 的 Future 管理非常麻烦
}

// ✅ 协程方式：线性代码，结构化并发，自动取消
fun loadDataCoroutine() {
    // lifecycleScope 自动绑定 Activity 生命周期
    // 默认使用 Dispatchers.Main.immediate
    lifecycleScope.launch {
        try {
            // withContext 切到 IO 线程执行网络请求
            // 挂起当前协程，不阻塞主线程
            val response = withContext(Dispatchers.IO) {
                api.fetchDataSync()  // 在 IO 线程执行
            }
            // 自动回到主线程（因为 launch 的调度器是 Main.immediate）
            val parsed = parser.parse(response)
            textView.text = parsed.title
 
            // 需要再请求一次？直接写下一行，没有嵌套
            val detail = withContext(Dispatchers.IO) {
                api.fetchDetailSync(parsed.id)  // 在 IO 线程执行
            }
            // 又自动回到主线程
            detailView.text = detail.content
 
        } catch (e: Exception) {
            // 异常处理也在主线程，与正常流程在同一个 try-catch 中
            Toast.makeText(context, "Error: ${e.message}", Toast.LENGTH_SHORT).show()
        }
    }
    // ✅ Activity 销毁时，lifecycleScope 自动取消所有子协程
    // 不需要手动管理任何回调或 Future
}

// View.post 保证在 layout 完成后执行
// 这种场景用协程反而不直观
view.post {
    // 此时 view.width 和 view.height 已经确定
    val width = view.width  // 安全获取宽度
    val height = view.height  // 安全获取高度
}

// 假设当前在主线程的某个回调中
lifecycleScope.launch(Dispatchers.Main.immediate) {
    // 【A】立即执行（因为 immediate 且已在主线程）
    Log.d("Order", "A: coroutine immediate")
}
 
handler.post {
    // 【B】排入 MessageQueue 队尾
    Log.d("Order", "B: handler post")
}
 
view.post {
    // 【C】也是排入队尾（通过 View 的 AttachInfo Handler）
    Log.d("Order", "C: view post")
}
 
Log.d("Order", "D: current execution")

lifecycleScope.launch(Dispatchers.Main.immediate) {
    Log.d("T", "1")
    withContext(Dispatchers.Main) {
        Log.d("T", "2")
    }
    Log.d("T", "3")
}
Log.d("T", "4")

// build.gradle.kts
dependencies {
    // lifecycle-runtime-ktx 提供了 lifecycleScope 扩展
    // 以及 repeatOnLifecycle 等生命周期感知协程工具
    implementation("androidx.lifecycle:lifecycle-runtime-ktx:2.8.7")
}

class HomeActivity : AppCompatActivity() {
 
    // 假设使用 Hilt 或手动创建 ViewModel
    private val viewModel: HomeViewModel by viewModels()
 
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_home)
 
        // lifecycleScope 是 LifecycleOwner 的扩展属性
        // 在此作用域内启动的协程，会在 Activity onDestroy 时自动取消
        lifecycleScope.launch {
            // 此处默认运行在 Dispatchers.Main（主线程）上
            // 非常适合收集 UI 状态流
            viewModel.uiState.collect { state ->
                // 安全地更新 UI，因为协程会随 Activity 销毁而取消
                // 不会出现在已销毁 Activity 上操作 View 的问题
                updateUI(state)
            }
        }
 
        // 同一作用域内可以启动多个协程，它们是并发执行的
        lifecycleScope.launch {
            // 执行一次性数据加载
            val config = viewModel.loadRemoteConfig()
            // 加载完成后更新 UI
            applyConfig(config)
        }
    }
}

class HomeFragment : Fragment(R.layout.fragment_home) {
 
    private val viewModel: HomeViewModel by viewModels()
 
    override fun onViewCreated(view: View, savedInstanceState: Bundle?) {
        super.onViewCreated(view, savedInstanceState)
 
        // ✅ 正确做法：使用 viewLifecycleOwner.lifecycleScope
        // 此协程绑定到 View 的生命周期
        // 当 Fragment 进入 Back Stack（onDestroyView）时自动取消
        // 当 Fragment 重新可见（onCreateView）时，需要重新启动
        viewLifecycleOwner.lifecycleScope.launch {
            viewModel.uiState.collect { state ->
                // 安全：View 销毁时协程已被取消，不会访问已回收的 View
                binding.titleText.text = state.title
                binding.contentText.text = state.content
            }
        }
 
        // ⚠️ 错误做法（常见 Bug 来源）：
        // lifecycleScope.launch { ... }
        // 这绑定的是 Fragment 自身生命周期
        // 如果 Fragment 在 Back Stack 中，View 被销毁但协程仍在运行
        // 访问 binding 或 view 会触发 NullPointerException 或 IllegalStateException
    }
 
    // 如果是与 UI 无关的操作（如数据预加载），可以使用 Fragment 自身的 lifecycleScope
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        
        // ✅ 合理：这里不涉及 View 操作，用 Fragment 生命周期是安全的
        lifecycleScope.launch {
            viewModel.preloadData()
        }
    }
}

lifecycleScope.launch(Dispatchers.Default) {
    // 假设我们需要处理大量数据
    for (i in 0 until 1_000_000) {
        // 每次迭代检查协程是否仍然活跃
        // 如果已被取消，ensureActive() 会抛出 CancellationException
        ensureActive()
        
        // 执行计算
        processItem(i)
    }
}

lifecycleScope.launch {
    try {
        // 执行网络请求
        val result = apiService.fetchData()
        updateUI(result)
    } catch (e: CancellationException) {
        // ⚠️ 如果你捕获了 CancellationException，必须重新抛出！
        // 否则取消不会生效，协程会继续执行后续代码
        throw e
    } catch (e: Exception) {
        // 处理其他异常（网络错误等）
        showError(e.message)
    }
}
 
// 更推荐的简洁写法：使用 runCatching 的安全版本
lifecycleScope.launch {
    try {
        val result = apiService.fetchData()
        updateUI(result)
    } catch (e: Exception) {
        // 从 Kotlin 1.5 开始，如果 e 是 CancellationException
        // 可以用 coroutineContext.ensureActive() 来检查
        coroutineContext.ensureActive()
        // 如果执行到这里，说明不是取消异常，正常处理错误
        showError(e.message)
    }
}

class DashboardActivity : AppCompatActivity() {
 
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_dashboard)
 
        // 启动一个"永远运行"的轮询协程
        lifecycleScope.launch {
            // 使用 while(true) 无限循环轮询
            while (true) {
                try {
                    // 通过 withContext 切换到 IO 线程执行网络请求
                    val status = withContext(Dispatchers.IO) {
                        apiService.getServerStatus()
                    }
                    // 回到主线程更新 UI
                    statusTextView.text = status.message
                } catch (e: Exception) {
                    // 确保不吞掉 CancellationException
                    coroutineContext.ensureActive()
                    // 处理网络异常
                    statusTextView.text = "连接失败"
                }
                // 每 30 秒轮询一次
                // delay 是一个挂起函数，是天然的取消检查点
                delay(30_000L)
            }
        }
 
        // 当用户退出 Activity 时：
        // 1. onDestroy() 被调用
        // 2. lifecycleScope 监听到 ON_DESTROY
        // 3. 内部 SupervisorJob 被 cancel()
        // 4. 上面的协程在 delay() 处（或 withContext 处）被取消
        // 5. 无需手动管理，没有内存泄漏风险
    }
}

// SupervisorJob 在 lifecycleScope 中的效果
lifecycleScope.launch {
    // ⚠️ 注意！这里通过 launch 启动的子协程，它的父 Job 是这个
    // launch 创建的普通 Job，而不是 lifecycleScope 的 SupervisorJob！
    // 所以如果 coroutine1 失败，coroutine2 也会被取消
    val coroutine1 = launch {
        error("失败") // 这会导致 coroutine2 也被取消！
    }
    val coroutine2 = launch {
        delay(1000)
        println("不会执行到这里")
    }
}
 
// 如果要在嵌套 launch 中也实现隔离，需要 supervisorScope
lifecycleScope.launch {
    // supervisorScope 内部的子协程互相隔离
    supervisorScope {
        val coroutine1 = launch {
            error("失败") // coroutine1 失败
        }
        val coroutine2 = launch {
            delay(1000)
            println("✅ 这会正常执行") // coroutine2 不受影响
        }
    }
}

// 伪代码展示 lifecycleScope 的内部实现
val lifecycleScope: LifecycleCoroutineScope
    get() {
        // 惰性创建，首次访问时初始化
        // SupervisorJob：子协程异常隔离
        // Dispatchers.Main.immediate：默认在主线程调度，支持 immediate 优化
        val context = SupervisorJob() + Dispatchers.Main.immediate
        // 注册生命周期观察者
        // 当 ON_DESTROY 事件到达时，cancel 这个 SupervisorJob
        lifecycle.addObserver(/* 观察 ON_DESTROY 事件 */)
        return LifecycleCoroutineScope(lifecycle, context)
    }

CoroutineContext of LifecycleScope
├── SupervisorJob ← lifecycle ON_DESTROY 时 cancel
├── Dispatchers.Main.immediate
└── (可选) CoroutineExceptionHandler
 
Job 树：
SupervisorJob (lifecycleScope)          ← 被 cancel 时级联取消所有子 Job
    ├── Job (launch #1: 加载资料)       ← 独立，失败不影响 #2 和 #3
    │       └── Job (内部 launch)       ← 与 #1 是普通父子关系
    ├── Job (launch #2: 拉取消息)       ← 独立，失败不影响 #1 和 #3
    └── Job (launch #3: 初始化统计)     ← 独立，失败不影响 #1 和 #2

// 方式 1：在 launch 内部 try-catch
lifecycleScope.launch {
    try {
        riskyOperation()
    } catch (e: Exception) {
        coroutineContext.ensureActive() // 确保不吞掉 CancellationException
        Log.e("TAG", "操作失败", e)
    }
}
 
// 方式 2：传入 CoroutineExceptionHandler
val handler = CoroutineExceptionHandler { _, throwable ->
    // 注意：这里运行在调度器的线程上（通常是主线程）
    Log.e("TAG", "协程异常", throwable)
}
lifecycleScope.launch(handler) {
    riskyOperation() // 异常会被 handler 捕获，不会崩溃
}

lifecycleScope.launch {
    // async 返回 Deferred，异常存储在 Deferred 中
    val deferred = async {
        error("发生错误") // 异常暂时不传播
    }
    // 如果不调用 deferred.await()，异常会丢失
    // 调用 await() 时，异常才会重新抛出
    val result = deferred.await() // ← 异常在这里抛出
}

// -------- viewModelScope 的核心实现原理（简化版） --------
 
// 用于在 ViewModel 的 tag 存储中缓存作用域对象的 Key
private const val JOB_KEY = "androidx.lifecycle.ViewModelCoroutineScope.JOB_KEY"
 
// viewModelScope 是 ViewModel 的扩展属性（extension property）
// 调用时不需要括号，就像访问普通字段一样：viewModelScope.launch { ... }
public val ViewModel.viewModelScope: CoroutineScope
    get() {
        // 1. 先尝试从 ViewModel 内部的 tag 缓存中取出已有的作用域
        val scope: CloseableCoroutineScope? = this.getTag(JOB_KEY)
        if (scope != null) {
            // 如果已经创建过，直接复用，保证同一个 ViewModel 只有一个作用域
            return scope
        }
        // 2. 如果是首次访问，创建一个新的 CloseableCoroutineScope
        //    使用 SupervisorJob + Dispatchers.Main.immediate 作为上下文
        return setTagIfAbsent(
            JOB_KEY,
            CloseableCoroutineScope(SupervisorJob() + Dispatchers.Main.immediate)
        )
    }
 
// CloseableCoroutineScope 实现了 Closeable 接口
// 当 ViewModel.clear() 被调用时，会遍历所有 tag 中的 Closeable 并调用 close()
internal class CloseableCoroutineScope(
    context: CoroutineContext  // 保存协程上下文
) : Closeable, CoroutineScope {
 
    // 实现 CoroutineScope 接口所需的 coroutineContext
    override val coroutineContext: CoroutineContext = context
 
    // 当 Closeable.close() 被调用时，取消作用域内的 Job
    // 这就是与 ViewModel 生命周期绑定的关键桥梁
    override fun close() {
        coroutineContext.cancel()  // 取消 Job，级联取消所有子协程
    }
}

class MyViewModel(
    private val repository: MyRepository  // 假设的数据仓库层
) : ViewModel() {
 
    // ========== 场景 1：正常使用 viewModelScope ==========
    fun loadData() {
        // 在 viewModelScope 中启动协程
        // 当 ViewModel 被清除时，此协程会在下一个挂起点自动取消
        viewModelScope.launch {
            // 切换到 IO 线程执行网络请求（这是一个挂起点）
            val result = withContext(Dispatchers.IO) {
                repository.fetchRemoteData()  // 挂起函数，支持取消
            }
            // 回到 Main 线程更新 UI 状态
            _uiState.value = result  // 如果协程已取消，这行不会执行
        }
    }
 
    // ========== 场景 2：长循环中的主动取消检查 ==========
    fun processLargeDataset(items: List<Item>) {
        viewModelScope.launch(Dispatchers.Default) {
            // 遍历大量数据进行 CPU 密集型处理
            for (item in items) {
                ensureActive()  // 每次循环检查协程是否已被取消
                                // 如果已取消，此处抛出 CancellationException
                heavyComputation(item)  // 纯 CPU 操作，没有挂起点
            }
        }
    }
 
    // ========== 场景 3：onCleared 中的清理陷阱 ==========
    override fun onCleared() {
        super.onCleared()
        // ⚠️ 错误做法：此时 viewModelScope 已经被取消
        // 下面这个协程启动后会立即收到 CancellationException，不会执行
        viewModelScope.launch {
            repository.saveCache()  // 不会执行！
        }
 
        // ✅ 正确做法 A：使用 NonCancellable 保证关键操作完成
        // 但需注意这里需要自行创建作用域，因为 viewModelScope 已取消
        CoroutineScope(Dispatchers.IO + NonCancellable).launch {
            repository.saveCache()  // 会执行，但不再响应取消
        }
 
        // ✅ 正确做法 B：对于非挂起的清理逻辑，直接在 onCleared 中同步执行
        repository.closeCacheSync()  // 同步关闭缓存
    }
}

class NewsViewModel(
    private val newsRepo: NewsRepository,   // 新闻数据源
    private val adsRepo: AdsRepository      // 广告数据源
) : ViewModel() {
 
    // UI 状态，使用 StateFlow 持有
    private val _uiState = MutableStateFlow<NewsUiState>(NewsUiState.Loading)
    val uiState: StateFlow<NewsUiState> = _uiState.asStateFlow()
 
    // ========== 策略 1：try-catch（最推荐） ==========
    fun loadNews() {
        viewModelScope.launch {
            // 使用 try-catch 包裹可能失败的挂起调用
            try {
                val news = newsRepo.fetchLatest()       // 可能抛出 IOException
                _uiState.value = NewsUiState.Success(news) // 成功时更新状态
            } catch (e: IOException) {
                // 网络异常被捕获，不会向上传播
                _uiState.value = NewsUiState.Error("网络错误: ${e.message}")
            }
            // CancellationException 不应捕获——它用于正常取消流程
            // 如果用 catch(e: Exception)，需手动 re-throw CancellationException
        }
    }
 
    // ========== 策略 2：CoroutineExceptionHandler ==========
    // 定义一个异常处理器，当协程内部未被 catch 的异常冒泡时触发
    private val exceptionHandler = CoroutineExceptionHandler { _, throwable ->
        // 这里在主线程执行（因为 viewModelScope 调度器是 Main.immediate）
        // 可以更新 UI 状态或做日志记录
        _uiState.value = NewsUiState.Error("未预期的错误: ${throwable.message}")
    }
 
    fun loadNewsWithHandler() {
        // 将 exceptionHandler 作为上下文元素传入 launch
        viewModelScope.launch(exceptionHandler) {
            // 此处故意不 try-catch
            val news = newsRepo.fetchLatest()  // 如果抛出异常...
            _uiState.value = NewsUiState.Success(news)
            // ...异常会被 exceptionHandler 捕获，而不是导致崩溃
        }
    }
 
    // ========== 策略 3：SupervisorJob 的隔离效果演示 ==========
    fun loadDashboard() {
        // 协程 A：加载新闻
        viewModelScope.launch {
            try {
                val news = newsRepo.fetchLatest()
                _uiState.value = NewsUiState.Success(news)
            } catch (e: Exception) {
                // 即使这里不 catch，协程 B 也不会被取消
                // 因为 viewModelScope 使用了 SupervisorJob
                _uiState.value = NewsUiState.Error(e.message ?: "")
            }
        }
 
        // 协程 B：加载广告（与协程 A 完全独立）
        viewModelScope.launch {
            // 协程 A 失败不影响此处执行
            val ads = adsRepo.fetchAds()  // 独立执行
            _adsState.value = ads         // 独立更新广告状态
        }
    }
 
    // ========== 陷阱：在 launch 内部使用 coroutineScope 会改变传播行为 ==========
    fun loadWithNestedScope() {
        viewModelScope.launch(exceptionHandler) {
            // coroutineScope 使用的是普通 Job（非 Supervisor）
            // 其内部任何子协程失败会取消整个 coroutineScope 块
            coroutineScope {
                // 子协程 X
                launch {
                    newsRepo.fetchLatest()  // 如果这里失败...
                }
                // 子协程 Y
                launch {
                    adsRepo.fetchAds()  // ...这里也会被取消！
                }
            }
            // 如果需要子协程互相隔离，应使用 supervisorScope 替代 coroutineScope
        }
    }
}

viewModelScope (SupervisorJob)
├── launch A（失败） → 异常不传播给父级 → 兄弟 B 不受影响
│                    → 如无 try-catch 且无 Handler → 应用崩溃
├── launch B（正常） → 继续运行 ✅
├── launch C
│   └── coroutineScope（普通 Job）
│       ├── launch X（失败） → 取消 Y → 取消整个 coroutineScope → 异常传给 C
│       └── launch Y（被连带取消）
└── launch D
    └── supervisorScope（SupervisorJob）
        ├── launch X（失败） → Y 不受影响 ✅
        └── launch Y（正常） → 继续运行 ✅

viewModelScope.launch {
    try {
        // 执行挂起操作
        someHeavyWork()
    } catch (e: CancellationException) {
        // ⚠️ 必须重新抛出，否则会破坏结构化并发的取消机制
        throw e
    } catch (e: Exception) {
        // 处理真正的业务异常
        _uiState.value = UiState.Error(e.message)
    }
}

class OrderViewModel : ViewModel() {
    fun placeOrder(order: Order) {
        viewModelScope.launch {
            coroutineScope {
                val payment = async { paymentService.charge(order) }
                val inventory = async { inventoryService.reserve(order) }
                processOrder(payment.await(), inventory.await())
            }
        }
    }
}

// ❌ 存在问题的写法
class MyActivity : AppCompatActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        // 在 lifecycleScope 中直接 collect
        lifecycleScope.launch {
            // viewModel.uiState 是一个 StateFlow
            viewModel.uiState.collect { state ->
                // 更新 UI
                updateUI(state)
            }
        }
    }
}

// ✅ 推荐写法
class MyActivity : AppCompatActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        // 在 lifecycleScope 中启动协程
        lifecycleScope.launch {
            // repeatOnLifecycle 是一个挂起函数，
            // 它会在生命周期到达 STARTED 时执行 block，
            // 降到 STARTED 以下（即 STOPPED）时取消 block，
            // 再次到达 STARTED 时重新执行 block。
            repeatOnLifecycle(Lifecycle.State.STARTED) {
                // 这个 block 内部拥有独立的 CoroutineScope
                // 每次"重启"都是一个全新的执行
                viewModel.uiState.collect { state ->
                    // 仅在 Activity 至少处于 STARTED 状态时更新 UI
                    updateUI(state)
                }
            }
            // ⚠️ 注意：代码执行到这里意味着 Lifecycle 已经 DESTROYED
            // 因为 repeatOnLifecycle 只有在 DESTROYED 时才会恢复（return）
        }
    }
}

repeatOnLifecycle(Lifecycle.State.STARTED) {
    // 并发收集多个 Flow——它们会同时启动、同时取消
    launch {
        // 收集 UI 状态流
        viewModel.uiState.collect { state ->
            updateUI(state)
        }
    }
    launch {
        // 收集导航事件流
        viewModel.navigationEvents.collect { event ->
            navigateTo(event)
        }
    }
}

// 简化的 repeatOnLifecycle 内部实现思路（非完整源码）
suspend fun Lifecycle.repeatOnLifecycle(
    state: Lifecycle.State,          // 目标状态，如 STARTED
    block: suspend CoroutineScope.() -> Unit // 需要重复执行的挂起代码块
) {
    // 如果当前生命周期已经是 DESTROYED，直接返回，不执行任何逻辑
    if (currentState === Lifecycle.State.DESTROYED) return
 
    // 使用 suspendCancellableCoroutine 将回调式的 Lifecycle 观察
    // 转换为挂起语义。外部协程会在这里挂起，直到 DESTROYED 时恢复。
    suspendCancellableCoroutine<Unit> { cont ->
        // 记录当前正在运行的子 Job，方便取消
        var launchedJob: Job? = null
 
        // 创建一个 LifecycleEventObserver 来监听生命周期变化
        val observer = LifecycleEventObserver { _, event ->
            // 当生命周期到达目标状态时（如 ON_START）
            if (event.targetState >= state) {
                // 如果还没有运行中的 Job，就启动一个新的子协程来执行 block
                if (launchedJob == null || launchedJob?.isCompleted == true) {
                    launchedJob = cont.context.job.let { parentJob ->
                        // 在当前协程的上下文中 launch 一个新的子协程
                        CoroutineScope(cont.context).launch {
                            block() // 执行用户传入的 block（如 Flow.collect）
                        }
                    }
                }
            }
            // 当生命周期降到目标状态以下时（如 ON_STOP）
            if (event.targetState < state) {
                // 取消正在运行的子 Job——这会取消 block 中的所有协程
                launchedJob?.cancel()
                launchedJob = null
            }
            // 当 ON_DESTROY 事件到达时，恢复外层挂起的 continuation
            if (event == Lifecycle.Event.ON_DESTROY) {
                cont.resume(Unit)
            }
        }
 
        // 注册观察者
        addObserver(observer)
 
        // 如果外层协程被取消（如 lifecycleScope 取消），移除观察者并取消子 Job
        cont.invokeOnCancellation {
            launchedJob?.cancel()
            removeObserver(observer)
        }
    }
}

class MyFragment : Fragment() {
    override fun onViewCreated(view: View, savedInstanceState: Bundle?) {
        super.onViewCreated(view, savedInstanceState)
        // ✅ 正确：使用 viewLifecycleOwner，它与 Fragment 的 View 生命周期绑定
        viewLifecycleOwner.lifecycleScope.launch {
            viewLifecycleOwner.repeatOnLifecycle(Lifecycle.State.STARTED) {
                viewModel.uiState.collect { state ->
                    // 安全地访问 binding / view
                    binding.textView.text = state.title
                }
            }
        }
 
        // ❌ 错误：使用 Fragment 自身的 lifecycleScope
        // Fragment 的生命周期 ≠ Fragment View 的生命周期
        // 当 Fragment 进入 back stack 时，View 被销毁但 Fragment 还活着
        // 此时 collect 中访问 binding 会导致 NPE / 崩溃
        lifecycleScope.launch {
            repeatOnLifecycle(Lifecycle.State.STARTED) {
                // ⚠️ 这里的 this 是 Fragment 的 Lifecycle，不是 View 的
            }
        }
    }
}

class MyActivity : AppCompatActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
 
        // 使用 flowWithLifecycle，代码更简洁
        lifecycleScope.launch {
            viewModel.uiState
                // flowWithLifecycle 在内部使用 repeatOnLifecycle
                // 当 Lifecycle 低于 STARTED 时上游被取消，
                // 回到 STARTED 时重新订阅上游
                .flowWithLifecycle(lifecycle, Lifecycle.State.STARTED)
                // 此处的 collect 只在 STARTED 以上状态时接收数据
                .collect { state ->
                    updateUI(state)
                }
        }
    }
}

// 简化的实现思路
fun <T> Flow<T>.flowWithLifecycle(
    lifecycle: Lifecycle,          // 要观察的生命周期
    minActiveState: Lifecycle.State = Lifecycle.State.STARTED // 最低活跃状态
): Flow<T> = callbackFlow {
    // 在 callbackFlow 内部调用 repeatOnLifecycle
    lifecycle.repeatOnLifecycle(minActiveState) {
        // 每次生命周期达到目标状态时，重新 collect 上游 Flow
        this@flowWithLifecycle.collect { value ->
            // 将上游的值发送到 callbackFlow 的 channel 中
            send(value)
        }
    }
    // repeatOnLifecycle 返回意味着 DESTROYED
    close() // 关闭 channel
}

// ❌ 错误：双重包装，语义重复且浪费资源
lifecycleScope.launch {
    repeatOnLifecycle(Lifecycle.State.STARTED) {
        viewModel.uiState
            .flowWithLifecycle(lifecycle, Lifecycle.State.STARTED) // 多余！
            .collect { state ->
                updateUI(state)
            }
    }
}

// 这三个 API 现已被标记为 @Deprecated
lifecycleScope.launchWhenCreated { /* ... */ }
lifecycleScope.launchWhenStarted { /* ... */ }
lifecycleScope.launchWhenResumed { /* ... */ }

// 使用 launchWhenStarted（挂起语义）
lifecycleScope.launchWhenStarted {
    viewModel.locationFlow.collect { location ->
        // 当 Activity 进入 STOPPED 状态时：
        // ⚠️ collect 被挂起，但上游 locationFlow 仍在生产数据！
        // 上游如果是 SharedFlow，数据会积压在缓冲区中
        // 上游如果是 Channel，数据也会缓存等待消费
        updateLocationUI(location)
    }
}
 
// 使用 repeatOnLifecycle（取消语义）
lifecycleScope.launch {
    repeatOnLifecycle(Lifecycle.State.STARTED) {
        viewModel.locationFlow.collect { location ->
            // 当 Activity 进入 STOPPED 状态时：
            // ✅ 整个 collect 被取消，上游 Flow 也随之停止
            // 没有数据积压，没有资源浪费
            updateLocationUI(location)
        }
    }
}

// ❌ 旧写法（已废弃）
lifecycleScope.launchWhenStarted {
    viewModel.uiState.collect { state ->
        updateUI(state)
    }
}
 
// ✅ 新写法（推荐）
lifecycleScope.launch {
    repeatOnLifecycle(Lifecycle.State.STARTED) {
        viewModel.uiState.collect { state ->
            updateUI(state)
        }
    }
}

@Composable
fun MyScreen(viewModel: MyViewModel = viewModel()) {
    // collectAsStateWithLifecycle 内部使用 repeatOnLifecycle
    // 当 Composable 所在的 Lifecycle 低于 STARTED 时停止收集
    // 回到 STARTED 时重新收集
    val uiState by viewModel.uiState.collectAsStateWithLifecycle()
 
    // 使用 uiState 构建 UI
    Text(text = uiState.title)
}

lifecycleScope.launch {
    repeatOnLifecycle(Lifecycle.State.STARTED) {
        viewModel.uiState.collect { state ->
            binding.textView.text = state.title
        }
    }
}

// suspendCancellableCoroutine 的简化签名
// T 是挂起后恢复时返回的结果类型
// block 是 lambda，接收一个 CancellableContinuation<T>，你在里面注册回调
public suspend inline fun <T> suspendCancellableCoroutine(
    crossinline block: (CancellableContinuation<T>) -> Unit // 拿到 continuation 引用
): T // 挂起后恢复时，返回值类型为 T

// 将 Google Task<T> 转换为 suspend 函数
// 调用方可以直接 val location = fusedClient.lastLocation.await()
suspend fun <T> Task<T>.await(): T {
    // 如果 Task 已经完成（缓存结果），无需挂起，直接返回
    if (isComplete) {
        // Task 成功完成时，返回结果
        val e = exception
        return if (e == null) {
            // 如果设置了 isCanceled 标志，抛出取消异常
            if (isCanceled) {
                throw CancellationException("Task $this was cancelled normally.")
            } else {
                // 安全地拿到结果（可能为 null，此时 T 应该是可空类型）
                @Suppress("UNCHECKED_CAST")
                result as T
            }
        } else {
            // Task 失败，将异常抛到协程中
            throw e
        }
    }
 
    // Task 尚未完成，需要真正挂起协程
    return suspendCancellableCoroutine { cont ->
        // 注册 Task 的完成监听器
        addOnCompleteListener { task ->
            // 回调触发时，检查 Task 状态
            val e = task.exception
            if (e == null) {
                // 成功分支
                @Suppress("UNCHECKED_CAST")
                if (task.isCanceled) {
                    // Task 被取消，对应协程也应取消
                    cont.cancel()
                } else {
                    // 正常恢复协程，传入结果值
                    cont.resume(task.result as T)
                }
            } else {
                // 失败分支：用异常恢复，协程挂起点会抛出此异常
                cont.resumeWithException(e)
            }
        }
 
        // 【关键】注册取消回调：协程被外部取消时，同步取消底层 Task
        // 这防止了协程已取消但 Task 还在跑的资源浪费
        cont.invokeOnCancellation {
            // 尝试取消 Task（参数 true 表示允许中断）
            // 注意：并非所有 Task 都支持取消，这里是 best-effort
            cancel()
        }
    }
}

// 将 Animator 转为 suspend 函数，等待动画播放完毕
// 调用方：myAnimator.awaitEnd()  // 挂起直到动画结束
suspend fun Animator.awaitEnd() {
    // 如果动画当前没在运行，直接返回，无需挂起
    if (!isRunning) return
 
    // 动画正在运行，挂起协程直到结束
    suspendCancellableCoroutine { cont ->
        // 创建监听器引用，后面取消时需要移除
        val listener = object : AnimatorListenerAdapter() {
            // 标记是否已恢复，防止 onEnd + onCancel 双重触发
            private var resumed = false
 
            // 动画正常结束
            override fun onAnimationEnd(animation: Animator) {
                // 移除自身监听，避免内存泄漏
                animation.removeListener(this)
                if (!resumed) {
                    resumed = true
                    // 恢复协程，返回 Unit
                    cont.resume(Unit)
                }
            }
 
            // 动画被外部取消（如 animator.cancel()）
            override fun onAnimationCancel(animation: Animator) {
                // 移除自身监听
                animation.removeListener(this)
                if (!resumed) {
                    resumed = true
                    // 动画取消也视为协程取消
                    cont.cancel()
                }
            }
        }
 
        // 注册监听器
        addListener(listener)
 
        // 协程被取消时，同步取消动画并移除监听
        cont.invokeOnCancellation {
            // 取消动画播放（会触发 onAnimationCancel -> 但 resumed 已被设置）
            cancel() // Animator.cancel()
            // 确保监听器被移除
            removeListener(listener)
        }
    }
}

// 挂起直到 View 完成下一次布局
// 调用方：view.awaitNextLayout()  之后就能安全读取 view.width/height
suspend fun View.awaitNextLayout() {
    suspendCancellableCoroutine { cont ->
        // 创建布局监听器
        val listener = object : View.OnLayoutChangeListener {
            override fun onLayoutChange(
                v: View, // 发生布局变化的 View
                left: Int, top: Int, right: Int, bottom: Int,    // 新位置
                oldLeft: Int, oldTop: Int, oldRight: Int, oldBottom: Int // 旧位置
            ) {
                // 布局完成，立即移除监听（一次性）
                v.removeOnLayoutChangeListener(this)
                // 恢复协程
                cont.resume(Unit)
            }
        }
 
        // 注册布局变化监听
        addOnLayoutChangeListener(listener)
 
        // 协程取消时移除监听，避免泄漏
        cont.invokeOnCancellation {
            removeOnLayoutChangeListener(listener)
        }
    }
}

// resume 传入一个需要手动关闭的资源
// 如果恢复瞬间协程被取消，尾部 lambda 负责关闭资源
suspendCancellableCoroutine { cont ->
    openConnectionAsync { connection ->
        // resume 并附带取消清理逻辑
        cont.resume(connection) { cause ->
            // 这个 lambda 仅在 resume 与 cancel 竞态时触发
            // cause 是取消的原因（CancellationException）
            connection.close() // 确保连接不泄漏
        }
    }
}

// 将 OkHttp Call 转换为 suspend 函数
// 调用方：val response = client.newCall(request).await()
suspend fun Call.await(): Response {
    return suspendCancellableCoroutine { cont ->
        // 注册取消回调：协程取消时，取消 HTTP 请求
        // 这会导致 onFailure 被回调，传入 IOException
        cont.invokeOnCancellation {
            // Call.cancel() 是线程安全的，可在任意线程调用
            cancel()
        }
 
        // 发起异步请求
        enqueue(object : Callback {
            // HTTP 请求成功
            override fun onResponse(call: Call, response: Response) {
                // 通过 resume 恢复协程，传入 Response 对象
                cont.resume(response) {
                    // 竞态保护：如果 resume 瞬间协程被取消
                    // Response body 必须关闭，否则连接泄漏
                    response.body?.close()
                }
            }
 
            // HTTP 请求失败（包括被 cancel 触发的 IOException）
            override fun onFailure(call: Call, e: IOException) {
                // 检查 continuation 是否还活着
                // 如果协程已取消，cont 处于 CANCELLED 状态
                // resumeWithException 会被忽略（不会抛 IllegalStateException）
                if (cont.isActive) {
                    // 用异常恢复协程
                    cont.resumeWithException(e)
                }
            }
        })
    }
}

// 超时保护示例：配合 withTimeout 使用
// 如果 5 秒内回调没触发，withTimeout 会取消协程
// invokeOnCancellation 会清理监听器
val result = withTimeout(5000L) {
    suspendCancellableCoroutine { cont ->
        // 注册回调...
        someApi.registerCallback { value ->
            cont.resume(value)   // 正常路径恢复
        }
        cont.invokeOnCancellation {
            someApi.unregisterCallback() // 超时取消时清理
        }
    }
}

// ❌ 错误示例：非原子的 check-then-act
var hasResumed = false // 共享可变状态，非线程安全
 
suspendCancellableCoroutine { cont ->
    someApi.onResult { value ->
        if (!hasResumed) {      // 线程 A 读到 false
            hasResumed = true   // 线程 B 也可能同时读到 false
            cont.resume(value)  // 两个线程都尝试 resume → 崩溃
        }
    }
}
 
// ✅ 正确做法：利用 cont 自身的原子性
suspendCancellableCoroutine { cont ->
    someApi.onResult { value ->
        // tryResume 是原子操作，失败返回 null
        val token = cont.tryResume(value)
        if (token != null) {
            // 只有成功 tryResume 的线程才能 completeResume
            cont.completeResume(token)
        }
    }
}

// PermissionManager: 将权限请求封装为 suspend 函数
// 使用方式：val granted = permissionManager.requestPermission(Manifest.permission.CAMERA)
class PermissionManager(private val activity: ComponentActivity) {
 
    // 保存当前的 continuation 引用（一次只能有一个权限请求在进行）
    private var continuation: CancellableContinuation<Boolean>? = null
 
    // 注册 ActivityResultLauncher（必须在 CREATED 之前注册）
    private val launcher = activity.registerForActivityResult(
        ActivityResultContracts.RequestPermission()
    ) { isGranted: Boolean ->
        // 权限结果回调：resume 协程并传入授权结果
        continuation?.resume(isGranted)
        // 清除引用，避免泄漏
        continuation = null
    }
 
    // 挂起函数：请求权限并返回是否授权
    suspend fun requestPermission(permission: String): Boolean {
        return suspendCancellableCoroutine { cont ->
            // 保存 continuation 引用供回调使用
            continuation = cont
 
            // 协程取消时清理引用
            cont.invokeOnCancellation {
                continuation = null
            }
 
            // 启动系统权限对话框
            launcher.launch(permission)
        }
    }
}
 
// 在 Activity 中的使用示例
// lifecycleScope.launch {
//     val manager = PermissionManager(this@MainActivity)
//     val granted = manager.requestPermission(Manifest.permission.CAMERA)
//     if (granted) {
//         openCamera()  // 直接顺序执行，无需回调
//     } else {
//         showRationale()
//     }
// }

// 创建一个全局异常处理器
// CoroutineExceptionHandler 接收两个参数：CoroutineContext 和 Throwable
val exceptionHandler = CoroutineExceptionHandler { context, throwable ->
    // context: 发生异常的协程上下文，可从中获取 Job、CoroutineName 等信息
    // throwable: 未捕获的异常实例
    
    // 获取协程名称用于日志追踪（如果设置了 CoroutineName）
    val coroutineName = context[CoroutineName]?.name ?: "unnamed"
    
    // 实际项目中通常会上报到 Crashlytics/Sentry 等平台
    Log.e("CoroutineError", "协程 [$coroutineName] 发生未捕获异常", throwable)
    
    // 注意：此处不能恢复协程，只能做善后处理
}

class MyViewModel : ViewModel() {
    // 正确做法：Handler 安装在 viewModelScope.launch 的上下文中
    // viewModelScope.launch 启动的是根协程
    fun loadData() {
        viewModelScope.launch(exceptionHandler) {
            // 此处的异常会被 exceptionHandler 捕获
            val data = repository.fetchData()  // 假设这里抛出 IOException
            
            // 即使嵌套 launch，异常依然会传播到根协程的 Handler
            launch {
                // 这里的异常同样会被上层的 exceptionHandler 捕获
                processData(data)
            }
        }
    }
    
    // 错误做法：Handler 安装在子协程上
    fun loadDataWrong() {
        viewModelScope.launch {
            // ❌ 错误！Handler 安装在子协程上不会生效
            // 异常会继续向上传播到 viewModelScope
            launch(exceptionHandler) {
                throw RuntimeException("This won't be caught by handler!")
            }
        }
    }
}

viewModelScope.launch(exceptionHandler) {
    // async 返回 Deferred，异常被暂存
    val deferred = async {
        throw IllegalStateException("Async 内部异常")
    }
    
    // 场景1：调用 await()，异常在此处抛出
    // 可以用 try-catch 在这里捕获
    try {
        val result = deferred.await()  // 异常在此重新抛出
    } catch (e: IllegalStateException) {
        Log.w("TAG", "捕获到 async 异常: ${e.message}")
    }
    
    // 场景2：如果不调用 await()，且 async 协程已失败
    // 异常会在 async 协程完成时传播，最终触发 exceptionHandler
}

// 在 Application.onCreate 中设置（生产环境的常见模式）
class MyApplication : Application() {
    override fun onCreate() {
        super.onCreate()
        
        // 保存原有的 Handler 以便链式调用
        val defaultHandler = Thread.getDefaultUncaughtExceptionHandler()
        
        Thread.setDefaultUncaughtExceptionHandler { thread, throwable ->
            // 上报到 Crashlytics（示例）
            // Firebase.crashlytics.recordException(throwable)
            
            Log.e("GlobalCrash", "线程 ${thread.name} 发生未捕获异常", throwable)
            
            // 调用原有 Handler，通常会终止进程
            defaultHandler?.uncaughtException(thread, throwable)
        }
    }
}

// 使用 supervisorScope 实现并行网络请求，互不影响
suspend fun loadDashboard(): DashboardData {
    // supervisorScope 创建一个 SupervisorJob 作用域
    // 内部子协程的失败相互隔离
    return supervisorScope {
        // 三个独立的网络请求并行执行
        // 使用 async 启动，方便获取结果或捕获异常
        
        val userDeferred = async {
            // 获取用户信息，可能失败
            userRepository.getCurrentUser()
        }
        
        val feedDeferred = async {
            // 获取动态流，可能失败
            feedRepository.getLatestFeed()
        }
        
        val notificationDeferred = async {
            // 获取通知数量，可能失败
            notificationRepository.getUnreadCount()
        }
        
        // 分别处理每个请求的结果
        // 使用 runCatching 将异常转换为 Result 类型
        val user = runCatching { userDeferred.await() }.getOrNull()
        val feed = runCatching { feedDeferred.await() }.getOrDefault(emptyList())
        val unreadCount = runCatching { notificationDeferred.await() }.getOrDefault(0)
        
        // 即使部分请求失败，也能返回部分有效数据
        DashboardData(user, feed, unreadCount)
    }
}

class DashboardViewModel : ViewModel() {
    // viewModelScope 源码简化版：
    // val viewModelScope = CoroutineScope(SupervisorJob() + Dispatchers.Main.immediate)
    // ⬆️ 注意这里使用的是 SupervisorJob
    
    private val _uiState = MutableStateFlow<UiState>(UiState.Loading)
    val uiState: StateFlow<UiState> = _uiState
    
    fun loadAllData() {
        // 这两个协程相互独立，一个失败不影响另一个
        viewModelScope.launch {
            try {
                val user = userRepository.getUser()
                _uiState.value = UiState.Success(user)
            } catch (e: Exception) {
                // 这个异常不会取消下面的 launch
                _uiState.value = UiState.Error(e.message)
            }
        }
        
        viewModelScope.launch {
            // 即使上面的协程抛出异常，这里依然会执行
            analyticsTracker.trackPageView("dashboard")
        }
    }
}

viewModelScope.launch(exceptionHandler) {
    supervisorScope {
        launch {
            // ❌ 这个异常不会取消兄弟协程
            // 但依然会触发 exceptionHandler
            throw IOException("网络错误")
        }
        
        launch {
            // ✅ 这个协程会继续执行
            delay(1000)
            Log.d("TAG", "我不受影响")
        }
    }
}
 
// 更安全的写法：在每个子协程内部处理异常
viewModelScope.launch {
    supervisorScope {
        launch {
            // ✅ 推荐：在子协程内部 try-catch
            try {
                riskyOperation()
            } catch (e: Exception) {
                Log.e("TAG", "操作失败，但不影响其他任务", e)
            }
        }
        
        launch {
            // 其他任务正常进行
            safeOperation()
        }
    }
}