Kotlin Academy · 课时

withTimeout 与 withTimeoutOrNull

Q: 「withTimeout 与 withTimeoutOrNull」这节课中我会学到什么？

使用超时包装器限制执行时间，并处理 TimeoutCancellationException。 你通过在浏览器中直接运行的动手代码来练习 Kotlin Academy，全天候 AI 导师会在你学习这节课的过程中回答你的问题。

使用超时包装器限制执行时间，并处理 TimeoutCancellationException。

withTimeout 与 withTimeoutOrNull 是 CoddyKit 上的免费 Kotlin Academy 课时。这是第 2 节课，共 4 节。你可以在下方免费阅读本课时的完整内容 — 然后在浏览器中使用内置代码编辑器和全天候 AI 导师进行实践。这是 Kotlin Academy 学习路径的一部分，你的进度在网页和 CoddyKit 应用中同步。 Kotlin Academy 课程共包含 4 节课。

为什么需要超时

协程可能会在网络或输入输出操作上无限期挂起。如果代码块未能在给定的毫秒数内完成，withTimeout 会取消该代码块。

import kotlinx.coroutines.*
fun main() = runBlocking {
    try {
        withTimeout(200) {
            delay(1000)  // simulates slow network
            println("This never prints")
        }
    } catch (e: TimeoutCancellationException) {
        println("Timed out!")
    }
}

withTimeout 基础

如果代码块超出时间限制，withTimeout(millis) { ... } 会抛出 TimeoutCancellationException（它是 CancellationException 的子类）。

import kotlinx.coroutines.*
suspend fun fetchData(): String {
    delay(100)
    return "data"
}
fun main() = runBlocking {
    val result = withTimeout(500) {
        fetchData()
    }
    println(result) // data
}

withTimeoutOrNull

超时时，withTimeoutOrNull 会返回 null，而不是抛出异常，因此可以更轻松地将超时作为正常流程处理。

import kotlinx.coroutines.*
fun main() = runBlocking {
    val result: String? = withTimeoutOrNull(200) {
        delay(1000)
        "done"
    }
    println(result ?: "Timeout — using default")
}

带返回值的超时

成功时，这两个函数都会返回代码块中最后一个表达式的值。

import kotlinx.coroutines.*
fun main() = runBlocking {
    val response = withTimeoutOrNull(500) {
        delay(100)
        mapOf("status" to 200, "body" to "OK")
    }
    println(response?.get("status")) // 200
}

嵌套超时

内部超时会先到期。只有在内部超时没有先取消的情况下，外部超时才会触发——这对于分别设置每次请求的超时和全局超时很有用。

import kotlinx.coroutines.*
fun main() = runBlocking {
    withTimeoutOrNull(1000) {       // global
        withTimeoutOrNull(200) {    // per-call
            delay(300)
            println("inner done")  // won't print
        } ?: println("Inner timed out")
        delay(100)
        println("outer still running")
    }
}

TimeoutCancellationException

TimeoutCancellationException 属于 CancellationException，因此协程机制会将其视为正常取消，不会将其传播到父作用域。

import kotlinx.coroutines.*
fun main() = runBlocking {
    val job = launch {
        try {
            withTimeout(100) { delay(1000) }
        } catch (e: TimeoutCancellationException) {
            println("Caught in child: ${e.message}")
        }
    }
    job.join()
    println("Parent still running: ${isActive}")
}

超时时的资源清理

请在 withTimeout 内使用 finally，以便即使时间耗尽也能释放资源。

import kotlinx.coroutines.*
fun main() = runBlocking {
    val result = withTimeoutOrNull(150) {
        try {
            println("Opening resource")
            delay(300)
            "result"
        } finally {
            println("Closing resource") // always runs
        }
    }
    println("Result: $result")
}

带超时的重试

可以将超时与重试逻辑结合起来：为每次尝试设置单独的超时时间，并在结果为空时重试。

import kotlinx.coroutines.*
suspend fun tryFetch(attempt: Int): String? = withTimeoutOrNull(200) {
    delay(if (attempt < 3) 300L else 100L) // fails first 2 attempts
    "success on attempt $attempt"
}
fun main() = runBlocking {
    var result: String? = null
    var attempt = 1
    while (result == null) {
        result = tryFetch(attempt++)
    }
    println(result)
}

ViewModel 中的 withTimeout

在安卓 ViewModel 中，请在 viewModelScope.launch 内使用 withTimeoutOrNull 包装仓库调用，以便在响应缓慢时显示错误状态。

import kotlinx.coroutines.*
// Pseudocode pattern:
suspend fun loadUser(): String = withTimeoutOrNull(3000) {
    // repo.getUser()
    delay(100)
    "Alice"
} ?: "Timeout — using cached data"
fun main() = runBlocking { println(loadUser()) }

准确性注意事项

withTimeout 依赖协程调度器。在使用 TestCoroutineScheduler 的测试中，时间是虚拟的，可以手动推进。

import kotlinx.coroutines.*
// In unit tests with runTest:
// runTest {
//     withTimeout(1000) {
//         delay(999)  // virtual time — completes instantly
//         println("done")
//     }
// }
fun main() = runBlocking {
    println("Use runTest for virtual-time timeout testing")
}

如何在两者之间选择

当超时表示错误时，请使用 withTimeout。当超时是预期结果时，请使用 withTimeoutOrNull（例如缓存未命中或可选的预取）。

import kotlinx.coroutines.*
fun main() = runBlocking {
    // Mandatory: throw on timeout
    // withTimeout(500) { criticalOp() }

    // Optional: null on timeout
    val cached = withTimeoutOrNull(50) {
        delay(200); "fresh"
    } ?: "stale"
    println(cached)
}

快速检查

当代码块超过时间限制时，withTimeoutOrNull 会返回什么？

回顾

withTimeout 超时时会抛出异常；withTimeoutOrNull 会返回 null。两者都会协作式地取消代码块，并执行 finally 块。请使用 finally 清理资源，并在超时属于预期结果时使用 withTimeoutOrNull。

常见问题解答

「withTimeout 与 withTimeoutOrNull」课时是免费的吗？

是的 — 「withTimeout 与 withTimeoutOrNull」的完整文本可在网页上免费阅读。要进行交互式练习（内置代码编辑器和全天候 AI 导师）并解锁 Kotlin Academy 课程的其余内容，请升级到 CoddyKit PRO。 Kotlin Academy 课程共包含 4 节课。

「withTimeout 与 withTimeoutOrNull」这节课中我会学到什么？

使用超时包装器限制执行时间，并处理 TimeoutCancellationException。你通过在浏览器中直接运行的动手代码来练习 Kotlin Academy，全天候 AI 导师会在你学习这节课的过程中回答你的问题。

学习 Kotlin Academy 需要有经验吗？

无需任何先前经验。CoddyKit 上的 Kotlin Academy 课程适合初学者到高级学习者，你可以从这里开始或从头开始，按照自己的节奏学习。这是第 2 节课，共 4 节。

「withTimeout 与 withTimeoutOrNull」课时需要多长时间？

大多数 CoddyKit 课程大约需要 5–10 分钟。每节课都很精短且互动，所以你能稳步进步，并在网页和应用中从离开的地方继续。

我能在这节 Kotlin Academy 课中编写并运行代码吗？

能。每节 Kotlin Academy 课都包含内置代码编辑器，你可以在浏览器中直接编写并运行真实代码，并获得即时 AI 反馈 — 无需本地设置。

此课程中的所有课时

← 返回 Kotlin Academy