runBlocking：阻塞边界与设计目的

协程的世界观是结构化并发：一切 suspend 函数在协程作用域内运行，取消自动传播，异常统一处理。但现实世界中存在一些硬性边界，使得协程无法完全接管调用链的起点：

JVM main 函数

入口签名固定为 fun main(args: Array<String>)，无法声明为 suspend 函数。JVM 进程需要 main 线程阻塞等待，否则进程会提前退出。

单元测试框架

JUnit / TestNG 等框架不识别 suspend 函数。测试方法必须返回 void 或返回非 suspend 类型，框架通过阻塞等待来感知测试是否通过。

遗留同步 API 集成

第三方库的回调 / 接口签名为同步，且因为历史包袱无法重构为协程。调用方必须给出一个同步结果。

在这三个场景中，外部环境强制要求阻塞等待。runBlocking 的价值就在于：以最小代价适配这个约束，同时在内部完整保留协程的结构化并发、取消机制和异常传播能力。

JUnit 测试方法不能声明为 suspend，但测试内部需要调用 suspend 函数、使用协程超时控制。runBlocking 提供了最自然的解决方案：

class UserRepositoryTest {

    // JUnit 测试方法不能声明为 suspend
    @Test
    fun `should fetch user correctly`() = runBlocking {
        // 在阻塞边界内，正常使用协程生态
        val repository = UserRepository()

        // 可以正常调用 suspend 函数
        val user = repository.fetchUser(id = "123")

        // 可以使用协程特有的超时控制
        withTimeout(3000) {
            assertEquals("Alice", user.name)
        }
    }
    // runBlocking 阻塞测试线程，直到协程完成或超时
    // 测试框架能正确感知测试是否通过
}

如果不使用 runBlocking，你可能会写出这样的丑陋代码：

// 反模式：手动阻塞等待协程完成
@Test
fun `bad test example`() {
    val latch = CountDownLatch(1)
    var result: User? = null
    var error: Throwable? = null

    GlobalScope.launch {  // 脱离了结构化并发！
        try {
            result = repository.fetchUser("123")
        } catch (e: Exception) {
            error = e
        } finally {
            latch.countDown()
        }
    }

    latch.await(5, TimeUnit.SECONDS)  // 阻塞等待
    // 问题：异常传播不自然、超时控制粗糙、协程可能泄漏
    error?.let { throw it }
    assertEquals("Alice", result?.name)
}

Kotlin 的 main 函数入口签名固定，不能声明为 suspend。runBlocking 是最标准的入口包装方式：

fun main() = runBlocking {
    // 在阻塞边界内，正常使用 suspend 函数
    val user = repository.fetchUser("123")
    println(user)

    // 还能使用完整的协程能力
    withTimeout(5000) {
        val detail = repository.fetchDetail(user.id)
        println(detail)
    }
}
// main 线程阻塞直到所有协程完成
// JVM 进程不会提前退出

假设有一个历史遗留的同步回调接口，你无法修改它的签名，但内部实现需要用到协程生态：

// 第三方库定义的同步接口（无法修改）
interface LegacyCallback {
    fun onDataRequested(requestId: String): String  // 同步！
}

// 你的实现中需要调用协程生态（suspend 函数）
class ModernImpl(private val repository: UserRepository) : LegacyCallback {

    override fun onDataRequested(requestId: String): String = runBlocking {
        // 在同步接口内部，无缝使用协程
        val user = withContext(Dispatchers.IO) {
            repository.fetchUser(requestId)
        }

        // 还可以使用协程的超时、重试等能力
        withTimeout(3000) {
            repository.fetchDetail(user.id)
        }

        user.name  // 返回给同步调用方
    }
}

很多新手会在 main 函数中尝试用 GlobalScope.launch，然后困惑为什么协程没执行完进程就退出了。下面直接对比两者差异：

runBlocking 的等待时间等于其协程树中所有未完成分支的最大耗时，前提是这些分支能够并发挂起或并行执行。若受限于单线程且存在非挂起阻塞，则退化为累加耗时。此外，任何子协程的异常或取消都会使等待提前终止。

下面用三个实验来验证这个规则：

