CodeGym /課程 /Kotlin SELF /建立在擴充與運算子之上的迷你 API

建立在擴充與運算子之上的迷你 API

Kotlin SELF
等級 38, 課堂 4
開放

1. 前言

迷你 API 是一小組函式、擴充(extensions)與(有時)運算子,用來讓程式碼更貼近領域(domain)。不是「更貼近 Kotlin」,也不是「更貼近流行 DSL」,而是更貼近你真正正在做的事:新增支出、計算總額、產生報表、格式化輸出。它是一個能減少重複並讓 main 更像「情境腳本」而不是「細節垃圾堆」的層。

很容易把迷你 API 跟「在 Kotlin 上寫自己的程式語言」混為一談。但目標其實更謙遜:讓下一個人(以及兩週後的你)打開檔案就能看懂發生了什麼,而不必猜「這個加號運算子到底是在加總數字,還是在發射火箭」。所以我們會一直用一個問題自我檢查:只看這行程式碼,就能預期會發生什麼嗎?

假設我們在延續一個教學用的命令列支出記帳應用程式(假想的 ExpenseTracker)。以前我們可能有一個 MutableList<Expense>、add/list/remove 等命令,以及幾種報表。現在我們想讓報表的組裝方式可讀且一致——這正是迷你 API 很適合出場的時機。

三條規則:「便宜」、「不驚喜」、「從名稱看得出意義」

當你開始加入擴充與運算子,就會出現一種誘惑:把細節「藏」得太深,讓程式碼變得漂亮,但不再誠實。Kotlin 的慣例提供了一個方向:如果某個東西看起來像屬性,它應該要便宜且沒有意外;如果某個動作很顯眼——最好讓它是一個函式。這在這裡特別有用,因為迷你 API 幾乎總是建立在「常被呼叫的小動作」之上。

把三條規則整理成一個行為檢查清單:

工具 適用時機 讀者的預期 常見「糟糕的驚喜」
擴充函式 fun X.foo() 重複的處理步驟、格式化、小型商業操作 這是一個動作,可以當作動詞來讀 foo 做太多事、碰 I/O、到處改狀態
擴充屬性 val X.bar 衍生值、輕量檢查 它「像欄位」:快、穩定、沒有副作用 get() 會排序清單、印到主控台或去打網路
運算子 operator fun plus/compareTo/get/set 公認語意:相加、比較、索引存取 符號應該能被單一方式解讀 + 會改變物件、[] 做「沒有就新增」、compareTo 用隨便的規則比較
infix fun a foo b 少量且精準:兩側角色「幾乎對等」(如 to) 看起來像一句迷你短語 用在變異(mutation)或在一般函式更清楚的地方

關於 infix,另外也值得記住形式限制:infix 函式必須剛好只有一個參數,不能有 vararg,也不能有預設值。infix 呼叫還有自己的優先順序,因此有些不加括號的表達式,讀起來和實際執行順序可能不一致。

2. 迷你模型與報表

模型:Expense 與 Money

為了讓範例不至於零散,我們先約定一組小型型別,圍繞它們來建迷你 API。我們不深究架構與分層——只是讓程式碼保持整潔並貼近領域。

從金額開始。前面的主題我們已經學過 value class,因此讓金額用「分(cents)」儲存,避免在金融計算裡被 Double 折磨:

@JvmInline
value class Money(val cents: Long)

以及一筆支出:

data class Expense(
    val title: String,
    val amount: Money,
    val category: String
)

目前類別用字串——這是刻意的。是的,我們已經有 enum,但今天的重點不是模型,而是「在輸出之上」建立迷你 API。類別之後可以再獨立改善,而便利層應該能同時支援字串與 enum。

接著決定如何建立報表。最簡單的方式是累積字串,最後用 joinToString("\n")。 但我們希望「新增一行」在所有地方看起來都一致,且格式化規則統一。因此我們建立一個小型累加器類別 Report。

Report 作為累加器:+= 何時合適

運算子 += 常被理解為「這肯定是在改動」。確實如此:依照運算子慣例, a += b 會被編譯成 a.plusAssign(b), 如果有這個方法,且編譯器會期待回傳 Unit。 這非常適合用在累加器:它存在的目的就是讓人往裡面加東西。

做一個會累積行文字的 Report:

class Report {
    private val lines = mutableListOf<String>()

    operator fun plusAssign(line: String) {
        lines.add(line)
    }

    override fun toString(): String = lines.joinToString("\n")
}

這裡有一個關於可預期性的關鍵點:Report 是可變(mutable)的容器物件。因此 += 的確就代表「往內部加入」。這很像 MutableList 上 += 的行為:對可變集合,它會就地加入元素。

用小例子驗證:

fun main() {
    val r = Report()
    r += "TOTAL: 350"
    r += "TOP: food"

    println(r)
    // TOTAL: 350
    // TOP: food
}

如果我們把 r + "..." 做成會變異 r,那會更糟:+ 通常被理解為「產生新值」(例如 List + element,回傳的是新集合)。所以規則很簡單:變異用 plusAssign 或明確的方法;建立新值用 plus。

