明确要求使用者同意的功能(Opt-in Requirement)

同意使用 API

局部同意

当你在你的代码中使用一个特定的 API 元素时, 要表示同意, 请使用 @OptIn 注解, 注解中引用实验性 API 的标注. 例如, 假设你想要使用 DateProvider 类, 它要求使用者同意:

// 库代码
@RequiresOptIn(message = "This API is experimental. It could change in the future without notice.")
@Retention(AnnotationRetention.BINARY)
@Target(AnnotationTarget.CLASS, AnnotationTarget.FUNCTION)
annotation class MyDateTime

@MyDateTime
// 一个明确要求使用者同意的类
class DateProvider

在你的代码中, 在声明一个使用 DateProvider 类的函数之前, 请添加 @OptIn 注解, 其中包含 MyDateTime 注解类的引用:

// 库的使用者代码
@OptIn(MyDateTime::class)

// 使用 DateProvider
fun getDate(): Date {
    val dateProvider: DateProvider
    // ...
}

需要注意的是, 使用这种方法时, 如果 getDate() 函数在你的代码的其它地方调用, 或被其它开发者使用, 它本身不需要使用者同意:

// 库的使用者代码
@OptIn(MyDateTime::class)

// 使用 DateProvider
fun getDate(): Date {
    val dateProvider: DateProvider
    // ...
}

fun displayDate() {
    // OK: 不需要使用者同意
    println(getDate())
}

传播同意(opt-in)要求

例如, 在声明使用 DateProvider 类的函数之前, 添加 @MyDateTime 注解:

// 库的使用者代码
@MyDateTime
fun getDate(): Date {
    // OK: 使用这个类的函数本身也要求使用者同意
    val dateProvider: DateProvider
    // ...
}

fun displayDate() {
    println(getDate())
    // 编译错误: getDate() 要求使用者同意
}

在上面的示例中我们可以看到, 被注解的函数变得象是 @MyDateTime API 的一部分. 对使用者同意的强制要求传递到了 getDate() 函数的使用者.

// 库的使用者代码
@MyDateTime
fun getDate(dateProvider: DateProvider = DateProvider()): Date

@MyDateTime
fun displayDate() {
    // OK: 这个函数也要求使用者同意
    println(getDate())
}

类似的, 如果你向一个签名中包含要求使用者同意的类型的声明使用 @OptIn, 那么对使用者同意的强制要求仍然会传播:

// 库的使用者代码
@OptIn(MyDateTime::class)
// 由于签名中存在 DateProvider, 因此会传播对使用者同意的强制要求
fun getDate(dateProvider: DateProvider = DateProvider()): Date

fun displayDate() {
    println(getDate())
    // 编译错误: getDate() 要求使用者同意
}

在传播使用者同意要求时, 很重要的一点是需要了解, 如果一个 API 元素进入稳定版, 不再要求使用者同意, 其它仍然要求使用者同意的 API 元素还是继续处于实验状态. 例如, 假设库作者对 getDate() 函数删除了使用者同意的要求, 因为它现在进入了稳定版:

// 库代码
// 不要求使用者同意
fun getDate(): Date {
    val dateProvider: DateProvider
    // ...
}

如果你使用 displayDate() 函数, 但没有删除使用者同意注解, 那么即使它已经不再需要使用者同意, 但它还是继续保持实验性状态:

// 库的使用者代码

// 仍然处于实验状态!
@MyDateTime
fun displayDate() {
    // 使用稳定版的库函数
    println(getDate())
}

对多个 API 表示使用者同意

@ExperimentalCoroutinesApi
@FlowPreview

或者也可以使用 @OptIn:

@OptIn(ExperimentalCoroutinesApi::class, FlowPreview::class)

在整个源代码文件中表示使用者同意

如果想要对一个源代码文件中的所有类和所有函数使用某个要求使用者同意的 API, 可以在文件最前部, 在包声明和包导入语句之前, 添加源代码文件级别的 @file:OptIn 注解.

// 库的使用者代码
@file:OptIn(MyDateTime::class)

在整个模块中表示使用者同意

如果你不希望在你的代码中每次使用需要同意的 API 的地方都添加标注, 那么你可以在你的整个模块级别上同意使用这些 API. 要在一个模块内同意使用某个 API, 可以使用参数 -opt-in 来编译模块, 并指定你所使用的 API 的要求用户同意标注的完全限定名称: -opt-in=org.mylibrary.OptInAnnotation. 使用这个参数来编译代码, 效果等于让模块内的每一个声明都添加 @OptIn(OptInAnnotation::class) 注解.

import org.jetbrains.kotlin.gradle.tasks.KotlinCompilationTask
// ...

