Skip to content

反射 ​

反射(Reflection)是一組語言與程式庫功能,允許你在執行時期反省(introspect)程式的結構。 例如,你可以讀取或更新屬性、呼叫函式,或是叫用類別建構函式來建立執行個體。當你在編譯期不知道宣告內容時,這會非常有用。

反射提供了描述已編譯宣告的執行時期物件。例如,類別由 KClass 表示、 型別由 KType 表示,而屬性或函式則由 KCallable 的子型別表示。 你可以檢查這些物件,並使用它們來存取值或呼叫函式。

反射的運作方式 ​

反射 API 透過 Kotlin 型別(如 KClass 或 KFunction)來表示已編譯的宣告。 反射物件代表宣告本身,而非所宣告物件的值。例如,你可以使用 KProperty 來取得屬性的名稱並傳回其型別,而無需從特定物件中讀取該屬性。

Kotlin 提供了一些基本功能作為語言和標準程式庫的一部分,例如類別常值或可呼叫參照。若要存取更廣泛的執行時期反省功能,請匯入 kotlin-reflect 程式庫。

反射 API 包含以下套件:

各平台之間的反射支援可能有所不同。本頁面以 Kotlin/JVM 反射 API 為準。進一步了解 Kotlin/JS 中的反射。

與 Java 反射的互通性 ​

在 JVM 上,kotlin-reflect 程式庫在 kotlin.reflect.jvm 套件中提供了擴充功能,用於在 Kotlin 和 Java 反射物件之間進行轉換。例如,你可以找到實作 Kotlin 屬性 getter 的 Java 方法以及該屬性的支援欄位:

kotlin
import kotlin.reflect.jvm.*

class User(val name: String)

fun main() {
    println(User::name.javaGetter)
    // public final java.lang.String User.getName()

    println(User::name.javaField)
    // private final java.lang.String User.name
}

Kotlin 屬性不一定隨時都有對應的 Java 欄位或 getter,因此當沒有相符的 Java 反射物件存在時,這兩個屬性都會傳回 null。

你也可以在 Kotlin KClass 與 Java Class 物件之間進行轉換。若要取得對應於 Java 類別的 Kotlin 類別,請使用 .kotlin 擴充屬性:

kotlin
fun getKClass(o: Any): KClass<Any> = value.javaClass.kotlin

取得執行時期類別 ​

大多數反射操作都始於 KClass。取得它的方式取決於該類別在編譯期是否已知:

  • 使用 ClassName::class 引用編譯期已知的類別。
  • 使用 value::class 取得執行時期值的實際類別,該類別可能比其宣告的型別更具體。
kotlin
import kotlin.reflect.KClass

class User(val name: String)

open class Language
class Kotlin : Language()

fun main() {
    // 傳回代表 User 的 KClass。
    val userClass: KClass<User> = User::class
    println(userClass.simpleName)
    // User
    
    val language: Language = Kotlin()

    // 傳回代表執行時期該值具體類別的 KClass
    val runtimeClass: KClass<out Language> = language::class
    println(runtimeClass.simpleName)
    // Kotlin
}

Kotlin 標準程式庫提供了用於檢查類別的基本工具。若要進行更深入的執行時期反省,請新增 kotlin-reflect 相依性並使用其 API。

新增 JVM 相依性 ​

在 JVM 平台上,Kotlin 編譯器發行版本將使用反射功能所需的執行時期元件作為獨立的構件 kotlin-reflect.jar 提供。這使得不需要反射功能的應用程式可以排除此構件,從而縮減執行時期類別路徑(classpath)的大小。

若要在 Gradle 或 Maven 專案中使用反射,請新增對 kotlin-reflect 的相依性:

kotlin
dependencies {
    implementation(kotlin("reflect"))
}
xml
<dependencies>
    <dependency>
        <groupId>org.jetbrains.kotlin</groupId>
        <artifactId>kotlin-reflect</artifactId>
        <version>${kotlin.version}</version>
    </dependency>
