异常与错误处理

// 创建一个基础的 Throwable 实例（实际开发中极少直接使用）
val t = Throwable("something went wrong")  // message 参数
println(t.message)       // 输出: something went wrong
println(t.cause)         // 输出: null（没有包装其他异常）
t.printStackTrace()      // 打印完整的调用栈信息到标准错误流

// 常见的 RuntimeException 子类演示
fun divide(a: Int, b: Int): Int {
    // 当 b 为 0 时，主动抛出 IllegalArgumentException（RuntimeException 的子类）
    require(b != 0) { "Divisor must not be zero" }
    return a / b
}
 
fun main() {
    // ArithmeticException —— 也是 RuntimeException 的子类
    // 如果没有 require 守卫，JVM 会在除零时自动抛出它
    val result = divide(10, 2)  // 正常返回 5
    println(result)
 
    // 触发 IllegalArgumentException
    // divide(10, 0)  // 抛出: java.lang.IllegalArgumentException: Divisor must not be zero
}

// 演示 StackOverflowError（Error 的子类）
fun infiniteRecursion(): Nothing {
    // 无终止条件的递归，每次调用都会在栈上压入新的帧
    // 最终栈空间耗尽，JVM 抛出 StackOverflowError
    return infiniteRecursion()
}
 
// 调用 infiniteRecursion() 会导致:
// Exception in thread "main" java.lang.StackOverflowError

// Java 风格（啰嗦）
var value: Int
try {
    value = "123".toInt()  // 可能抛出 NumberFormatException
} catch (e: NumberFormatException) {
    value = 0
}
 
// Kotlin 风格（try 作为表达式，直接返回值）
val value2 = try {
    "123".toInt()          // 成功时返回解析结果
} catch (e: NumberFormatException) {
    0                      // 失败时返回默认值
}

┌─────────────────────────────────────────┐
│         Throwable 对象 (堆内存)           │
├─────────────────────────────────────────┤
│  message: String? ──→ "file not found"  │
│  cause: Throwable? ──→ null             │
│  stackTrace: Array<StackTraceElement>   │
│    ├─ [0] MyClass.readFile(Main.kt:42)  │
│    ├─ [1] MyClass.process(Main.kt:28)   │
│    └─ [2] MainKt.main(Main.kt:5)       │
└─────────────────────────────────────────┘

// 高性能场景下的轻量异常（跳过昂贵的栈捕获）
class LightweightException(message: String) : Exception(message) {
    // 覆写 fillInStackTrace，返回 this 而不实际填充栈信息
    // 这样创建异常的开销从微秒级降到纳秒级
    override fun fillInStackTrace(): Throwable = this
}

// 1. 在 val 初始化中使用 throw
val name: String = inputName ?: throw IllegalArgumentException("Name required")
// 如果 inputName 为 null，throw 表达式被求值
// 由于 Nothing 是所有类型的子类型，它可以"假装"是 String
 
// 2. 在 when 表达式中使用 throw
fun getStatusMessage(code: Int): String = when (code) {
    200 -> "OK"                                          // 返回 String
    404 -> "Not Found"                                   // 返回 String
    else -> throw IllegalArgumentException("Unknown: $code")  // Nothing，兼容 String
}
 
// 3. 在 if-else 表达式中使用 throw
fun requirePositive(n: Int): Int =
    if (n > 0) n                                         // 返回 Int
    else throw IllegalArgumentException("Must be positive") // Nothing，兼容 Int

// 编译器推断 result 的类型为 String
// 因为 throw 的类型是 Nothing，而 Nothing 是 String 的子类型
// 所以两个分支的公共类型（LUB, Least Upper Bound）是 String
val result: String = name ?: throw Exception("missing")
 
// 同理，emptyList<Nothing>() 可以赋值给任何 List 类型
val strings: List<String> = emptyList()  // 实际返回 List<Nothing>，向上兼容
val ints: List<Int> = emptyList()        // 同上

// 标准库中的 TODO() 函数签名
public inline fun TODO(): Nothing = throw NotImplementedError()
 
// 标准库中的 error() 函数签名
public inline fun error(message: Any): Nothing =
    throw IllegalStateException(message.toString())
 
// 使用场景：占位符，编译通过但运行时会崩溃
fun calculateTax(income: Double): Double {
    TODO("Tax calculation not implemented yet")
    // 编译器不会报错"缺少 return"，因为 TODO() 返回 Nothing
    // Nothing 是 Double 的子类型，类型检查通过
}

// 自定义的 "永不返回" 函数
fun fail(message: String): Nothing {
    // 记录日志后抛出异常
    logger.error("Fatal: $message")       // 记录错误日志
    throw ApplicationException(message)    // 抛出异常，函数永不正常返回
}
 
// 使用时，编译器知道 fail() 之后的代码不可达
fun processOrder(order: Order?): OrderResult {
    val validOrder = order ?: fail("Order cannot be null")
    // 编译器知道 validOrder 一定是非空的 Order 类型
    // 因为如果 order 为 null，fail() 会抛异常，不会走到这里
    return validOrder.process()
}

// ① 直接构造：最基础的方式
throw Exception("Something went wrong")
 
// ② 带 cause 的异常链：保留原始异常信息
try {
    parseConfig(rawText)
} catch (e: JsonParseException) {
    // 将底层的 JSON 解析异常包装为业务异常
    // cause 参数保留了原始异常，方便排查根因
    throw ConfigurationException("Invalid config format", cause = e)
}
 
// ③ 使用标准库的便捷函数
// require —— 检查参数，失败抛 IllegalArgumentException
fun setAge(age: Int) {
    require(age in 0..150) { "Age must be between 0 and 150, got $age" }
    // lambda 只在条件不满足时才执行，避免不必要的字符串拼接开销
}
 
// check —— 检查状态，失败抛 IllegalStateException
fun startEngine() {
    check(fuelLevel > 0) { "Cannot start engine: fuel level is $fuelLevel" }
}
 
