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 是很好的解法,但有時候那是隱藏錯誤,最後變成壞掉的統計與莫名其妙的報表。
下面是我們今天會用到的主要方法表:
| 方法 | 回傳什麼 | 適用時機 | 典型風險 |
|---|---|---|---|
|
|
當錯誤「不重要」,可以接受 null | 丟失錯誤原因 |
|
|
想把錯誤單獨取出來並顯示/記錄 | 忘記處理成功情況 |
|
|
有有意義的 fallback,或想從函式提前返回 | 做成「萬用補丁」 |
|
或丟出例外 |
當這一層已把錯誤視為致命 | 把 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,或轉換成清楚的訊息來有意識地處理結果。
GO TO FULL VERSION