Kotlin Academy · 课时

创建自定义异常类

Q: 「创建自定义异常类」这节课中我会学到什么？

定义领域专用异常，并为其提供有意义的消息和属性。 你通过在浏览器中直接运行的动手代码来练习 Kotlin Academy，全天候 AI 导师会在你学习这节课的过程中回答你的问题。

定义领域专用异常，并为其提供有意义的消息和属性。

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

为什么需要自定义异常

自定义异常可以表达领域含义：调用方可以针对性地捕获它们，获取有用的消息，并根据类型采取不同的操作。

最简单的自定义异常

继承 Exception（或 RuntimeException 等具体子类），并将消息传递给父类构造函数。

class InvalidEmailException(message: String) : Exception(message)
fun main() {
    try {
        throw InvalidEmailException("missing @")
    } catch (e: InvalidEmailException) {
        println("caught: ${e.message}")
    }
}

带属性的异常

添加字段来传递上下文信息，例如 HTTP 状态、字段名称和重试次数等。

class HttpError(
    message: String,
    val statusCode: Int
) : Exception(message)
fun main() {
    try {
        throw HttpError("Not Found", 404)
    } catch (e: HttpError) {
        println("HTTP ${e.statusCode}: ${e.message}")
    }
}

带原因的异常

传入 cause，以便在异常链中保留原始异常。

class DatabaseError(message: String, cause: Throwable) : Exception(message, cause)
fun main() {
    try {
        try { error("connection refused") }
        catch (e: Throwable) { throw DatabaseError("query failed", e) }
    } catch (e: DatabaseError) {
        println("${e.message} (caused by: ${e.cause?.message})")
    }
}

受检异常与非受检异常

Kotlin 将所有异常视为非受检异常（不要求声明 throws）。按照惯例，请继承 RuntimeException。

class ValidationException(field: String, message: String) :
    RuntimeException("[$field] $message")
fun main() {
    try {
        throw ValidationException("age", "must be positive")
    } catch (e: ValidationException) {
        println(e.message)
    }
}

领域异常层次结构

构建层次结构后，调用方可以捕获基类型进行常规处理，也可以捕获具体子类型处理特殊情况。

open class AppException(message: String) : RuntimeException(message)
class NotFoundException(what: String) : AppException("$what not found")
class UnauthorizedException : AppException("not authorized")
fun main() {
    val errors = listOf(NotFoundException("user"), UnauthorizedException())
    for (e in errors) {
        try { throw e }
        catch (e: AppException) { println("App error: ${e.message}") }
    }
}

密封异常层次结构

对于一组封闭的错误类型，请使用 sealed 层次结构，这样调用方就能穷举处理每一种变体。

sealed class ApiError(message: String) : RuntimeException(message) {
    class Timeout : ApiError("timeout")
    class NotFound(val id: String) : ApiError("not found: $id")
    class ServerError(val status: Int) : ApiError("server returned $status")
}
fun describe(e: ApiError) = when (e) {
    is ApiError.Timeout -> "request timed out"
    is ApiError.NotFound -> "id ${e.id} missing"
    is ApiError.ServerError -> "5xx: ${e.status}"
}
fun main() {
    println(describe(ApiError.NotFound("user-42")))
}

命名约定

为清晰起见，自定义异常类的名称应以 Exception 或 Error 结尾。请使用过去时形式或名词，例如 NotFound、InvalidInput。

class InvalidInputException(msg: String) : RuntimeException(msg)
class UserNotFoundException(id: Int) : RuntimeException("user $id not found")
fun main() {
    try { throw UserNotFoundException(7) }
    catch (e: UserNotFoundException) { println(e.message) }
}

记录异常文档

使用 KDoc 的 @throws 记录函数可能抛出的异常。

/**
 * @throws InvalidEmailException if the email is malformed
 */
fun validate(email: String) {
    if ("@" !in email) throw InvalidEmailException("missing @")
}
class InvalidEmailException(m: String) : RuntimeException(m)
fun main() {
    try { validate("nope") }
    catch (e: InvalidEmailException) { println(e.message) }
}

避免过度使用异常

异常用于异常情况。对于预期结果（例如输入为空、缺少可选字段），优先使用可空返回值、密封结果类型或默认值。

fun findUser(id: Int): String? = if (id == 1) "Alice" else null
fun main() {
    val name = findUser(42) ?: "(unknown)"
    println(name) // (unknown), no exception
}

实际示例

一个虚构 API 客户端的实际自定义异常示例，其中包含状态和响应体。

class ApiException(
    message: String,
    val statusCode: Int,
    val responseBody: String
) : RuntimeException(message)
fun main() {
    try {
        throw ApiException("Bad Request", 400, "{\"error\":\"invalid\"}")
    } catch (e: ApiException) {
        println("[${e.statusCode}] ${e.message}: ${e.responseBody}")
    }
}

快速检查

定义领域专用的 Kotlin 异常时，最常用的父类是什么？

回顾

自定义异常可以表达领域含义。请继承 RuntimeException 或 Exception，添加属性来提供上下文信息，保留异常原因，并构建层次结构以支持分组捕获。对于封闭的类型集合，请使用密封异常；当错误可预期时，优先使用可空类型或结果类型。

常见问题解答

「创建自定义异常类」课时是免费的吗？

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

「创建自定义异常类」这节课中我会学到什么？

定义领域专用异常，并为其提供有意义的消息和属性。你通过在浏览器中直接运行的动手代码来练习 Kotlin Academy，全天候 AI 导师会在你学习这节课的过程中回答你的问题。

学习 Kotlin Academy 需要有经验吗？

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

「创建自定义异常类」课时需要多长时间？

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

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

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

此课程中的所有课时

← 返回 Kotlin Academy