// error —— 直接抛出 IllegalStateException
fun getUser(id: Long): User {
    return userCache[id] ?: error("User $id not found in cache")
}

class BankAccount(val balance: Double) {
    fun withdraw(amount: Double): Double {
        // require 校验参数：amount 必须为正数
        require(amount > 0) { "Withdrawal amount must be positive" }
 
        // check 校验状态：余额必须充足
        check(balance >= amount) { "Insufficient balance: $balance < $amount" }
 
        return balance - amount
    }
}

// 在 map 中使用 throw
val numbers = listOf("1", "2", "abc", "4")
 
val parsed: List<Int> = numbers.map { str ->
    // toIntOrNull() 返回 Int?
    // throw 的类型是 Nothing，Nothing 是 Int 的子类型
    // 所以 ?: 表达式整体类型为 Int
    str.toIntOrNull() ?: throw NumberFormatException("Cannot parse: $str")
}
 
// 在 let 中使用 throw
val config: Config = loadConfig()
    ?.let { validateConfig(it) }           // 返回 Config?
    ?: throw IllegalStateException("Config loading and validation failed")

// ❌ 反模式：用异常做控制流
fun findFirst(list: List<Int>, predicate: (Int) -> Boolean): Int? {
    try {
        list.forEach { item ->
            if (predicate(item)) throw FoundException(item)  // 昂贵！每次都捕获栈
        }
        return null
    } catch (e: FoundException) {
        return e.value
    }
}
 
// ✅ 正确做法：用标准库函数
fun findFirst(list: List<Int>, predicate: (Int) -> Boolean): Int? {
    return list.firstOrNull(predicate)  // 简洁、高效、无异常开销
}

fun greet(name: String?): String {
    val validName = name ?: throw IllegalArgumentException("Name is null")
    return "Hello, $validName"
}
 
fun main() {
    val result: Any = try {
        greet(null)
    } catch (e: IllegalArgumentException) {
        42
    }
    println(result)
}

fun parseAge(input: String): Int {
    try {
        // toInt() 在输入不是合法整数时抛出 NumberFormatException
        val age = input.toInt()
        return age
    } catch (e: NumberFormatException) {
        // 捕获到异常后，打印友好提示并返回默认值
        println("Invalid age format: '${input}', reason: ${e.message}")
        return -1
    }
}
 
fun main() {
    println(parseAge("25"))    // 输出: 25
    println(parseAge("abc"))   // 输出: Invalid age format: 'abc', reason: For input string: "abc"
                               //       -1
}

fun readConfig(path: String): Map<String, String> {
    try {
        val file = java.io.File(path)           // 构造文件对象
        val content = file.readText()            // 可能抛 IOException
        val pairs = content.lines().map { line ->
            val parts = line.split("=")          // 按等号分割
            // 如果格式不对，parts 可能不够两个元素
            if (parts.size != 2) throw IllegalArgumentException("Bad format: $line")
            parts[0].trim() to parts[1].trim()   // 返回键值对
        }
        return pairs.toMap()
    } catch (e: java.io.FileNotFoundException) {
        // 最具体的异常放在最前面
        println("Config file not found: $path")
        return emptyMap()
    } catch (e: java.io.IOException) {
        // 更宽泛的 IO 异常（包括权限问题、磁盘错误等）
        println("IO error reading config: ${e.message}")
        return emptyMap()
    } catch (e: IllegalArgumentException) {
        // 格式解析错误
        println("Config format error: ${e.message}")
        return emptyMap()
    }
}

// 方式一：捕获共同父类，再用 when 细分（适合异常有共同父类的情况）
try {
    riskyOperation()
} catch (e: Exception) {
    when (e) {
        is IOException,
        is IllegalArgumentException -> {
            // 对这两种异常做相同处理
            println("Handled known error: ${e.message}")
        }
        else -> throw e  // 其他异常重新抛出，不要吞掉
    }
}
 
// 方式二：抽取公共处理逻辑为函数（更清晰）
fun handleRecoverableError(e: Exception) {
    println("Recoverable error: ${e.message}")
    // 记录日志、发送告警等
}
 
try {
    riskyOperation()
} catch (e: IOException) {
    handleRecoverableError(e)           // 复用处理逻辑
} catch (e: IllegalArgumentException) {
    handleRecoverableError(e)           // 复用处理逻辑
}

fun readFirstLine(path: String): String? {
    var reader: java.io.BufferedReader? = null  // 声明在 try 外部以便 finally 访问
    try {
        reader = java.io.File(path).bufferedReader()  // 打开文件
        return reader.readLine()                       // 读取第一行并返回
    } catch (e: java.io.IOException) {
        println("Failed to read file: ${e.message}")   // 处理 IO 异常
        return null                                     // 返回 null 表示失败
    } finally {
        // 无论 try 成功还是 catch 被触发，这里都会执行
        reader?.close()                                 // 安全关闭资源
        println("Reader cleanup completed")             // 确认清理完成
    }
}

// 场景 1：正常执行 —— finally 在 return 之前执行
fun scenario1(): String {
    try {
        return "from try"       // 准备返回
    } finally {
        println("finally runs") // 在 return 生效之前执行
    }
    // 输出: finally runs
    // 返回: "from try"
}
 
// 场景 2：异常被捕获 —— finally 在 catch 之后执行
fun scenario2(): String {
    try {
        throw RuntimeException("boom")
    } catch (e: RuntimeException) {
        println("caught")       // 先执行 catch
        return "from catch"     // 准备返回
    } finally {
        println("finally runs") // 在 catch 的 return 生效之前执行
    }
    // 输出: caught → finally runs
    // 返回: "from catch"
}
 
// 场景 3：异常未被捕获 —— finally 在异常传播之前执行
fun scenario3() {
    try {
        throw Error("fatal")    // Error 类型，没有对应的 catch
    } finally {
        println("finally runs") // 仍然执行！然后异常继续向上传播
    }
}

