1. 簡介
當你第一次遇到 out 和 in 時,很容易會想:「啊哈,這大概是某種高深的魔法,讓 generics 像繼承那樣運作。」 但更正確的理解其實相反:out/in 是一種不讓你做不安全事情的方法——就算你很想做、就算你覺得「我會很小心」也不行。
想像你正在為我們的教學用主控台應用做一個小模組(例如支出追蹤器)。我們希望寫出能同時處理 Record(基礎紀錄)、ExpenseRecord(支出)、IncomeRecord(收入) 的程式碼。繼承我們已經會了,接下來就會想讓「容器」也能跟著型別階層一起配合。
問題在於容器的角色並不相同。有些容器像「盒子」,我們從裡面取出值; 另一些容器像「投入口/接收器」,我們往裡面放入值; 還有一些同時「既能放也能取」,而通常就是在這種情況下,會出現不變(invariant)與各種限制。
今天的核心概念:宣告處變異(declaration-site variance)指的是你在自訂泛型型別的宣告時,誠實地對編譯器說: 「你看,我只會用 T 以這種方式。」 Kotlin 相信你——並作為交換,允許更彈性的子型別關係(subtyping)。 官方文件用 declaration-site variance 來描述,並以 Source<out T> 為例:如果型別真的只會「輸出」T,就可以用 out 讓它協變。
2. Declaration-site variance:如何宣告 out/in,以及什麼是型別位置(type positions)
接下來我們會自己寫泛型型別,這看起來有點像「存取權限設定」:你彷彿是在設計一個 API,並事先禁止危險操作。
重點是:out 與 in 是寫在型別參數的宣告處, 也就是類別/介面/函式型別的標頭位置,例如 class Box<out T> ... 或 class Sink<in T> ...。 這不是「只針對某個函式的一次性技巧」,而是對整個型別都生效的規則:
- 如果 T 宣告為 out, Kotlin 會嚴格檢查 T 不要在任何地方被當作「輸入」 (例如方法參數、setter 等);
- 如果 T 宣告為 in, Kotlin 會檢查你不要嘗試把型別為 T 的值「精確地」對外輸出。
為什麼要這麼嚴格?因為否則變異性在執行期就會被破壞(就像 Java 的陣列曾經那樣設計,直到現在仍讓人有點頭痛)。 Kotlin 的偏好是:「寧可不編譯,也不要讓你有機會造成型別災難。」
理解編譯器如何判斷 T 在哪裡是「in」、哪裡是「out」很有幫助。 實務上就是看值的流向:你是把它輸出到外面,還是把它接收進來。
下面是一張小抄表。它不能取代理解,但在你盯著編譯錯誤、心裡想「它又想幹嘛」的時候,真的非常有用。
| T 出現的位置 | 此處的 T 是… | 例子 | 在 out T 時允許 | 在 in T 時允許 |
|---|---|---|---|---|
| 函式回傳型別 | out(往外輸出) | |
是 | 否 |
| 函式參數 | in(往內接收) | |
否 | 是 |
| val 屬性,其型別為 T | out(getter) | |
是 | 否 |
| var 屬性,其型別為 T | 同時是 out 與 in | |
否 | 否(一般情況下) |
這裡有個重要的「一般情況下」:有時你可以透過改設計來繞開限制。 例如 consumer 可以用 Any? 來保存值,因為 Any? 並不承諾會是 T。 Producer 也可以提供不接收 T 的操作,而是接收與型別參數無關的東西(例如「重置狀態」)。
3. out T:協變與 producer
現在我們用實作來看 out——這會是最「直覺」的一種,因為它很像你已經用過很久的 List。 理解了它之後,就更容易理解通常更燒腦的 in。
範例用的迷你領域模型
為了避免例子只是「貓狗大戰」(雖然貓狗很努力),我們做一組更像會出現在記帳應用裡的型別:
open class Record(val id: Int, val comment: String)
class ExpenseRecord(
id: Int,
comment: String,
val amount: Int
) : Record(id, comment)
這裡 ExpenseRecord 是 Record 的子型別。 因此 ExpenseRecord 可以用在任何期待 Record 的地方(這是一般的繼承,我們之前就會了)。
「快照」作為 producer:Snapshot<out T>
現在我們建立一個只保存值並把它輸出的型別。 這很像「計算結果的快照」、「伺服器回應」、「已就緒的值」。
class Snapshot<out T>(private val value: T) {
fun get(): T = value
}
請注意:這裡的 T 只出現在 out 位置——也就是由 get() 回傳。 這正是 out 所要求的承諾。
檢查子型別關係:
fun main() {
val expenseSnapshot: Snapshot<ExpenseRecord> =
Snapshot(ExpenseRecord(1, "Coffee", 250))
val recordSnapshot: Snapshot<Record> = expenseSnapshot
println(recordSnapshot.get().comment) // Coffee
}
為什麼這是安全的?因為透過 recordSnapshot 我們無法把「錯的 Record」塞進去。 我們只能讀;而從 Snapshot<ExpenseRecord> 讀出一個 Record 完全沒有問題: 「支出」也是一種「紀錄」。
這也正是 Kotlin 中唯讀集合之所以協變的原因(它們是「值的來源」)。 官方文件也明確指出唯讀集合是協變的。
out 禁止了什麼:不能把 T 當輸入接收
接著我們試著「改良」Snapshot:加上一個 set(newValue: T) 方法,讓它能改變內容。
class Snapshot<out T>(private var value: T) {
fun get(): T = value
// This is not allowed — idea only; it does not compile:
// fun set(newValue: T) { value = newValue }
}
Kotlin 會禁止這件事(而且這是好事)。邏輯是: 如果 Snapshot<ExpenseRecord> 可以指派給 Snapshot<Record>, 然後又能透過 Snapshot<Record> 變數呼叫 set(Record(...)), 那我們就會把「一般的 Record」塞進一個實際上只應該保存 ExpenseRecord 的物件裡。 型別安全就崩了。
也就是說,out 是彈性的代價:你得到沿著型別階層「向上替換」的能力, 但失去以型別 T 作為輸入的安全能力。
陷阱:var 幾乎總是會破壞 out
新手最常遇到的驚訝之一:你宣告了 out T, 接著做了一個 var value: T 的屬性,然後編譯器突然不爽。 原因在於 var 同時具有getter 與 setter。 Getter 會回傳 T(out 位置),setter 會接收 T(in 位置)。 但 out 要求 T 只能用在 out。
看看這個「想法示例」:
// Does not compile — shown as a trap:
// class Box<out T>(var value: T)
如果你需要的是 producer,通常就用 val(唯讀)或把狀態藏在內部,並透過方法輸出。
4. in T:逆變與 consumer
如果 out 常常讓人覺得「合理」,那 in 一開始常會讓人覺得「編譯器在刁難我」。 我們把它弄懂,讓編譯器看起來不像反派,而像是型別安全俱樂部的門口保全。
consumer 的概念:我們只接收 T
我們做一個只接收 T 值、但不把任何「型別為 T」的東西輸出到外部的型別。
例如「格式化器」(它拿到一個物件,產生字串)。對主控台應用很實用:我們一直需要把東西印出來。
class Formatter<in T>(private val toText: (T) -> String) {
fun format(value: T): String = toText(value)
}
注意:T 出現在 format(value: T) 的參數位置——這是 in 位置。 同時 T 也出現在函式型別 (T) -> String 的輸入端; 而函式的輸入端也表現為「in」。
為什麼子型別關係會「反過來」
現在是最有趣的部分:到底誰是誰的子型別?
如果 ExpenseRecord 是 Record 的子型別,那麼 Formatter<Record> 會是 Formatter<ExpenseRecord> 的子型別, 因為 Formatter 是 consumer(逆變)。
聽起來怪,但邏輯很簡單:如果某個物件能格式化任何 Record, 那它當然也能格式化 ExpenseRecord(因為支出只是紀錄的一種特例)。
fun main() {
val recordFormatter: Formatter<Record> =
Formatter { r -> "#${r.id}: ${r.comment}" }
val expenseFormatter: Formatter<ExpenseRecord> = recordFormatter
val e = ExpenseRecord(10, "Taxi", 900)
println(expenseFormatter.format(e)) // #10: Taxi
}
這次我們做了相對於 out「反方向」的指派。 而這對 consumer 來說是正常的:它的關係是鏡像的。
in 禁止了什麼:不能把 T 當精確型別輸出到外部
試著做一個 consumer,它還會「保存最後接收的元素」,並把它回傳出去:
class Sink<in T> {
// Idea that will not compile if you try to return T:
// private var last: T? = null
// fun put(x: T) { last = x }
// fun last(): T? = last
}
為什麼不行?因為如果你有一個 Sink<Record>,並把它指派給 Sink<ExpenseRecord> 的變數(在 in 下這是允許的), 那外部就可能以為 last() 會回傳 ExpenseRecord?。 但實際物件是 Sink<Record>——裡面可能放進任何 Record,不一定是支出。
因此 Kotlin 允許 consumer 型別接收 T, 但不允許它對外「承諾」精確的 T。
5. Kotlin 裡你其實已經遇過的 out/in
有趣的是:你早就用過各種 variance,只是沒注意到。 Kotlin 盡量讓標準函式庫開箱即用就具有「正確的」變異性, 避免你天天手動寫 out/in。
List<out T>:唯讀 producer
唯讀的 List 是協變的,因此 List<ExpenseRecord> 可以用作 List<Record>。 這正是我們上面討論的 producer 邏輯。 文件通常會這樣描述:唯讀集合是協變的。
Comparable<in T>:consumer
在 Comparable 中,型別參數是逆變的:Comparable<in T>。 官方文件的例子是:Comparable<Number> 可以指派給 Comparable<Double>, 因為能比較 Number 的物件,也能比較 Double。
即使你暫時不想深入比較的數學細節,也很值得記住這個形式: 被比較的型別出現在 compareTo(other: T) 的輸入端,因此它是 consumer → in。
函式型別:輸入是 in,輸出是 out
函式型別 (A) -> B 是非常直觀的 variance 模型: 函式消費 A 型別的參數,並產生 B 型別的結果。 因此輸入端表現為 in,輸出端表現為 out。
實務想法:如果你有一個能接收 Record 的函式, 它自然也能接收 ExpenseRecord(因為支出是一種紀錄)。 因此你可以把它用在需要「支出處理器」的地方:
fun main() {
val handleRecord: (Record) -> String = { r -> "Handled: ${r.comment}" }
val handleExpense: (ExpenseRecord) -> String = handleRecord
println(handleExpense(ExpenseRecord(7, "Lunch", 600))) // Handled: Lunch
}
如果你此刻心想「這很像上一講的例子」——沒錯。 現在你只是看見了:這不是巧合,而是同一個 consumer/producer 原則,只是以函式的形式呈現。
6. 實務重構:資料來源與輸出處理器
為了不讓今天的主題停留在「真空」裡,我們把它小心地嵌回主控台應用的邏輯中。 我們不打算做「百年大計」的架構(那是另一門學問), 而是做一件小而清楚的事:用 out/in 把資料取得與輸出格式化分離開來。
報表資料的 producer:ReportSource<out T>
做一個「資料來源」,它把報表元素輸出給外部。它是 producer,所以用 out。
class ReportSource<out T>(private val items: List<T>) {
fun firstOrNull(): T? = items.firstOrNull()
}
使用方式:
fun main() {
val expenses = listOf(
ExpenseRecord(1, "Coffee", 250),
ExpenseRecord(2, "Book", 1200)
)
val expenseSource: ReportSource<ExpenseRecord> = ReportSource(expenses)
val recordSource: ReportSource<Record> = expenseSource
println(recordSource.firstOrNull()?.comment) // Coffee
}
這裡很直觀:支出來源可以當作紀錄來源使用,因為它只「輸出」。
輸出的 consumer:Printer<in T>
接著做一個「印出/輸出」物件,它接收 T 並輸出到主控台。 它是 consumer,所以用 in。
class Printer<in T>(private val toLine: (T) -> String) {
fun print(value: T) {
println(toLine(value))
}
}
並驗證型別替換:
fun main() {
val printRecord = Printer<Record> { r -> "Record: ${r.comment}" }
val printExpense: Printer<ExpenseRecord> = printRecord
printExpense.print(ExpenseRecord(3, "Taxi", 900)) // Record: Taxi
}
能印出「任何 Record」的物件,當然也適用於只需要印出「ExpenseRecord」的地方。 這就是 in 的逆變。
把 producer 與 consumer 串到同一個函式裡
現在我們可以寫一個函式:拿到「來源」和「印表/輸出器」,印出第一個元素。 這裡很值得觀察:out 與 in 如何在同一個場景中一起合作:
fun printFirst(
source: ReportSource<Record>,
printer: Printer<Record>
) {
val first = source.firstOrNull()
if (first != null) {
printer.print(first)
}
}
接著在安全的前提下,把「更具體」與「更一般」的東西代入使用:
fun main() {
val expenses = listOf(ExpenseRecord(1, "Coffee", 250))
val sourceExpenses = ReportSource(expenses) // ReportSource<ExpenseRecord>
val printerRecords = Printer<Record> { "-> ${it.comment}" }
printFirst(sourceExpenses, printerRecords) // -> Coffee
}
為什麼這能編譯?明明 printFirst 期待的是 ReportSource<Record>, 我們卻給了 ReportSource<ExpenseRecord>? 因為 ReportSource 以 out 宣告,因此它是協變的。 那為什麼印表/輸出器也能編譯?因為 Printer 以 in 宣告,因此它是逆變的。
7. 設計 out 與 in 時的常見錯誤
錯誤 №1:加了 out,卻又想做「正常的可變容器(mutable container)」。
非常常見:你寫了 class Box<out T>,然後又新增 fun set(x: T),或做了 var value: T。 編譯器報錯,看起來像是在「毀你人生」。 但其實它是在保護你避免邏輯漏洞:協變型別不能安全地當作 T 的接收器。 如果你需要可變性,要嘛讓型別不變(class Box<T>), 要嘛把 producer 與 consumer 的角色拆成不同型別。
錯誤 №2:加了 in,卻又想把 T 原樣回傳給外部。
consumer 型別常常會想「回傳最後接收的元素」。 但一旦型別變成逆變,回傳 T 就成了不安全的承諾: 外部會期待比實際可能進入的型別更具體的結果。 這種情況下,要嘛回傳更一般的型別(Any?),要嘛改設計: consumer 不一定需要「取出」它接收過的東西。
錯誤 №3:以為 out 代表物件不可變(immutable)。
out 並不等於「immutable」。它的意思是「在我的 API 中,型別參數只用在輸出端」。 你仍然可以有不涉及 T 的方法去改變內部狀態(例如 clear()), 而型別依然可以保持協變。 Variance 只保證型別安全,不保證沒有 mutation——這是兩件不同的事。
錯誤 №4:為了讓它能編譯,就「亂猜」要用 out 還是 in。
out 與 in 不是「修好型別錯誤的萬靈丹」,而是描述意圖與語義。 停止猜的方法是每次都用一句話確認: 我的型別是在產生 T,還是在消費 T? 如果是產生(讀取、取得、回傳)——用 out。 如果是消費(接收、加入、處理輸入)——用 in。 如果同時兩者都有——多半就是不變,並且需要重新設計。
錯誤 №5:困惑為什麼 var 會同時破壞 out 與 in。
屬性 var x: T 同時會輸出 T(getter),也會接收 T(setter)。 因此在帶有 out T 的型別中,它因 setter 而被禁止; 在帶有 in T 的型別中,它因 getter 而被禁止。 如果你想保存某個值但仍保留變異性,通常的做法是: 對 out 用 val; 對 in 則不要以 T 保存,而用更一般的型別(Any?), 或乾脆不保存(做成「純處理器」)。
GO TO FULL VERSION