CodeGym /課程 /Kotlin SELF /Result<T> — 如何保存「成功/錯誤」狀態

Result<T> — 如何保存「成功/錯誤」狀態

Kotlin SELF
等級 40, 課堂 3
開放

1. 前言

當你剛開始寫程式時,例外(exception)常常被當作閃電一樣的東西:「哪裡出事了,然後程式就掛了」。但隨著專案變大,你會發現有一部分錯誤其實是正常的生活情境:使用者輸入的不是數字、要求刪除一筆不存在的資料、提供了空的分類。這不是「世界末日」,只是「沒有結果」——但需要說明原因。

這時就出現典型兩難:如果到處都丟例外,使用者在呼叫你的函式時,程式碼就會變成一片 try/catch 叢林。 如果到處都回傳 null,很快就失去語意:為什麼是 null?是「找不到」?是「輸入不合法」?還是「邏輯壞掉」? Kotlin 甚至在標準函式庫的範例裡也會示範:有時候使用像 toIntOrNull() 這種安全替代方案,比直接呼叫會崩潰的 toInt() 更好——正是因為「不是數字」往往是可預期的情況。

Result<T> 是其中一個工具,能幫你表達:「這個函式可能成功 或 失敗,我會把它當成值回傳,而不是用爆炸的方式傳遞。」

2. 什麼是 Result<T>:在同一個盒子裡放值或錯誤

想像一個貼著「小心」標籤的盒子:裡面不是有一個有用的東西(例如 Int),就是有一張紙條,說明為什麼拿不到那個東西(以 Throwable 的形式)。這就是 Result<T>:一個容器,用來保存執行的兩種可能結果之一——成功時有 T,失敗時有例外。

重點觀念:Result<T> 不是魔法,也不是替代一切做法。它只是傳遞結果的一種形式,當情境是可預期的,就不必逼迫每個呼叫者都寫 try/catch。 同時,「錯誤」也不是字串或 null,而是完整的例外(型別 + 訊息 + 可能的原因)。這很方便,因為 Kotlin 的例外有豐富的型別生態系(NumberFormatException、IllegalArgumentException 等等)。

用示意圖來看,大概會像這樣:

flowchart TD
    A[函式做某些事] --> B{成功了嗎?}
    B -->|是| C["Result.success(value)"]
    B -->|否| D["Result.failure(exception)"]
    C --> E[呼叫端決定:取值、套用 fallback,或停止]
    D --> E

3. 如何建立 Result:success(...) 與 failure(...)

建立 Result 很簡單。有兩個基本的工廠方法:

  • Result.success(value) — 把值包起來。
  • Result.failure(exception) — 把錯誤包起來。

我們先從一個不牽涉專案的超小範例開始——只是為了看清楚機制,不被領域邏輯干擾。

fun main() {
    val ok: Result<Int> = Result.success(10)
    val bad: Result<Int> = Result.failure(IllegalArgumentException("nope"))

    println(ok)   // Success(10)
    println(bad)  // Failure(java.lang.IllegalArgumentException: nope)
}

這還不是「漂亮的應用程式」,但已經能看出來:變數裡存的是結果,而不是「爆了/沒爆」。

接著是一個重要的實務細節:failure 裡的例外越高品質,之後就越容易理解到底發生了什麼。

4. 在專案中用函式回傳 Result

為了不讓範例「在真空中」,我們延續實作型的主控台專案(暫且稱它為 BudgetBuddy):它會保存支出,並能接受 add、list、remove 等指令。我們先不處理檔案或網路——那是課程後面的內容——所以儲存會先放在記憶體中。

在領域模型中,我們有一個支出模型:

data class Expense(
    val id: Int,
    val amount: Int,
    val category: String,
    val note: String
)

現在想像一個典型任務:使用者用文字輸入金額,而我們想把它解析成 Int。如果直接用 toInt()「硬做」,輸入不正確時就會得到 NumberFormatException。

在較早的講次我們已經看過用 toIntOrNull() 做「溫和」解析的作法。現在我們做一個具有顯式合約的版本:回傳 Result<Int>,錯誤時放入帶有清楚訊息的例外。

fun parseAmount(text: String): Result<Int> {
    val trimmed = text.trim()
    val n = trimmed.toIntOrNull()
        ?: return Result.failure(NumberFormatException("Amount is not a number: '$text'"))

    if (n <= 0) {
        return Result.failure(IllegalArgumentException("Amount must be > 0, got $n"))
    }

    return Result.success(n)
}

注意這個風格:我們不把例外往外丟,而是把它包裝成值。還有一點:我們加了 got ...——它能加速診斷,因為訊息裡會顯示實際值。

5. Result 作為合約:函式不替錯誤做最後裁決

很容易誤解 Result:以為它「處理了錯誤」。它沒有處理。它只是很整齊地說:「這是結果,接下來你來決定。」

為了感受這點,我們寫一個建立支出的函式,但回傳 Result<Expense>。它內部會使用 parseAmount。