// ⚠️ 危险示例：finally 中的 return 会覆盖一切
fun dangerousReturn(): String {
    try {
        throw RuntimeException("important error!")  // 抛出异常
    } catch (e: RuntimeException) {
        return "from catch"                          // 准备返回 "from catch"
    } finally {
        return "from finally"                        // 覆盖了 catch 的返回值！
    }
    // 实际返回: "from finally"
    // "important error!" 异常被彻底吞掉，没有任何痕迹
}
 
// ⚠️ 更隐蔽的情况：finally 的 return 吞掉未捕获的异常
fun silentSwallow(): String {
    try {
        throw OutOfMemoryError("heap exhausted")    // 严重错误！
    } finally {
        return "everything is fine"                  // 异常被吞掉，调用者毫不知情
    }
    // 返回: "everything is fine"
    // OutOfMemoryError 消失了——这是灾难性的 bug
}

// ✅ 原则 1：只捕获你能处理的异常，不要写空的 catch 块
try {
    connectToDatabase()
} catch (e: ConnectionException) {
    // 有明确的恢复策略：重试、降级、或向用户报告
    retryWithBackoff(maxAttempts = 3) { connectToDatabase() }
}
 
// ❌ 反模式：吞掉异常
try {
    connectToDatabase()
} catch (e: Exception) {
    // 什么都不做——bug 会在几周后以莫名其妙的方式爆发
}
 
// ✅ 原则 2：捕获最具体的异常类型
try {
    parseAndValidate(input)
} catch (e: ValidationException) {
    // 只处理验证异常，其他异常继续传播
    showValidationError(e.field, e.message)
}
 
// ❌ 反模式：捕获 Exception 或 Throwable
try {
    parseAndValidate(input)
} catch (e: Exception) {
    // 把 NullPointerException、StackOverflowError 等都吞了
    println("something went wrong")
}
 
// ✅ 原则 3：保留异常链（cause）
try {
    loadUserProfile(userId)
} catch (e: IOException) {
    // 包装为业务异常时，保留原始 cause
    throw UserProfileException("Failed to load profile for $userId", cause = e)
}

// Java 风格：变量必须先声明为 var，再在不同分支赋值
int value;
try {
    value = Integer.parseInt(input);
} catch (NumberFormatException e) {
    value = 0;
}

// Kotlin 风格：try 是表达式，直接返回值
val value: Int = try {
    input.toInt()           // try 块的最后一个表达式 → 成功时的返回值
} catch (e: NumberFormatException) {
    0                       // catch 块的最后一个表达式 → 失败时的返回值
}
// value 是不可变的 val，类型安全，代码更简洁

// 规则 1：无异常时，返回 try 块最后一个表达式的值
val result1 = try {
    println("step 1")       // 执行但不影响返回值
    println("step 2")       // 执行但不影响返回值
    42                      // ← 这是 try 块的最后一个表达式，作为返回值
} catch (e: Exception) {
    -1
}
// result1 = 42
 
// 规则 2：有异常时，返回匹配的 catch 块最后一个表达式的值
val result2 = try {
    "abc".toInt()           // 抛出 NumberFormatException
    42                      // ← 不会执行到这里
} catch (e: NumberFormatException) {
    println("caught!")      // 执行但不影响返回值
    -1                      // ← catch 块的最后一个表达式，作为返回值
}
// result2 = -1
 
// 规则 3：finally 块的值不会影响 try 表达式的返回值
val result3 = try {
    42
} finally {
    100                     // finally 的值被丢弃，不影响返回值
}
// result3 = 42（不是 100）

// try 返回 Int，catch 返回 Int → 整体类型 Int
val a: Int = try { "123".toInt() } catch (e: Exception) { 0 }
 
// try 返回 String，catch 返回 Int → LUB 是 Any
val b: Any = try { "hello" } catch (e: Exception) { 42 }
 
// try 返回 Int，catch 抛出异常（Nothing）→ Nothing 是 Int 的子类型 → 整体 Int
val c: Int = try {
    "123".toInt()
} catch (e: NumberFormatException) {
    throw IllegalStateException("Unexpected", e)  // 返回类型是 Nothing
}
 
// 多个 catch 块：取所有分支的 LUB
val d = try {
    readFromNetwork()                              // 返回 String
} catch (e: java.io.IOException) {
    "default"                                      // String
} catch (e: SecurityException) {
    ""                                             // String
}
// d 的类型被推断为 String

// 模式 1：安全解析，配合 Elvis 操作符
// 先尝试解析，失败返回 null，再用 ?: 提供默认值
fun safeParseInt(s: String): Int =
    try { s.toInt() } catch (e: NumberFormatException) { 0 }
 
// 模式 2：在函数返回值中直接使用
fun loadConfiguration(): Config = try {
    // 尝试从文件加载配置
    ConfigLoader.fromFile("/etc/app/config.yaml")
} catch (e: java.io.FileNotFoundException) {
    // 文件不存在时使用默认配置
    Config.default()
} catch (e: ConfigParseException) {
    // 配置格式错误时也使用默认配置，但记录警告
    logger.warn("Config parse failed, using defaults", e)
    Config.default()
}
 
// 模式 3：在集合操作中嵌入 try 表达式
val rawScores = listOf("95", "87", "N/A", "76", "error", "88")
 
val validScores: List<Int> = rawScores.map { raw ->
    try {
        raw.toInt()                    // 尝试解析为整数
    } catch (e: NumberFormatException) {
        -1                             // 无法解析的标记为 -1
    }
}.filter { it >= 0 }                  // 过滤掉无效分数
 
// validScores = [95, 87, 76, 88]

val input = "42abc"
 
// 方式 1：try 表达式 —— 最灵活，可以区分不同异常类型
val v1 = try { input.toInt() } catch (e: NumberFormatException) { 0 }
 
// 方式 2：toIntOrNull + Elvis —— 最简洁，适合简单场景
val v2 = input.toIntOrNull() ?: 0
 
// 方式 3：runCatching —— 返回 Result 类型，适合链式处理（后续章节详解）
val v3 = runCatching { input.toInt() }.getOrDefault(0)