Report 的擴充:少一點複製貼上,多一點一致性

有了 Report 之後,下一個誘惑是到處手寫字串: "TOTAL: ${...}"、 "COUNT: ${...}" 等等。問題不在於困難,而在於很快就會變成「每個人都用自己的風格」:有的用冒號、有的用破折號、有的空格不同、有的大小寫不同。迷你 API 的目的就是讓風格統一且可重複。

加入一個擴充函式,用同一種格式印出鍵值對:

fun Report.kv(key: String, value: Any?) {
    this += "$key: $value"
}

請注意:我們刻意不做成 infix,也不做成運算子。這就是一個普通的動作「加一行」,而名稱 kv(key-value)很短,但在報表的語境裡仍然可讀。

使用方式:

fun main() {
    val r = Report()
    r.kv("TOTAL", 350)
    r.kv("COUNT", 12)

    println(r)
    // TOTAL: 350
    // COUNT: 12
}

接著加入一些更「領域化」的函式。例如金額輸出:我們不想每次都記得分(cents)的換算。

fun Money.format(): String = "%.2f".format(cents / 100.0)

並在 Report 中使用:

fun Report.money(key: String, value: Money) {
    this += "$key: ${value.format()}"
}

現在金額輸出是穩定的,而 main 裡也不需要順手塞一些「找零用的」算術。

3. 格式化與方便的語法

StringBuilder 迷你 API:沒有魔法的鏈式呼叫

有時候,比起用獨立的類別,直接用字串來組裝報表更方便。Kotlin 在這方面通常使用 StringBuilder,採用「組裝 → 回傳字串」的方式。對於較大的字串,StringBuilder 比在迴圈中做字串串接更好,這也是在它之上建立迷你 API 的好時機。

做一個擴充函式:追加一行(含換行)並回傳 this 以便鏈式呼叫:

fun StringBuilder.line(text: String): StringBuilder =
    append(text).append('\n')

現在組裝就像「一串文字流」:

fun main() {
    val text = StringBuilder()
        .line("Expense report")
        .line("--------------")
        .line("TOTAL: 350")
        .toString()

    print(text)
    // Expense report
    // --------------
    // TOTAL: 350
}

為什麼這是好的迷你 API,而不是「過度設計」?因為意圖非常明確:line("...") 就是加一行。沒有隱藏邏輯、沒有副作用、也不會意外地改到 StringBuilder 之外的任何東西。鏈式呼叫由左到右讀起來像腳本,但仍然誠實透明。

infix 要精準使用:何時才真的可讀

infix 看起來很漂亮,但也很狡猾,因為你會想「到處都用」。慣例建議:只有在兩側角色「功能上相近」時才宣告 infix,例如 to 或 zip;並避免用 infix 來做變異操作。

我們有時候想寫成「鍵–值」對,尤其是打算之後把它們轉成 Map。例如在報表裡,先收集資料再輸出。

做一個 infix eq,用來建立 Pair:

infix fun String.eq(value: Any?): Pair<String, Any?> =
    this to value

使用:

fun main() {
    val p = "TOTAL" eq 350
    println(p) // (TOTAL, 350)
}

這裡 infix 是合理的:左側字串是「鍵」,右側是「值」,角色相當對稱。而且這不是變異,而是建立新值。

實務上的額外好處:從陣列/清單的 Pair 可以用 toMap() 轉成 Map,但要記得鍵必須唯一(最後一個會覆蓋前一個)。

ExpenseTracker 的迷你 API:從支出清單產生報表

現在把所有內容串成一個小故事:我們有一個支出清單,想建立一段簡短的文字報表。不是「超大型系統」,而是一個乾淨的函式,可以從 main 呼叫。

在支出清單上做幾個小型的擴充函式。是的,這是「建在集合之上的 API」,而 Kotlin 標準庫本來就大量這麼做:標準庫很大一部分都是 extension 函式。

計算所有支出的總額:

fun List<Expense>.total(): Money {
    var sum = 0L
    for (e in this) sum += e.amount.cents
    return Money(sum)
}

再做成報表:

fun List<Expense>.toReport(): Report {
    val r = Report()
    r += "Expense report"
    r.money("TOTAL", this.total())
    r.kv("COUNT", this.size)
    return r
}

測試:

fun main() {
    val items = listOf(
        Expense("Coffee", Money(350), "food"),
        Expense("Taxi", Money(1200), "transport")
    )

    println(items.toReport())
    // Expense report
    // TOTAL: 15.50
    // COUNT: 2
}

為什麼這是一個好的迷你 API 層?

  • 第一,main 幾乎不包含細節:它在說「我有支出,幫我做報表」。
  • 第二,toReport() 是有意義的函式,從名稱就能看出回傳的是 Report 物件。
  • 第三,迷你 API 很小:total()、toReport()、Report.kv()、Report.money()、Money.format()。

它不是「什麼都做的萬用函式庫」,而是針對任務的精準便利。

4. 危險地帶與如何選擇工具