fun createExpense(id: Int, amountText: String, category: String, note: String): Result<Expense> {
    val amountResult = parseAmount(amountText)
    val amount = amountResult.getOrElse { return Result.failure(it) }

    val cat = category.trim()
    if (cat.isEmpty()) {
        return Result.failure(IllegalArgumentException("Category must not be blank"))
    }

    return Result.success(Expense(id = id, amount = amount, category = cat, note = note.trim()))
}

這裡發生了一個重要的事情:我們把 getOrElse 當成「取值或因錯誤提前返回」的方式。這很像 guard clauses 的風格:一看到無法再正確往下走——就乾淨地回傳錯誤,而不是在整個方法裡寫一個巨大的 if。

而且,我們也可以用例外來做,但那樣呼叫端就必須寫 try/catch(或是程式直接「啪」就結束)。我們的目標是把合約直接寫在型別上,讓它可讀:Result<Expense>。

6. 在 CLI 中使用 Result:取值、分支與 pipeline

當 Result 到了呼叫端,我們就有選擇:取出值、套用備援值、顯示訊息並結束流程,或是再次把錯誤「炸出來」(如果在這一層它已被視為致命錯誤)。

這裡重要的是不要抱著「算了,我就到處塞個 0」的心態。有時候 0 是很好的解法,但有時候那是隱藏錯誤,最後變成壞掉的統計與莫名其妙的報表。

下面是我們今天會用到的主要方法表:

方法 回傳什麼 適用時機 典型風險
getOrNull()
T?
當錯誤「不重要」,可以接受 null 丟失錯誤原因
exceptionOrNull()
Throwable?
想把錯誤單獨取出來並顯示/記錄 忘記處理成功情況
getOrElse { ... }
T
有有意義的 fallback,或想從函式提前返回 做成「萬用補丁」
getOrThrow()
T
或丟出例外
當這一層已把錯誤視為致命 把 Result 變成毫無意義的包裝

接下來用短範例看看它們的行為。

getOrNull() — 把 Result<T> 轉成 T?

當我們刻意想要「柔性行為」時,這個很有用:不是數字就回傳 null。在 Kotlin 中,這種風格你應該已經從 toIntOrNull() 以及集合的 OrNull 系列方法看過了。

fun main() {
    val n: Int? = parseAmount("123").getOrNull()
    println(n) // 123

    val bad: Int? = parseAmount("x").getOrNull()
    println(bad) // null
}

缺點也很明顯:丟失值的原因消失了。所以 getOrNull() 是一個有意識的選擇:「我不在乎原因」。

exceptionOrNull() — 把例外當成資料取出

如果我們需要向使用者解釋為什麼指令沒有成功,通常會想拿到錯誤文字。

fun main() {
    val r = parseAmount("x")
    val msg = r.exceptionOrNull()?.message ?: "OK"
    println(msg) // Amount is not a number: 'x'
}

注意:exceptionOrNull() 回傳 Throwable?,所以這裡自然會用到安全呼叫 ?.。

getOrElse { ... } — 有意義的 fallback 或提前退出

getOrElse 很適合用在你真的知道錯誤時該怎麼辦的情況。例如:使用者沒輸入備註,你可以放入「(no note)」。但在金額這類資料上這麼做就很危險。

我們示範一個 fallback 合理的例子:

fun normalizedNote(note: String): Result<String> =
    if (note.isBlank()) Result.failure(IllegalArgumentException("Empty note"))
    else Result.success(note.trim())

fun main() {
    val note = normalizedNote("   ").getOrElse { "(no note)" }
    println(note) // (no note)
}

這裡的 fallback 是 UX 的一部分,而不是「把問題掃到地毯底下」。

getOrThrow() — 回到例外世界

有時候 Result 用在底層是為了整齊地收集錯誤,但到了上層我們會決定:「如果這裡有錯誤,那就停止,不能再往下。」這時 getOrThrow() 會誠實地把例外丟出去。

fun main() {
    val amount = parseAmount("x").getOrThrow()
    println(amount) // 這裡不會執行到
}

為什麼這不是多此一舉?因為不同層級的策略可以不同。底層可以「封裝」錯誤,而上層可以判斷在此處流程必須結束。

onSuccess {} 與 onFailure {}:不靠 try/catch 的分支

在寫主控台介面時,你常常要做一件簡單的事:成功就印 OK,失敗就印 ERROR: …。這時 onSuccess / onFailure 能避免把程式碼變成一堆 if 的鏈。

做一個小函式,用來印出指令執行結果:

fun printCommandResult(result: Result<String>) {
    result
        .onSuccess { println("OK: $it") }
        .onFailure { println("ERROR: ${it.message}") }
}

使用範例:

fun main() {
    val ok = Result.success("Expense added")
    val bad = Result.failure(IllegalArgumentException("Wrong command"))

    printCommandResult(ok)   // OK: Expense added
    printCommandResult(bad)  // ERROR: Wrong command
}

這還不是「完整的應用程式」,但已經能看出來:分支變得乾淨而且局部化。我們不必捕捉例外——它已經「躺在盒子裡」,而我們只是決定要怎麼呈現它。

在 main 中的 add 指令小型 pipeline