val result = try {
    // 外层 try：处理整体流程异常
    val config = try {
        // 内层 try：处理配置加载异常
        loadFromRemote()                    // 尝试远程加载
    } catch (e: java.io.IOException) {
        loadFromLocal()                     // 远程失败则加载本地缓存
    }
    applyConfig(config)                     // 应用配置，可能抛出 ConfigException
    "success"
} catch (e: ConfigException) {
    // 外层 catch：处理配置应用异常
    "failed: ${e.message}"
}

fun puzzle(): Int {
    return try {
        try {
            throw IllegalArgumentException("inner")
        } finally {
            println("inner finally")
        }
    } catch (e: IllegalArgumentException) {
        println("outer catch")
        99
    } finally {
        println("outer finally")
    }
}
 
fun main() {
    println(puzzle())
}

val result: Int = try {
    val x = 10
    val y = 20
    x + y
} catch (e: Exception) {
    -1
} finally {
    999
}

// Java 代码：checked exception 强制处理
public String readFile(String path) throws IOException {  // 必须声明
    BufferedReader reader = new BufferedReader(new FileReader(path));
    return reader.readLine();
}
 
public void caller() {
    // 编译错误！必须处理 IOException
    // String content = readFile("data.txt");
 
    // 方式一：try-catch 捕获
    try {
        String content = readFile("data.txt");
    } catch (IOException e) {
        e.printStackTrace();
    }
 
    // 方式二：继续向上声明 throws IOException
}

// Java 中极其常见的反模式
try {
    riskyOperation();
} catch (IOException e) {
    // 什么都不做，异常被吞掉了
    // 程序继续运行，但状态可能已经不一致
}
 
// 另一种常见的"应付编译器"写法
try {
    riskyOperation();
} catch (IOException e) {
    throw new RuntimeException(e);  // 机械地包装成 unchecked，毫无意义
}

// Java：异常声明像病毒一样扩散
public void methodA() throws IOException, SQLException, ParseException {
    methodB();  // 只是中间转发，却必须声明所有异常
}
 
public void methodB() throws IOException, SQLException, ParseException {
    methodC();  // 同上
}
 
public void methodC() throws IOException, SQLException, ParseException {
    // 真正可能抛异常的地方
}

// Java：lambda 中无法抛出 checked exception
List<String> paths = List.of("a.txt", "b.txt");
// 编译错误！IOException 是 checked exception，Function.apply() 没有声明 throws
// paths.stream().map(path -> new FileReader(path)).collect(Collectors.toList());
 
// 被迫在 lambda 内部 try-catch，代码变得丑陋
paths.stream().map(path -> {
    try {
        return new FileReader(path);
    } catch (IOException e) {
        throw new RuntimeException(e);  // 又是机械包装
    }
}).collect(Collectors.toList());

// Kotlin：直接调用可能抛异常的函数，无需声明或捕获
fun readFile(path: String): String {
    // FileReader 构造函数可能抛 IOException
    // Kotlin 不要求你处理它
    return java.io.FileReader(path).readText()
}
 
fun caller() {
    // 直接调用，编译器不会报错
    val content = readFile("data.txt")
    // 如果文件不存在，IOException 会在运行时抛出
    // 开发者可以自行决定是否在这里或更上层处理
}

// Kotlin 端：使用 @Throws 注解
// 这个注解不影响 Kotlin 调用者，只影响生成的字节码
@Throws(IOException::class)
fun readConfig(path: String): String {
    val file = java.io.File(path)           // 创建 File 对象
    if (!file.exists()) {                    // 检查文件是否存在
        throw IOException("File not found: $path")  // 抛出 IOException
    }
    return file.readText()                   // 读取文件全部内容
}
 
// 可以声明多个异常类型
@Throws(IOException::class, IllegalArgumentException::class)
fun parseConfig(path: String): Map<String, String> {
    require(path.isNotBlank()) { "Path must not be blank" }  // 可能抛 IAE
    val content = readConfig(path)                             // 可能抛 IOException
    return parseToMap(content)                                 // 解析为 Map
}

// 编译后的字节码等价 Java 代码
// @Throws 注解让编译器在方法签名中添加了 throws 声明
public static String readConfig(String path) throws IOException {
    // ... 方法体 ...
}
 
public static Map<String, String> parseConfig(String path)
        throws IOException, IllegalArgumentException {
    // ... 方法体 ...
}

// Java 端调用 Kotlin 函数
public class JavaCaller {
    public void loadSettings() {
        try {
            // Java 编译器知道 readConfig 可能抛 IOException
            String config = ConfigReaderKt.readConfig("settings.conf");
            System.out.println(config);
        } catch (IOException e) {
            // 编译器允许这个 catch 块，因为字节码中有 throws 声明
            System.err.println("Failed to read config: " + e.getMessage());
        }
    }
}

// ✅ 需要 @Throws：抛出 checked exception + 可能被 Java 调用
@Throws(IOException::class)
fun saveData(data: ByteArray, path: String) {
    java.io.File(path).writeBytes(data)  // writeBytes 内部可能抛 IOException
}
 
// ❌ 不需要 @Throws：只抛出 unchecked exception
fun validateAge(age: Int) {
    require(age >= 0) { "Age cannot be negative" }
    // IllegalArgumentException 是 RuntimeException 的子类
    // Java 也不强制捕获它
}
 
// ❌ 不需要 @Throws：纯 Kotlin 项目，不会被 Java 调用
internal fun internalHelper(): String {
    // internal 可见性意味着只在模块内使用
    // 如果整个模块都是 Kotlin，无需 @Throws
    return java.io.File("temp.txt").readText()
}

// suspend 函数也可以使用 @Throws
@Throws(IOException::class)
suspend fun fetchRemoteConfig(url: String): String {
    // 模拟网络请求
    return withContext(Dispatchers.IO) {
        java.net.URL(url).readText()  // 可能抛出 IOException
    }
}

