CodeGym /課程 /Kotlin SELF /宣告處變異(declaration-site variance):在泛型型別中使用 out 與 in

宣告處變異(declaration-site variance):在泛型型別中使用 out 與 in

Kotlin SELF
等級 36, 課堂 1
開放

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(往外輸出)
fun get(): T
是 否
函式參數 in(往內接收)
fun put(x: T)
否 是
val 屬性,其型別為 T out(getter)
val current: T
是 否
var 屬性,其型別為 T 同時是 out 與 in
var current: T
否 否(一般情況下)

這裡有個重要的「一般情況下」:有時你可以透過改設計來繞開限制。 例如 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?), 或乾脆不保存(做成「純處理器」)。

1
任務
Kotlin SELF, 等級 36, 課堂 1
上鎖
記錄快照
記錄快照
1
任務
Kotlin SELF, 等級 36, 課堂 1
上鎖
報表格式化器
報表格式化器
1
任務
Kotlin SELF, 等級 36, 課堂 1
上鎖
唯讀盒子
唯讀盒子
1
任務
Kotlin SELF, 等級 36, 課堂 1
上鎖
字串收集器
字串收集器
留言
TO VIEW ALL COMMENTS OR TO MAKE A COMMENT,
GO TO FULL VERSION