fun main() {
    // 实验1：纯挂起 —— 等待时间 = max
    val t1 = measureTimeMillis {
        runBlocking {
            launch { delay(2000) }
            launch { delay(3000) }
            launch { delay(1000) }
        }
    }
    println("纯挂起: ${t1}ms")  // ≈ 3000ms

    // 实验2：CPU密集 + 单线程 —— 等待时间 = sum
    val t2 = measureTimeMillis {
        runBlocking(newSingleThreadContext("single")) {
            launch { Thread.sleep(2000) } // 非挂起阻塞！
            launch { Thread.sleep(3000) }
            launch { Thread.sleep(1000) }
        }
    }
    println("CPU密集+单线程: ${t2}ms")  // ≈ 6000ms

    // 实验3：CPU密集 + 多线程 —— 等待时间 = max
    val t3 = measureTimeMillis {
        runBlocking(Dispatchers.Default) {
            launch { Thread.sleep(2000) }
            launch { Thread.sleep(3000) }
            launch { Thread.sleep(1000) }
        }
    }
    println("CPU密集+多线程: ${t3}ms")  // ≈ 3000ms
}

下面用对比图直观展示单线程阻塞与多线程/挂起并发的差异：

当在线程池受限的环境中，嵌套切换到同一调度器时，会导致永久阻塞：

val singleThread = newSingleThreadContext("limited")

runBlocking(singleThread) {
    // 外层占用了唯一线程并阻塞等待

    // withContext 试图获取同一调度器的线程 → 永远拿不到 → 死锁
    withContext(singleThread) {
        delay(1000)
    }
}

用泳道图直观展示这个死锁过程：

Android 主线程本质上就是一个容量为 1 的单线程调度器。如果在主线程调用 runBlocking：

• 主线程被阻塞：UI 事件、触摸、渲染全部冻结 → ANR
• 调度器嵌套死锁：如果内部再切回主线程（如 withContext(Dispatchers.Main)），形成与上面完全相同的死锁模式
• 没有任何好处：协程的生命周期管理完全可以用 lifecycleScope / viewModelScope 替代

runBlocking 对 Thread.interrupt() 有正确的协程语义映射，这是它优于 Future.get() / CountDownLatch.await() 的关键原因：

val job = thread {
    runBlocking {
        try {
            delay(Long.MAX_VALUE)  // 等待很久很久...
        } catch (e: CancellationException) {
            // Thread.interrupt() 自动转换为 CancellationException
            // → 触发结构化取消，所有子协程一并清理
            println("协程被正确取消，资源已清理")
        }
    }
}

// 外部通过 interrupt 取消
job.interrupt()
// runBlocking 收到中断信号 → 抛出 CancellationException
// → 协程树中的所有子协程收到取消 → 全部清理
// → runBlocking 返回 → 线程安全退出

下面的对比表格展示了 runBlocking 在中断处理上的优势：

下面用代码展示如果用 Future.get() 替代 runBlocking，中断处理会有多麻烦：

// 反模式：用 Future 阻塞等待协程
val executor = Executors.newSingleThreadExecutor()
val future = executor.submit<String> {
    runBlocking {
        // 协程任务...
        delay(5000)
        "result"
    }
}

// 外部中断
thread {
    Thread.sleep(1000)
    future.cancel(true)  // 发送中断信号
}

try {
    val result = future.get()  // 阻塞等待
} catch (e: CancellationException) {
    // 问题：协程内部的资源清理不受此控制
    // Future.cancel 只是 interrupt 线程，内部 runBlocking 的协程树清理
    // 依赖于 runBlocking 自身的 interrupt → CancellationException 映射
    // 如果你直接用 Thread.sleep + Future.get，根本没有这个映射
} finally {
    executor.shutdownNow()  // 暴力关闭，可能导致资源泄漏
}

任何子协程的异常或取消都会使 runBlocking 的等待提前终止。这意味着 runBlocking 内部是一个完整的结构化并发域：

fun main() = runBlocking {
    val job1 = launch {
        delay(1000)
        throw RuntimeException("子协程异常！")
    }

    val job2 = launch {
        delay(5000)
        println("这条日志永远不会打印")  // 因为父协程已被取消
    }

    // job1 在 1000ms 后抛出异常
    // → 异常向上传播到 runBlocking 的 scope
    // → scope 取消，job2 收到 CancellationException
    // → runBlocking 立即返回（≈ 1000ms 后，而非 5000ms）
    // → 异常继续向上抛给 main 线程
}