// 最基础的自定义异常
// 继承 RuntimeException，因为大多数业务异常不需要强制捕获
class OrderNotFoundException(
    message: String,                    // 错误描述
    cause: Throwable? = null            // 可选的原始异常（默认 null）
) : RuntimeException(message, cause)    // 调用父类构造函数
 
// 使用
fun findOrder(id: Long): Order {
    return orderRepository.findById(id)
        ?: throw OrderNotFoundException("Order with id $id not found")
}

// 携带丰富上下文信息的业务异常
class PaymentFailedException(
    val orderId: Long,                   // 关联的订单 ID
    val amount: Double,                  // 支付金额
    val currency: String,                // 货币类型
    val errorCode: String,               // 支付网关返回的错误码
    message: String,                     // 人类可读的错误描述
    cause: Throwable? = null             // 原始异常
) : RuntimeException(message, cause) {
 
    // 提供格式化的详细信息，方便日志输出
    fun toDetailString(): String =
        "PaymentFailed[order=$orderId, amount=$amount $currency, code=$errorCode]: $message"
}
 
// 使用场景
fun processPayment(order: Order): PaymentReceipt {
    try {
        return paymentGateway.charge(order.totalAmount, order.currency)
    } catch (e: GatewayTimeoutException) {
        // 包装底层异常，添加业务上下文
        throw PaymentFailedException(
            orderId = order.id,                          // 携带订单 ID
            amount = order.totalAmount,                  // 携带金额
            currency = order.currency,                   // 携带币种
            errorCode = "GATEWAY_TIMEOUT",               // 标准化错误码
            message = "Payment gateway timed out for order ${order.id}",
            cause = e                                    // 保留原始异常链
        )
    }
}

// 调用方可以精确地提取上下文信息
try {
    processPayment(order)
} catch (e: PaymentFailedException) {
    // 直接访问结构化字段，无需解析字符串
    logger.error("Payment failed for order ${e.orderId}: ${e.errorCode}")
    metrics.recordPaymentFailure(e.errorCode)            // 按错误码统计
    notifyUser(e.orderId, e.amount, e.currency)          // 通知用户
}

// 顶层业务异常基类（sealed 或 abstract 均可）
// 使用 abstract 允许跨模块扩展
abstract class AppException(
    val errorCode: String,               // 全局唯一的错误码
    message: String,                     // 错误描述
    cause: Throwable? = null             // 原始异常
) : RuntimeException(message, cause)
 
// ── 用户领域异常 ──
open class UserException(
    errorCode: String,
    message: String,
    cause: Throwable? = null
) : AppException(errorCode, message, cause)
 
class UserNotFoundException(
    val userId: Long                     // 携带用户 ID
) : UserException(
    errorCode = "USER_NOT_FOUND",
    message = "User $userId does not exist"
)
 
class UserSuspendedException(
    val userId: Long,                    // 携带用户 ID
    val reason: String                   // 封禁原因
) : UserException(
    errorCode = "USER_SUSPENDED",
    message = "User $userId is suspended: $reason"
)
 
// ── 订单领域异常 ──
open class OrderException(
    errorCode: String,
    message: String,
    cause: Throwable? = null
) : AppException(errorCode, message, cause)
 
class InsufficientStockException(
    val productId: Long,                 // 商品 ID
    val requested: Int,                  // 请求数量
    val available: Int                   // 实际库存
) : OrderException(
    errorCode = "INSUFFICIENT_STOCK",
    message = "Product $productId: requested $requested but only $available available"
)

try {
    placeOrder(userId = 42, productId = 100, quantity = 5)
} catch (e: InsufficientStockException) {
    // 最精确的匹配：库存不足，可以给用户具体提示
    showMessage("库存不足，${e.productId} 仅剩 ${e.available} 件")
} catch (e: OrderException) {
    // 中间层匹配：所有订单相关异常
    showMessage("订单处理失败：${e.errorCode}")
} catch (e: AppException) {
    // 最宽泛的匹配：所有业务异常
    logger.error("Business error [${e.errorCode}]: ${e.message}")
    showGenericError()
}

// sealed 异常：编译器保证 when 穷尽性
sealed class ValidationException(
    message: String
) : RuntimeException(message) {
 
    // 字段为空
    class MissingField(
        val fieldName: String                // 缺失的字段名
    ) : ValidationException("Field '$fieldName' is required")
 
    // 格式错误
    class InvalidFormat(
        val fieldName: String,               // 字段名
        val expectedPattern: String           // 期望的格式
    ) : ValidationException("Field '$fieldName' must match pattern: $expectedPattern")
 
    // 值超出范围
    class OutOfRange(
        val fieldName: String,               // 字段名
        val min: Number,                     // 最小值
        val max: Number,                     // 最大值
        val actual: Number                   // 实际值
    ) : ValidationException("Field '$fieldName': $actual is not in [$min, $max]")
}
 
// when 表达式可以穷尽所有分支，无需 else
fun handleValidationError(e: ValidationException): String = when (e) {
    is ValidationException.MissingField ->
        "请填写 ${e.fieldName}"                          // 提示用户填写
    is ValidationException.InvalidFormat ->
        "${e.fieldName} 格式不正确，应为 ${e.expectedPattern}"  // 提示正确格式
    is ValidationException.OutOfRange ->
        "${e.fieldName} 应在 ${e.min}~${e.max} 之间"     // 提示有效范围
    // 无需 else！编译器知道所有子类都已覆盖
}

// 统一的 API 错误响应数据类
data class ApiError(
    val code: String,                    // 业务错误码
    val message: String,                 // 用户可见的错误描述
    val timestamp: Long = System.currentTimeMillis()  // 错误发生时间
)
 
// 全局异常处理器（以 Ktor/Spring 风格为例）
fun handleException(e: Throwable): Pair<Int, ApiError> = when (e) {
    is UserNotFoundException -> 404 to ApiError(       // HTTP 404
        code = e.errorCode,
        message = "用户不存在"
    )
    is UserSuspendedException -> 403 to ApiError(      // HTTP 403
        code = e.errorCode,
        message = "账户已被封禁"
    )
    is InsufficientStockException -> 409 to ApiError(  // HTTP 409 Conflict
        code = e.errorCode,
        message = "库存不足"
    )
    is AppException -> 400 to ApiError(                // HTTP 400 兜底
        code = e.errorCode,
        message = e.message ?: "业务处理失败"
    )
    else -> 500 to ApiError(                           // HTTP 500 未知错误
        code = "INTERNAL_ERROR",
        message = "服务器内部错误"
    )
}