tasks.named<KotlinCompilationTask<*>>("compileKotlin").configure {
    compilerOptions.freeCompilerArgs.add("-opt-in=org.mylibrary.OptInAnnotation")
}

如果你的 Gradle 模块是一个跨平台模块, 请使用 optIn 方法:

sourceSets {
    all {
        languageSettings.optIn("org.mylibrary.OptInAnnotation")
    }
}

<build>
    <plugins>
        <plugin>
            <groupId>org.jetbrains.kotlin</groupId>
            <artifactId>kotlin-maven-plugin</artifactId>
            <version>${kotlin.version}</version>
            <executions>...</executions>
            <configuration>
                <args>
                    <arg>-opt-in=org.mylibrary.OptInAnnotation</arg>
                </args>
            </configuration>
        </plugin>
    </plugins>
</build>

对继承一个类或接口要求使用者同意

要在你的代码中同意使用这样的 API 元素, 并扩展它, 请使用 @SubclassOptInRequired 注解, 其中指定注解类的引用. 例如, 假设你想要使用 CoreLibraryApi 接口, 它要求使用者同意:

// 库代码
@RequiresOptIn(
    level = RequiresOptIn.Level.WARNING,
    message = "Interfaces in this library are experimental"
)
annotation class UnstableApi()

@SubclassOptInRequired(UnstableApi::class)
// 一个接口, 要求使用者同意, 然后才能扩展它
interface CoreLibraryApi

在你的代码中, 在创建一个从 CoreLibraryApi 接口继承的新接口之前, 请添加 @SubclassOptInRequired 注解, 其中指定 UnstableApi 注解类的引用:

// 库的使用者代码
@SubclassOptInRequired(UnstableApi::class)
interface SomeImplementation : CoreLibraryApi

注意, 当你对一个类使用 @SubclassOptInRequired 注解时, 使用者同意的要求不会传播到任何内部类或嵌套类:

// 库代码
@RequiresOptIn
annotation class ExperimentalFeature

@SubclassOptInRequired(ExperimentalFeature::class)
open class FileSystem {
    open class File
}

// 库的使用者代码

// 要求使用者同意
class NetworkFileSystem : FileSystem()

// 嵌套类 class
// 不需要使用者同意
class TextFile : FileSystem.File()

或者, 你也可以使用 @OptIn 注解来表示使用者同意. 你也可以使用实验性标记注解, 将使用者同意要求传播到你的代码中任何使用这个类的地方:

// 库的使用者代码
// 带有 @OptIn 注解
@OptInRequired(UnstableApi::class)
interface SomeImplementation : CoreLibraryApi

// 使用引用注解类的注解
// 传播使用者同意要求
@UnstableApi
interface SomeImplementation : CoreLibraryApi

对使用 API 要求使用者同意

创建表示要求使用者同意(Opt-in requirement)的注解

@RequiresOptIn
@Retention(AnnotationRetention.BINARY)
@Target(AnnotationTarget.CLASS, AnnotationTarget.FUNCTION)
annotation class MyDateTime

请使用 @RequiresOptIn 注解的level 参数来设置你希望的严重级别.

此外, 你还可以为 API 使用者提供一个 message. 对于企图使用这个 API 但没有明确同意的用户, 编译器会显示这个警告信息:

@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 元素

@MyDateTime
class DateProvider

@MyDateTime
fun getTime(): Time {}

对扩展 API 要求使用者同意

@RequiresOptIn(
    level = RequiresOptIn.Level.WARNING,
    message = "Interfaces in this library are experimental"
)
annotation class UnstableApi()

@SubclassOptInRequired(UnstableApi::class)
// 一个接口, 要求使用者同意, 然后才能扩展它
interface CoreLibraryApi

注意, 当你使用 @SubclassOptInRequired 注解来要求使用者同意时, 这个要求不会传播到任何内部类或嵌套类.

关于如何在你的 API 中使用 @SubclassOptInRequired 注解的真实示例, 请参见 kotlinx.coroutines 库中的 SharedFlow 接口.

未稳定发布的 API 对使用者同意的要求

@Deprecated("This opt-in requirement is not used anymore. Remove its usages from your code.")
@RequiresOptIn
annotation class ExperimentalDateTime

明确要求使用者同意的功能(Opt-in Requirement)﻿

同意使用 API﻿

局部同意﻿

传播同意(opt-in)要求﻿

对多个 API 表示使用者同意﻿

在整个源代码文件中表示使用者同意﻿

在整个模块中表示使用者同意﻿

note

对继承一个类或接口要求使用者同意﻿

对使用 API 要求使用者同意﻿

创建表示要求使用者同意(Opt-in requirement)的注解﻿

标记要求使用者同意的 API 元素﻿

对扩展 API 要求使用者同意﻿

未稳定发布的 API 对使用者同意的要求﻿