Opt-in Requirements · Kotin知識點難點歸納總結

# 選擇加入的要求 >[info] 【注意】要求選擇加入的注解 `@RequiresOptIn` 與 `@OptIn` 是 *實驗性的*。請參閱[以下](#experimental-status-of-the-opt-in-requirements)用法詳細信息。 >[info] 【注意】1.3.70 中引入了 `@RequireOptIn` 與 `@OptIn` 注解以取代先前使用的 `@Experimental` 與 `@UseExperimental`；同時 `-Xopt-in` 編譯器選項也取代了 `-Xuse-experimental`。 Kotlin 標準庫提供了一種機制，用于要求并明確同意使用 API 的某些元素。通過這種機制，庫開發人員可以將使用其 API 需要選擇加入的特定條件告知用戶，例如，如果某個 API 處于實驗狀態，并且將來可能會更改。為了避免潛在的問題，編譯器會向此類 API 的用戶發出警告，告知他們這些條件，并要求他們在使用 API 之前選擇加入。 ## 選擇使用 API 如果庫作者將一個庫的 API 聲明標記為[_要求選擇加入_](#requiring-opt-in-for-api)，你應該明確同意在代碼中使用它。有多種方式可以選擇加入使用此類 API，所有方法均不受技術限制。你可以自由選擇最適合自己的方式。 ### 傳播選擇加入在使用供第三方（庫）使用的 API 時，你也可以把其選擇加入的要求傳播到自己的 API。為此，請在你的 API 主體聲明中添加注解 [_要求選擇加入的注解_](#opt-in-requirement-annotations)。這可以讓你使用帶有此注解的 API 元素。 ```kotlin // 庫代碼 @RequiresOptIn(message = "This API is experimental. It may be changed in the future without notice.") @Retention(AnnotationRetention.BINARY) @Target(AnnotationTarget.CLASS, AnnotationTarget.FUNCTION) annotation class MyDateTime // 要求選擇加入的注解 @MyDateTime class DateProvider // 要求選擇加入的類 ``` ```kotlin // 客戶端代碼 fun getYear(): Int { val dateProvider: DateProvider // 錯誤：DateProvider 要求選擇加入 // ... } @MyDateTime fun getDate(): Date { val dateProvider: DateProvider // OK：該函數也需要選擇加入 // ... } fun displayDate() { println(getDate()) // 錯誤：getDate() 需要選擇加入 } ``` 如本例所示，帶注釋的函數看起來是 `@MyDateTime` API 的一部分。因此，這種選擇加入會將選擇加入的要求傳播到客戶端代碼；其客戶將看到相同的警告消息，并且也必須同意。要使用多個需要選擇加入的API，請在聲明中標記所有需要選擇加入的注解。 ### 非傳播的用法在不公開其自身API的模塊（例如應用程序）中，你可以選擇使用 API 而無需將選擇加入的要求傳播到代碼中。這種情況下，請使用 [@OptIn](/api/latest/jvm/stdlib/kotlin/-opt-in/index.html) 標記你的聲明，并以要求選擇加入的注解作為參數： ```kotlin // 庫代碼 @RequiresOptIn(message = "This API is experimental. It may be changed in the future without notice.") @Retention(AnnotationRetention.BINARY) @Target(AnnotationTarget.CLASS, AnnotationTarget.FUNCTION) annotation class MyDateTime // 要求選擇加入的注解 @MyDateTime class DateProvider // 要求選擇加入的類 ``` ```kotlin //客戶端代碼 @OptIn(MyDateTime::class) fun getDate(): Date { // 使用 DateProvider；不傳播選擇加入的要求 val dateProvider: DateProvider // ... } fun displayDate() { println(getDate()) // OK：不要求選擇加入 } ``` 當有人調用函數 `getDate()` 時，不會通知他們函數主體中使用的選擇加入 API 的要求。要在一個文件的所有函數和類中使用要求選擇加入的 API，請在文件的頂部，文件包說明和導入聲明前添加文件級注釋 `@file:OptIn`。 ```kotlin //客戶端代碼 @file:OptIn(MyDateTime::class) ``` ### 模塊范圍的選擇加入如果你不想在使用要求選擇加入 API 的每個地方都添加注解，則可以為整個模塊選擇加入這些 API。要選擇在模塊中使用 API，請使用參數 `-Xopt-in` 進行編譯，使用 `-Xopt-in = org.mylibrary.OptInAnnotation` 指定該 API 使用的要求選擇加入注解的標準名稱。使用此參數進行編譯的效果與模塊中每個聲明都有注解 `@OptIn(OptInAnnotation::class)` 的效果相同。如果使用 Gradle 構建模塊，可以添加如下參數： ```groovy compileKotlin { kotlinOptions { freeCompilerArgs += "-Xopt-in=org.mylibrary.OptInAnnotation" } } ``` ```kotlin tasks.withType<KotlinCompile>().all { kotlinOptions.freeCompilerArgs += "-Xopt-in=org.mylibrary.OptInAnnotation" } ``` 如果你的 Gradle 模塊是多平臺模塊，請使用 `useExperimentalAnnotation` 方法： ```groovy sourceSets { all { languageSettings { useExperimentalAnnotation('org.mylibrary.OptInAnnotation') } } } ``` ```kotlin sourceSets { all { languageSettings.useExperimentalAnnotation("org.mylibrary.OptInAnnotation") } } ``` 對于 Maven，它將是： ```xml <build> <plugins> <plugin> <groupId>org.jetbrains.kotlin</groupId> <artifactId>kotlin-maven-plugin</artifactId> <version>${kotlin.version}</version> <executions>...</executions> <configuration> <args> <arg>-Xopt-in=org.mylibrary.OptInAnnotation</arg> </args> </configuration> </plugin> </plugins> </build> ``` 要在模塊級別選擇加入多個 API，請為每個要求選擇加入的 API 添加以上描述的參數之一。 ## 要求選擇加入 API ### 要求選擇加入的注解如果想獲得使用者使用你的模塊 API 的明確同意，請創建一個注解類，作為_要求選擇加入的注解_。這個類必須使用 [@RequiresOptIn](/api/latest/jvm/stdlib/kotlin/-requires-opt-in/index.html) 注解： ```kotlin @RequiresOptIn @Retention(AnnotationRetention.BINARY) @Target(AnnotationTarget.CLASS, AnnotationTarget.FUNCTION) annotation class MyDateTime ``` 要求選擇加入的注解必須滿足以下幾個要求： * `BINARY` [retention](/api/latest/jvm/stdlib/kotlin.annotation/-annotation-retention/index.html) * [targets](/api/latest/jvm/stdlib/kotlin.annotation/-annotation-target/index.html)中沒有 `EXPRESSION` 與 `FILE` * 沒有參數選擇加入的要求可以具有以下兩個嚴格[級別](/api/latest/jvm/stdlib/kotlin/-requires-opt-in/-level/index.html)之一： * `RequiresOptIn.Level.ERROR`。選擇加入是強制性的。否則，使用標記 API 的代碼將無法編譯。默認級別。 * `RequiresOptIn.Level.WARNING`。選擇加入不是強制性的，而是建議使用的。沒有它，編譯器會發出警告。要設置所需的級別，請指定 `@RequiresOptIn` 注解的 `level` 參數。另外，你可以提供一個 `message` 來通知用戶有關使用該 API 的特定條件。編譯器會將其顯示給使用該 API 但未選擇加入的用戶。 ```kotlin @RequiresOptIn(level = RequiresOptIn.Level.WARNING, message = "This API is experimental. It can be incompatibly changed in the future.") @Retention(AnnotationRetention.BINARY) @Target(AnnotationTarget.CLASS, AnnotationTarget.FUNCTION) annotation class ExperimentalDateTime ``` 如果你發布了多個需要選擇加入的獨立功能，請為每個功能聲明一個注解。這使你的用戶可以更安全地使用 API：他們只能使用其明確接受的功能。這也使你可以獨立地從功能中刪除選擇加入的要求。 ### 標記 API 元素要在使用 API 時要求選擇加入，請給它的聲明添加要求選擇加入的注解。 ```kotlin @MyDateTime class DateProvider @MyDateTime fun getTime(): Time {} ``` ## 實驗 API 的選擇加入要求如果要求選擇加入實驗狀態的特性，請仔細處理 API 由實驗狀態到穩定狀態的轉換，以避免破壞客戶端代碼。 API 結束實驗并以穩定狀態發布后，請從聲明中刪除其要求選擇加入的注解。客戶端將可以不受限制地使用它們。但是，你應該將注解類留在模塊中，以便與現有的客戶端代碼保持兼容。為了讓 API 用戶相應地更新其模塊（從代碼中刪除注解并重新編譯），請將注解標記為 [`@Deprecated`](/api/latest/jvm/stdlib/kotlin/-deprecated/index.html)并在棄用 message 中提供說明。 ```kotlin @Deprecated("This opt-in requirement is not used anymore. Remove its usages from your code.") @RequiresOptIn annotation class ExperimentalDateTime ``` ## 選擇加入要求的實驗狀態選擇加入要求的機制在 Kotlin 1.3 中是實驗性的。這意味著在將來的版本中，可能會以不兼容的方式進行更改。為了讓使用注解 `@OptIn` 和 `@RequiresOptIn` 的用戶了解其實驗狀態，編譯器會在編譯代碼時發出警告： ```This class can only be used with the compiler argument '-Xopt-in=kotlin.RequiresOptIn'``` 要移除警告，請添加編譯器參數 `-Xopt-in=kotlin.RequiresOptIn`。