</dependencies>

如果你沒有使用 Gradle 或 Maven,請確保專案的類別路徑中有 kotlin-reflect.jar。命令列編譯器預設會加入該程式庫。若要將其從類別路徑中排除,請使用 -no-reflect 編譯器選項。

檢查型別 ​

KClass 和 KType 代表不同的資訊。KClass 代表一個類別,但不會保留型別引數或可 null 性。例如,List<String> 與 List<Int> 共用相同的 List::class 表示形式,而 String 與 String? 共用 String::class。因此,請使用 typeOf<T>() 函式來取得靜態已知型別 T 的 KType,其中包含其型別引數和可 null 性。

在以下範例中,classifier 屬性將型別連接到其類別或型別參數。arguments 集合包含其型別引數。因此,程式碼可以將 String? 與 List 分開檢查:

kotlin
import kotlin.reflect.typeOf

fun main() {
    val type = typeOf<List<String?>>()

    println(type.classifier)
    // class kotlin.collections.List
    println(type.arguments.single().type)
    // kotlin.String?
}

在 JVM 上,建立的型別沒有註解,即使你在原始碼中對該型別加上了註解也是如此。對型別註解的支援可能會在未來版本的 kotlin-reflect 程式庫中新增。

檢查值 ​

當你直接在程式碼中撰寫目標型別時,is、as 與 as? 運算子 即可發揮作用。但是,如果你將目標類別儲存在 KClass 中,請使用:

  • isInstance() 函式,用於檢查某個值是否為該類別的執行個體。它會傳回 true 或 false。
  • cast() 函式,用於將該值作為目標型別傳回。如果該值為 null 或型別不相容,則會擲回例外狀況。
  • safeCast() 函式,用於將該值作為目標型別傳回;若該值為 null 或型別不相容,則傳回 null。
kotlin
import kotlin.reflect.cast
import kotlin.reflect.safeCast

fun main() {
    val expectedClass = String::class
    val value: Any = "Kotlin"

    // 檢查值而不進行轉換
    println(expectedClass.isInstance(value))
    // true

    // 將值作為 String 傳回
    val text = expectedClass.cast(value)
    println(text.length)
    // 6

    // 不相容的轉換會擲回例外狀況
    val failedCast = runCatching {
        Int::class.cast(value)
    }
    println(failedCast.isFailure)
    // true

    // 安全轉換將相同的不相符情況表示為 null
    val number = Int::class.safeCast(value)
    println(number)
    // null
}

檢查類別 ​

取得 KClass 後,你可以檢查其成員。如此一來,你就可以在使用這些宣告之前了解存在哪些宣告。 使用 members 屬性來檢查類別的函式與屬性。它包含一個 KCallable 物件集合,其中包含類別中可存取的所有宣告(包含繼承的宣告)。

例如,以下程式碼列出了一個資料類別中可存取的函式與屬性:

kotlin
data class User(val name: String, val age: Int)

fun main() {
    println(User::class.members.map { it.name }.sorted())
    // [age, component1, component2, copy, equals, hashCode, name, toString]
}

kotlin.reflect.full 套件提供了更具體的屬性,用於依種類、作用域和接收者選取宣告:

屬性傳回值
declaredMembers直接在類別中宣告的函式與屬性,不包含繼承的宣告
functions該類別可用的所有函式:來自該類別及其超類別的非 static 函式,以及在該類別中宣告的 static 函式
declaredFunctions在該類別中宣告的所有函式
memberFunctions在該類別及其超類別中宣告的非擴充、非 static 函式
declaredMemberFunctions在該類別中宣告的非擴充、非 static 函式
memberExtensionFunctions宣告為該類別或其超類別成員的擴充函式
declaredMemberExtensionFunctions在該類別中宣告的擴充函式
staticFunctions在該類別中宣告的 static 函式
memberProperties在該類別及其超類別中宣告的非擴充屬性
declaredMemberProperties在該類別中宣告的非擴充屬性
memberExtensionProperties宣告為該類別或其超類別成員的擴充屬性
declaredMemberExtensionProperties在該類別中宣告為成員的擴充屬性。
staticProperties代表在 Java 類別中宣告的 static 欄位的屬性