迷你 API 什麼時候會變得危險

當你嘗到甜頭,就會想:「那我們把所有動作都變成一個按鈕吧。」這時 Kotlin 就開始考驗你作為工程師的成熟度。

例如,一個糟糕的點子:做一個擴充屬性 val List<Expense>.report: String, 它在內部建立報表、排序、分組與格式化。它看起來像欄位,但實際做了很多工作。慣例建議:屬性只在計算便宜、不丟例外、且在相同狀態下結果穩定時才合適。若報表可能很昂貴——它就應該是一個函式(fun buildReport()),讓讀者預期「要做工作」。

另一個細節是集合運算子。很多人看過 list + element 就以為這是「加到清單裡」。但對 read-only 集合,+ 會回傳新清單;而 += 對 var 變數可能是把結果重新指派回去,對 MutableList 則可能是就地變異。這本身不是問題,前提是你理解它;但在迷你 API 裡最好不要逼讀者猜。因此我們讓 Report 成為帶 plusAssign 的累加器,語意就非常明確。

最後是 infix。是的,a foo b 很漂亮。但 infix 有優先順序,不加括號的表達式有時讀起來跟執行起來不一致。所以 infix 只留給非常簡單的「成對」操作,其餘都用一般函式。

如何選:extension / operator / infix

為了不把這些當成「五十條規則」硬背,最好準備一個簡單的思考流程。想像你要加入一個便利點,按以下順序問自己:

1) 這看起來像「讀取屬性」嗎?
   是 → 用 val(或 extension-val),但前提是便宜且無副作用。
   否 → 繼續。

2) 這是一個有明確動詞的動作嗎?
   是 → 用函式(一般或 extension)。
   否 → 繼續。

3) 這件事有公認的符號(+, [], 比較)嗎?
   是 → 用 operator,但前提是語意要單一且明確。
   否 → 繼續。

4) 兩側「幾乎對等」,而且讀起來像一句話嗎?
   是 → 用 infix(少量、謹慎)。
   否 → 用一般函式,別折磨自己。

這不是「Kotlin 的法律」,而是一種實務習慣,能救你遠離看起來像魔法的程式碼。魔法在正式環境裡的壞處是:它只會一路運作到你遇到第一個 bug——然後你才會突然發現,「魔杖」其實是一根雙面刃。

5. 常見錯誤

錯誤 1:「我能做運算子,所以我就做。」
運算子不是為了好看,而是為了可預期。若 a + b 讀起來不像「相加」,或 obj[i] 讀起來不像「依索引/鍵取值」,你是在讓程式更差。在這些地方,一般方法(addExpense、appendLine)幾乎總是更好。

錯誤 2:把重工作藏在 extension 屬性裡。
屬性看起來像快速讀取資料,因此讀者不會預期排序、分組、建報表,更不會預期例外。慣例建議:屬性只用在便宜且穩定的計算上。工作量明顯時——請做成函式。

錯誤 3:不區分 + 與 += 的語意:「新值」vs「變異」。
在 Kotlin 中 += 會依不同規則編譯:要嘛呼叫 plusAssign,要嘛透過「重新建立」來做 a = a + b。如果你在自訂型別上重載運算子,請保持語意清楚到不行:plus 通常建立新值,plusAssign 則改變既有值。

錯誤 4:用 infix 做變異,或用在兩側角色不對等的動作上。
infix 適合用在兩側邏輯對稱的地方(例如鍵–值或集合聯集),不適合用在一般命令式「去做某事」的場景。慣例也明確建議不要做會變異接收者的 infix 方法。

錯誤 5:把迷你 API 膨脹成「擴充大雜燴」。
如果你把所有擴充都塞進一個叫 Extensions.kt 的千行檔案,你得到的不是迷你 API,而是迷你混亂。最好依主題把擴充分在服務對象附近(例如 ReportExtensions.kt、MoneyFormatting.kt),並避免在不同地方做出同名擴充,否則之後會跟 import 打架。

錯誤 6:做出無法「用眼睛讀懂」的迷你 API。
最糟的可讀性崩壞,是某一行程式碼不再自足:不懂內部約定就無法判斷是變異還是建立新值、呼叫是否昂貴、是否有副作用——這種迷你 API 不是幫忙,而是妨礙。好的便利層仍然透明:它減少噪音,但不隱藏意義。

1
任務
Kotlin SELF, 等級 38, 課堂 4
上鎖
問候信
問候信
1
任務
Kotlin SELF, 等級 38, 課堂 4
上鎖
金額拆分
金額拆分
1
任務
Kotlin SELF, 等級 38, 課堂 4
上鎖
使用者報告
使用者報告
1
任務
Kotlin SELF, 等級 38, 課堂 4
上鎖
儲位倉庫
儲位倉庫
1
問卷/小測驗
擴充函式與運算子,等級 38,課堂 4
未開放
擴充函式與運算子
擴充函式與運算子
留言
TO VIEW ALL COMMENTS OR TO MAKE A COMMENT,
GO TO FULL VERSION