我們組一小段更像真實指令輸入的流程。提醒一下:在前幾天我們已經做過字串解析、正規化、split、指令等。這裡只示範 Result 如何幫我們避免把 main 變成巨大的 try/catch。

指令:
add <amount> <category> <note...>

例如:
add 120 food Coffee

fun handleAddCommand(input: String, nextId: Int): Result<Expense> {
    val parts = input.trim().split(" ")
    if (parts.size < 4) {
        return Result.failure(IllegalArgumentException("Usage: add <amount> <category> <note...>"))
    }

    val amountText = parts[1]
    val category = parts[2]
    val note = parts.drop(3).joinToString(" ")

    return createExpense(id = nextId, amountText = amountText, category = category, note = note)
}

然後在 main 中可能會像這樣:

fun main() {
    val input = "add x food Coffee"
    val result = handleAddCommand(input, nextId = 1)

    result
        .onSuccess { println("Added: $it") }
        .onFailure { println("Cannot add: ${it.message}") }
    // Cannot add: Amount is not a number: 'x'
}

這裡關鍵是:「不是數字」這個錯誤是 NumberFormatException,屬於典型的格式錯誤。但我們不讓它把程式「炸掉」。我們把它變成可控的結果。

如何避免把 Result 變成「藏錯工具」

Result 很容易被用錯:把錯誤包起來、在主控台嘟囔一句,然後繼續當作什麼都沒發生。結果程式變得很「耐打」……但開始說謊。這幾乎就像用膠帶把「Check engine」燈貼住:安靜了,但問題沒有消失。

要避免這件事,一個好規則是:發生錯誤後一定要做出決策。在 CLI 程式裡常見的決策有三種:顯示訊息後繼續迴圈、顯示訊息後結束程式,或套用有意義的 fallback。若你寫了 onFailure { } 卻什麼都不做,就等於在說:「我看到失火了,但決定讓它繼續燒,我只是不看而已。」

一個「良好紀律」的小例子——把 Result 轉成 CLI 直接要印的字串:

fun toCliMessage(result: Result<Expense>): String {
    val e = result.exceptionOrNull()
    return if (e != null) {
        "ERROR: ${e.message}"
    } else {
        val expense = result.getOrThrow()
        "OK: added id=${expense.id}, amount=${expense.amount}"
    }
}

這裡有個細節:我們先檢查是否有錯誤,再呼叫 getOrThrow()——也就是說,只有在我們自己的邏輯被破壞時才會「爆」(例如錯誤是 null 但又沒有值;在正確使用 Result 時通常不會發生)。這種風格類似 fail-fast:應該在程式邏輯壞掉的地方崩潰,而不是在使用者只是輸入了 x 取代數字的地方崩潰。

7. 使用 Result<T> 的常見錯誤

錯誤 1:用 getOrNull() 把 Result 變成 null,然後忘了其實發生過錯誤。
這很常見:只是想「先讓它跑起來」。結果你丟失了原因,也失去向使用者解釋的能力。如果 UX 上需要知道「為什麼」,最好取出 exceptionOrNull() 並組成訊息,而不是默默得到 null。

錯誤 2:把 getOrElse { 0 } 當成萬用補丁。
對支出金額來說,0 看起來也許無害,但可能掩蓋真實問題:例如使用者輸入垃圾內容,而你悄悄記錄了一筆 0 元的支出。之後報表就會「不知為何」對不上。fallback 必須在具體情境中是有意義的,而不是只為了讓編譯器開心。

錯誤 3:寫 Result.failure(Exception("oops")),既沒有語意也沒有實際資料。
oops 這種訊息,最多好笑 3 秒鐘,直到你開始除錯。正常的訊息應該要說明期待什麼、實際得到什麼,並包含實際值(got ...)。

錯誤 4:把 onFailure { } 當成「消音器」,然後若無其事地繼續。
Result 不一定要讓程式崩潰——這是它的優點。但如果錯誤發生時你沒有選擇策略(停止、繼續、fallback),那你不是處理錯誤,而是把它藏起來。這樣 bug 就會安靜地在程式裡旅行,然後在你最不想遇到的那一天找上門。

錯誤 5:函式回傳 Result,但在第一個呼叫點就到處直接呼叫 getOrThrow()。
這會把 Result 變成多餘的包裝:形式上你把例外移到值裡,但立刻又把例外丟回去,並沒有提升可讀性。既然選擇了 Result 這種合約,就讓呼叫端有機會用 onSuccess/onFailure、getOrElse,或轉換成清楚的訊息來有意識地處理結果。

1
任務
Kotlin SELF, 等級 40, 課堂 3
上鎖
計算器的除法
計算器的除法
1
任務
Kotlin SELF, 等級 40, 課堂 3
上鎖
輸入數量
輸入數量
1
任務
Kotlin SELF, 等級 40, 課堂 3
上鎖
玩家暱稱
玩家暱稱
1
任務
Kotlin SELF, 等級 40, 課堂 3
上鎖
最終價格
最終價格
留言
TO VIEW ALL COMMENTS OR TO MAKE A COMMENT,
GO TO FULL VERSION