請選擇與你的程式碼所需宣告相符的最精確屬性。例如,序列化器可能使用 declaredMemberProperties 僅處理特定類別引入的屬性,而尋找可呼叫 API 的架構可能同時也需要繼承的 memberFunctions。

你也可以透過反射檢查密封子類別。

讀取屬性 ​

反射允許你讀取在執行時期選取的屬性。 例如,你有一個 UI 組態,指定將 name 作為要從 User 物件顯示的屬性。 為此,應用程式必須找到相符的屬性宣告,然後呼叫其 getter:

kotlin
import kotlin.reflect.full.memberProperties

data class User(val name: String, val age: Int)

fun readProperty(instance: Any, propertyName: String): Any? {
    // 檢查執行時期類別
    val runtimeClass = instance::class

    // 尋找屬性宣告
    val property = runtimeClass.memberProperties
        .firstOrNull { it.name == propertyName }
        ?: error("Unknown property: $propertyName")

    // 以該物件作為接收者呼叫 getter
    return property.getter.call(instance)
}

fun main() {
    val user = User("Jane Doe", 22)

    println(readProperty(user, "name"))
    // Jane Doe
    println(readProperty(user, "age"))
    // 22
}

本範例使用 memberProperties 傳回未綁定的屬性物件。這些物件描述屬於該類別但未附加到特定執行個體的屬性。因此,getter.call() 需要 instance 作為其接收者。結果的型別為 Any?,因為在執行時期選取的屬性可以傳回任何型別。

如果屬性在編譯期已知,請使用直接屬性存取或可呼叫參照,而非反射。

呼叫函式 ​

動態函式呼叫遵循與屬性相同的模式。如果所有引數都按其宣告順序提供,你可以使用 call()。首先傳入未綁定成員函式的物件執行個體,接著加上其常規引數:

kotlin
import kotlin.reflect.full.memberFunctions

class Formatter {
    fun format(text: String, uppercase: Boolean): String =
        if (uppercase) text.uppercase() else text
}

fun main() {
    val formatter = Formatter()

    // 在執行時期依名稱尋找函式
    val function = Formatter::class.memberFunctions
        .single { it.name == "format" }

    // 先提供接收者,然後依序提供宣告的引數
    val result = function.call(formatter, "Kotlin", true)

    println(result)
    // KOTLIN
}

在此範例中,該呼叫包含三個值:Formatter 接收者、text 和 uppercase。它也會傳回 Any? 型別,並在執行時期報告不相容的接收者或引數。

你也可以將值與 KParameter 物件產生關聯,而不是依位置提供引數。為此,請使用 callBy() 函式:

kotlin
import kotlin.reflect.full.instanceParameter
import kotlin.reflect.full.memberFunctions
import kotlin.reflect.full.valueParameters

class Greeter {
    fun greet(name: String, punctuation: String = "!") =
        "Hello, $name$punctuation"
}

fun main() {
    val greeter = Greeter()
    val function = Greeter::class.memberFunctions
        .single { it.name == "greet" }

    // valueParameters 包含在 greet() 中宣告的參數
    // 但不包含 Greeter 接收者
    val nameParameter = function.valueParameters
        .single { it.name == "name" }

    val result = function.callBy(
        mapOf(
            // 成員函式需要執行個體接收者
            function.instanceParameter!! to greeter,
            nameParameter to "Kotlin"
        )
    )

    println(result)
    // Hello, Kotlin!
}

在此範例中,instanceParameter 識別成員函式接收者,而 valueParameters 僅包含在函式簽章中宣告的參數。

當完整的有序引數清單已準備就緒時,請使用 call()。

當你需要將引數與參數物件進行配對,或讓選用參數使用其預設值時,請使用 callBy()。