// 技巧 1：使用伴生对象提供工厂方法，让创建更语义化
class ResourceConflictException private constructor(
    val resourceType: String,
    val resourceId: String,
    message: String
) : AppException("RESOURCE_CONFLICT", message) {
 
    companion object {
        // 工厂方法：语义清晰，调用处一目了然
        fun duplicateEmail(email: String) = ResourceConflictException(
            resourceType = "User",
            resourceId = email,
            message = "Email $email is already registered"
        )
 
        fun duplicateOrderNumber(orderNumber: String) = ResourceConflictException(
            resourceType = "Order",
            resourceId = orderNumber,
            message = "Order number $orderNumber already exists"
        )
    }
}
 
// 使用：比直接 new 更具可读性
throw ResourceConflictException.duplicateEmail("[email]")
 
// 技巧 2：扩展函数简化异常抛出
inline fun <reified T> notFound(id: Any): Nothing {
    // reified 获取泛型的实际类型名
    val typeName = T::class.simpleName    // 例如 "User"、"Order"
    throw AppException(
        errorCode = "${typeName?.uppercase()}_NOT_FOUND",
        message = "$typeName with id $id not found"
    )
}
 
// 使用
fun getUser(id: Long): User {
    return userRepository.findById(id) ?: notFound<User>(id)
    // 抛出: AppException(errorCode="USER_NOT_FOUND", message="User with id 42 not found")
}

// 选项 A
fun readData(path: String): String = File(path).readText()
 
// 选项 B
@Throws(IOException::class)
fun readData(path: String): String = File(path).readText()
 
// 选项 C
@Throws(RuntimeException::class)
fun readData(path: String): String = File(path).readText()
 
// 选项 D
@Suppress("TooGenericExceptionThrown")
fun readData(path: String): String = File(path).readText()

abstract class AppException(val code: String, msg: String) : RuntimeException(msg)
class AuthException(code: String, msg: String) : AppException(code, msg)
class PermissionDeniedException(val resource: String)
    : AuthException("PERM_DENIED", "No access to $resource")
 
fun main() {
    try {
        throw PermissionDeniedException("admin_panel")
    } catch (e: AppException) {
        println("${e.code}: ${e.message}")
    }
}

// Result 的概念模型（简化版，非实际源码）
// 实际上 Result 是 inline class，编译后没有额外的包装开销
@JvmInline
value class Result<out T> internal constructor(
    internal val value: Any?   // 成功时存 T 的值，失败时存 Failure(exception)
) {
    // 判断是否成功
    val isSuccess: Boolean get() = value !is Failure
 
    // 判断是否失败
    val isFailure: Boolean get() = value is Failure
 
    // 内部类，包装失败的异常
    internal class Failure(val exception: Throwable)
}

// 创建一个成功的 Result，包含值 42
val success: Result<Int> = Result.success(42)
 
// 创建一个失败的 Result，包含异常信息
val failure: Result<Int> = Result.failure(IllegalStateException("something broke"))
 
// 验证状态
println(success.isSuccess)  // true
println(success.isFailure)  // false
println(failure.isSuccess)  // false
println(failure.isFailure)  // true

val success: Result<String> = Result.success("Kotlin")
val failure: Result<String> = Result.failure(RuntimeException("oops"))
 
// ① getOrNull() —— 成功返回值，失败返回 null
println(success.getOrNull())   // "Kotlin"
println(failure.getOrNull())   // null
 
// ② exceptionOrNull() —— 失败返回异常，成功返回 null
println(success.exceptionOrNull())  // null
println(failure.exceptionOrNull())  // java.lang.RuntimeException: oops
 
// ③ getOrDefault() —— 失败时返回指定的默认值
println(failure.getOrDefault("fallback"))  // "fallback"
 
// ④ getOrThrow() —— 成功返回值，失败直接重新抛出异常
println(success.getOrThrow())  // "Kotlin"
// failure.getOrThrow()        // 抛出 RuntimeException: oops

// ❌ 不诚实的函数签名：看起来返回 User，实际可能抛异常
fun findUser(id: Long): User {
    // 可能抛出 UserNotFoundException、DatabaseException...
    // 但签名完全没有体现这一点
    return database.query("SELECT * FROM users WHERE id = ?", id)
}
 
// ✅ 诚实的函数签名：返回类型明确告诉调用者"可能失败"
fun findUser(id: Long): Result<User> {
    return runCatching {
        database.query("SELECT * FROM users WHERE id = ?", id)
    }
}

// Kotlin 1.5+ 允许 Result 作为返回类型
fun parseAge(input: String): Result<Int> {
    return runCatching { input.toInt() }  // 将可能的异常包装为 Result
}
 
// 但 Result 作为 inline class，在某些泛型场景下会被装箱
// 这是需要注意的性能细节
val results: List<Result<Int>> = listOf("1", "abc", "3").map { parseAge(it) }

val result: Result<String> = Result.success("42")
 
// map 将 String 转换为 Int
// 如果 result 是 Success，执行 lambda 并将结果包装为新的 Success
// 如果 result 是 Failure，直接返回原来的 Failure，lambda 不执行
val mapped: Result<Int> = result.map { it.toInt() }
 
println(mapped.getOrNull())  // 42
 
// 失败时 map 不执行
val failed: Result<String> = Result.failure(Exception("boom"))
val mappedFail: Result<Int> = failed.map { it.toInt() }  // lambda 不会被调用
println(mappedFail.isFailure)  // true
println(mappedFail.exceptionOrNull()?.message)  // "boom"（原始异常原封不动）

val result: Result<String> = Result.success("not_a_number")
 
// map 版本：如果 toInt() 抛异常，异常会直接逃逸
// val dangerous: Result<Int> = result.map { it.toInt() }  // 💥 抛出 NumberFormatException
 
// mapCatching 版本：toInt() 的异常被捕获，包装为 Failure
val safe: Result<Int> = result.mapCatching { it.toInt() }
println(safe.isFailure)  // true
println(safe.exceptionOrNull())  // java.lang.NumberFormatException: For input string: "not_a_number"

val failure: Result<Int> = Result.failure(Exception("network error"))
 
// recover：失败时执行 lambda，返回替代值
// 如果 Result 是 Success，直接返回原值，lambda 不执行
val recovered: Result<Int> = failure.recover { exception ->
    println("Recovering from: ${exception.message}")  // 输出: Recovering from: network error
    -1  // 提供默认值作为恢复
}
 
println(recovered.getOrNull())  // -1
println(recovered.isSuccess)    // true（已经从 Failure 恢复为 Success）

val failure: Result<String> = Result.failure(Exception("primary failed"))
 
// recoverCatching：恢复函数本身也可能失败
val result: Result<String> = failure.recoverCatching { exception ->
    // 尝试从备用数据源恢复，但备用源也可能失败
    fetchFromBackup()  // 如果这里也抛异常，会被捕获为新的 Failure
}

val failure: Result<Int> = Result.failure(IllegalArgumentException("bad input"))
 
// getOrElse：失败时执行 lambda，lambda 接收异常作为参数
val value: Int = failure.getOrElse { exception ->
    // 可以根据异常类型决定不同的默认值
    when (exception) {
        is IllegalArgumentException -> 0     // 参数错误，返回 0
        is IllegalStateException -> -1       // 状态错误，返回 -1
        else -> throw exception              // 未知异常，重新抛出
    }
}
println(value)  // 0
 
// 成功时 getOrElse 直接返回成功值，lambda 不执行
val success: Result<Int> = Result.success(42)
val successValue: Int = success.getOrElse { 0 }
println(successValue)  // 42

val result: Result<String> = Result.success("Kotlin")
 
// fold 接收两个 lambda：
// 第一个处理成功（onSuccess），第二个处理失败（onFailure）
val message: String = result.fold(
    onSuccess = { value ->
        "Got value: $value"           // 成功时的处理逻辑
    },
    onFailure = { exception ->
        "Error: ${exception.message}" // 失败时的处理逻辑
    }
)
println(message)  // "Got value: Kotlin"

fun processData(input: String): Result<Int> {
    return runCatching { input.toInt() }
        .onSuccess { value ->
            // 成功时记录日志（副作用），不改变 Result
            println("Successfully parsed: $value")
        }
        .onFailure { exception ->
            // 失败时记录日志（副作用），不改变 Result
            println("Failed to parse: ${exception.message}")
        }
}
 
// 调用
val r = processData("123")  // 输出: Successfully parsed: 123
println(r.getOrNull())      // 123

// 模拟一个用户注册流程，每一步都可能失败
data class RawInput(val email: String, val age: String)
data class ValidatedInput(val email: String, val age: Int)
data class User(val id: Long, val email: String, val age: Int)
 
fun registerUser(raw: RawInput): Result<User> {
    return runCatching {
        // 第一步：验证年龄格式（可能抛 NumberFormatException）
        raw.age.toInt()
    }
    .mapCatching { age ->
        // 第二步：业务规则校验（可能抛 IllegalArgumentException）
        require(age in 18..120) { "Age $age is out of valid range" }
        ValidatedInput(raw.email, age)          // 构建验证后的输入
    }
    .mapCatching { validated ->
        // 第三步：写入数据库（可能抛 DatabaseException）
        val id = database.insert(validated)     // 模拟数据库插入
        User(id, validated.email, validated.age) // 构建用户对象
    }
    .recover { exception ->
        // 如果是已知用户（邮箱重复），从缓存恢复
        when (exception) {
            is DuplicateEmailException ->
                userCache.getByEmail(raw.email)  // 返回已存在的用户
            else -> throw exception              // 未知异常，重新抛出
        }
    }
    .onSuccess { user ->
        // 成功时发送欢迎邮件（副作用）
        emailService.sendWelcome(user.email)
    }
    .onFailure { exception ->
        // 失败时记录审计日志（副作用）
        auditLog.record("Registration failed: ${exception.message}")
    }
}
 
// 调用方使用 fold 做最终处理
fun handleRegistration(raw: RawInput): String {
    return registerUser(raw).fold(
        onSuccess = { user ->
            "Welcome, ${user.email}! Your ID is ${user.id}"
        },
        onFailure = { error ->
            "Registration failed: ${error.message}"
        }
    )
}

fun main() {
    val result = Result.success("hello")
        .map { it.uppercase() }
        .map { it.length }
        .getOrElse { -1 }
 
    println(result)
}

val recovered = Result.failure<String>(IllegalStateException("fail"))
    .map { it.uppercase() }
    .recover { "default" }
    .mapCatching { it.toInt() }
    .getOrElse { 0 }

// 标准库源码（简化版）
// 顶层函数版本：对任意代码块捕获异常
public inline fun <R> runCatching(block: () -> R): Result<R> {
    return try {
        Result.success(block())    // 执行 block，成功则包装为 Success
    } catch (e: Throwable) {
        Result.failure(e)          // 捕获所有 Throwable，包装为 Failure
    }
}
 
// 扩展函数版本：在某个对象上下文中执行
public inline fun <T, R> T.runCatching(block: T.() -> R): Result<R> {
    return try {
        Result.success(block())    // block 以 T 为 receiver 执行
    } catch (e: Throwable) {
        Result.failure(e)          // 同样捕获所有异常
    }
}

// ① 顶层函数形式：包裹任意代码块
val result: Result<Int> = runCatching {
    "42".toInt()                   // 可能抛出 NumberFormatException
}
println(result)                    // 输出: Success(42)
 
val failed: Result<Int> = runCatching {
    "not_a_number".toInt()         // 抛出 NumberFormatException
}
println(failed)                    // 输出: Failure(java.lang.NumberFormatException: ...)
 
// ② 扩展函数形式：在对象上下文中执行
val parseResult: Result<Int> = "123".runCatching {
    toInt()                        // this 是 "123"，直接调用 String.toInt()
}
println(parseResult.getOrNull())   // 输出: 123

// 场景：解析用户输入的年龄字符串，校验范围，返回可用值或默认值
fun parseAge(input: String): Int {
    return runCatching {
        input.trim().toInt()                       // 第一步：解析字符串为整数
    }.mapCatching { age ->
        require(age in 0..150) { "Age out of range: $age" }  // 第二步：校验范围
        age                                        // 校验通过，返回 age
    }.recover { exception ->
        println("Warning: ${exception.message}")   // 第三步：失败时打印警告
        -1                                         // 返回默认值 -1
    }.getOrThrow()                                 // 第四步：提取最终值
}
 
fun main() {
    println(parseAge("25"))       // 输出: 25
    println(parseAge("abc"))      // 输出: Warning: For input string: "abc" → -1
    println(parseAge("200"))      // 输出: Warning: Age out of range: 200 → -1
}

data class User(val id: Long, val name: String, val email: String)
data class UserDTO(val displayName: String, val maskedEmail: String)
 
// 模拟数据库查询，可能抛异常
fun queryUserFromDb(id: Long): User {
    if (id <= 0) throw IllegalArgumentException("Invalid user ID: $id")
    if (id == 999L) throw RuntimeException("Database connection timeout")
    return User(id, "Alice", "alice@example.com")
}
 
// 模拟数据转换，可能抛异常
fun toDTO(user: User): UserDTO {
    require(user.email.contains("@")) { "Invalid email format" }
    val masked = user.email.replace(Regex("(?<=.{2}).(?=.*@)"), "*")
    return UserDTO(user.name, masked)
}
 
// 链式处理：查询 → 转换 → 兜底
fun getUserDisplay(id: Long): UserDTO {
    return runCatching {
        queryUserFromDb(id)                        // 步骤1：查询用户
    }.mapCatching { user ->
        toDTO(user)                                // 步骤2：转换为 DTO
    }.recover { e ->
        println("Error processing user $id: ${e.message}")
        UserDTO("Unknown", "N/A")                  // 步骤3：任何失败都返回兜底 DTO
    }.getOrThrow()                                 // 步骤4：提取值（此处 recover 保证了 Success）
}
 
fun main() {
    println(getUserDisplay(1))     // UserDTO(displayName=Alice, maskedEmail=al***@example.com)
    println(getUserDisplay(-1))    // Error processing user -1: Invalid user ID: -1
                                   // UserDTO(displayName=Unknown, maskedEmail=N/A)
    println(getUserDisplay(999))   // Error processing user 999: Database connection timeout
                                   // UserDTO(displayName=Unknown, maskedEmail=N/A)
}

// 对文件对象使用扩展版 runCatching
fun readConfig(path: String): Result<Map<String, String>> {
    return File(path).runCatching {
        // this 是 File 对象，可以直接调用 readLines() 等方法
        readLines()                                // 读取所有行
            .filter { it.isNotBlank() && !it.startsWith("#") }  // 过滤空行和注释
            .associate { line ->
                val (key, value) = line.split("=", limit = 2)   // 按 = 分割
                key.trim() to value.trim()         // 去除首尾空格，组成键值对
            }
    }
}
 
// 对集合元素批量使用 runCatching
val inputs = listOf("10", "abc", "30", "", "50")
 
val results: List<Result<Int>> = inputs.map { input ->
    runCatching { input.toInt() }                  // 每个元素独立捕获异常
}
 
// 分离成功和失败
val successes = results.filter { it.isSuccess }.map { it.getOrThrow() }
val failures = results.filter { it.isFailure }.map { it.exceptionOrNull()!! }
 
println("Parsed: $successes")       // Parsed: [10, 30, 50]
println("Errors: ${failures.size}") // Errors: 2

// ⚠️ 危险：runCatching 会捕获 OutOfMemoryError
val result = runCatching {
    val hugeArray = IntArray(Int.MAX_VALUE)  // 触发 OutOfMemoryError
}
// result 是 Failure(OutOfMemoryError)，但此时 JVM 状态可能已经不稳定
// 程序继续运行可能产生不可预测的行为
 
// ✅ 更安全的做法：自定义一个只捕获 Exception 的版本
inline fun <R> runCatchingSafe(block: () -> R): Result<R> {
    return try {
        Result.success(block())
    } catch (e: Exception) {       // 只捕获 Exception，放过 Error
        Result.failure(e)
    }
}

// ⚠️ 协程中的陷阱
suspend fun fetchData(): Result<String> {
    return runCatching {
        delay(1000)                // 如果协程被取消，delay 会抛 CancellationException
        "data"                     // runCatching 会把 CancellationException 包装为 Failure
    }                              // 协程不会真正取消！这是一个严重的 bug
}
 
// ✅ 协程安全版本
suspend fun fetchDataSafe(): Result<String> {
    return try {
        Result.success(actualFetch())
    } catch (e: CancellationException) {
        throw e                    // 重新抛出 CancellationException，保持取消语义
    } catch (e: Exception) {
        Result.failure(e)
    }
}

// ❌ 过度链式化，难以理解每一步在做什么
val result = runCatching { step1() }
    .mapCatching { step2(it) }
    .mapCatching { step3(it) }
    .recoverCatching { step4() }
    .mapCatching { step5(it) }
    .recoverCatching { step6() }
    .mapCatching { step7(it) }
    .getOrDefault(fallback)
 
// ✅ 适度使用，保持可读性
val intermediate = runCatching { step1() }
    .mapCatching { step2(it) }
    .getOrElse { return handleEarlyFailure(it) }
 
val finalResult = runCatching { step3(intermediate) }
    .recover { fallback }
    .getOrThrow()