Требования к явному согласию

Дать согласие локально

Чтобы дать согласие на использование конкретного элемента API в коде, примените аннотацию @OptIn, указав маркер экспериментального API. Например, предположим, что вы хотите использовать класс DateProvider, для которого требуется явное согласие:

// Library code
@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
// A class requiring opt-in
class DateProvider

В коде перед объявлением функции, использующей класс DateProvider, добавьте аннотацию @OptIn со ссылкой на класс аннотации MyDateTime:

// Client code
@OptIn(MyDateTime::class)

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

Важно отметить, что при таком подходе, если функция getDate() вызывается в другом месте кода или используется другим разработчиком, явное согласие не требуется:

// Client code
@OptIn(MyDateTime::class)

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

fun displayDate() {
    // OK: No opt-in is required
    println(getDate()) 
}

Требование явного согласия не распространяется дальше, а это значит, что другие разработчики могут неосознанно использовать экспериментальные API. Чтобы этого избежать, безопаснее распространять требования к явному согласию.

// Client code
@MyDateTime
fun getDate(): Date {
    // OK: the function requires opt-in as well
    val dateProvider: DateProvider
    // ...
}

fun displayDate() {
    println(getDate())
    // Error: getDate() requires opt-in
}

// Client code
@MyDateTime
fun getDate(dateProvider: DateProvider = DateProvider()): Date

@MyDateTime
fun displayDate() {
    // OK: the function requires opt-in as well
    println(getDate())
}

// Client code
@OptIn(MyDateTime::class)
// Propagates opt-in due to DateProvider in the signature
fun getDate(dateProvider: DateProvider = DateProvider()): Date

fun displayDate() {
    println(getDate())
    // Error: getDate() requires opt-in
}

// Library code
// No opt-in requirement
fun getDate(): Date {
    val dateProvider: DateProvider
    // ...
}

// Client code

// Still experimental!
@MyDateTime 
fun displayDate() {
    // Uses a stable library function
    println(getDate())
}

@ExperimentalCoroutinesApi
@FlowPreview

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

Дать согласие для файла

Чтобы использовать API, требующий явного согласия, во всех функциях и классах файла, добавьте аннотацию уровня файла @file:OptIn в начало файла перед объявлением пакета и импортами.

// Client code
@file:OptIn(MyDateTime::class)

Дать согласие для модуля

Если вы не хотите аннотировать каждое использование API, требующего явного согласия, вы можете дать согласие на его использование для всего модуля. Чтобы дать согласие на использование API в модуле, скомпилируйте его с аргументом -opt-in, указав полное имя аннотации требования к явному согласию для используемого API: -opt-in=org.mylibrary.OptInAnnotation. Компиляция с этим аргументом эквивалентна добавлению аннотации @OptIn(OptInAnnotation::class) к каждому объявлению в модуле.

Если вы собираете модуль с помощью Gradle, можно добавить аргументы следующим образом:

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

tasks.named<KotlinCompilationTask<*>>("compileKotlin").configure {
    compilerOptions.optIn.add("org.mylibrary.OptInAnnotation")
}

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

tasks.named('compileKotlin', KotlinCompilationTask) {
    compilerOptions {
        optIn.add('org.mylibrary.OptInAnnotation')
    }
}

Если ваш модуль Gradle является многоплатформенным, используйте метод optIn:

kotlin {
    compilerOptions {
        optIn.add("org.mylibrary.OptInAnnotation")
    }
}

kotlin {
    compilerOptions {
        optIn.add('org.mylibrary.OptInAnnotation')
    }
}

Для Maven используйте следующий вариант:

<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 на уровне модуля, добавьте один из описанных аргументов для каждого маркера требования к явному согласию, используемого в модуле.

Дать согласие на наследование от класса или интерфейса

Иногда автор библиотеки предоставляет API, но хочет требовать от пользователей явного согласия, прежде чем они смогут расширять его. Например, API библиотеки может быть стабильным для использования, но не для наследования, поскольку в будущем в него могут быть добавлены новые абстрактные функции. Авторы библиотек могут обеспечить это, пометив аннотацией @SubclassOptInRequired открытые или абстрактные классы и нефункциональные интерфейсы.

Чтобы дать согласие на использование такого элемента API и расширить его в своём коде, примените аннотацию @SubclassOptInRequired со ссылкой на класс аннотации. Например, предположим, что вы хотите использовать интерфейс CoreLibraryApi, для которого требуется явное согласие:

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

@SubclassOptInRequired(UnstableApi::class)
// An interface requiring opt-in to extend
interface CoreLibraryApi 

В коде перед созданием нового интерфейса, наследующего интерфейс CoreLibraryApi, добавьте аннотацию @SubclassOptInRequired со ссылкой на класс аннотации UnstableApi:

// Client code
@SubclassOptInRequired(UnstableApi::class)
interface SomeImplementation : CoreLibraryApi

Обратите внимание: если применить аннотацию @SubclassOptInRequired к классу, требование явного согласия не распространяется на внутренние или вложенные классы:

// Library code
@RequiresOptIn
annotation class ExperimentalFeature

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

// Client code

// Opt-in is required
class NetworkFileSystem : FileSystem()

// Nested class
// No opt-in required
class TextFile : FileSystem.File()

Кроме того, можно дать согласие с помощью аннотации @OptIn. Также можно использовать аннотацию-маркер экспериментального API, чтобы распространить требование на все случаи использования класса в вашем коде:

// Client code
// With @OptIn annotation
@OptInRequired(UnstableApi::class)
interface SomeImplementation : CoreLibraryApi

// With annotation referencing annotation class
// Propagates the opt-in requirement further
@UnstableApi
interface SomeImplementation : CoreLibraryApi

Создать аннотации требований к явному согласию

Чтобы требовать явного согласия на использование API вашего модуля, создайте класс аннотации, который будет служить аннотацией требования к явному согласию. Этот класс должен быть помечен аннотацией @RequiresOptIn:

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

Аннотации требований к явному согласию должны соответствовать нескольким требованиям. Они должны иметь:

• BINARY или RUNTIME срок хранения.

• Не иметь EXPRESSION, FILE, TYPE или TYPE_PARAMETER в качестве цели применения.

• Не иметь параметров.

Для требования явного согласия можно задать один из двух уровней строгости:

• RequiresOptIn.Level.ERROR. Явное согласие обязательно. Иначе код, использующий помеченный API, не скомпилируется. Это уровень по умолчанию.

• RequiresOptIn.Level.WARNING. Явное согласие не обязательно, но рекомендуется. Без него компилятор выдаст предупреждение.

Чтобы задать нужный уровень, укажите параметр level аннотации @RequiresOptIn.

Кроме того, можно предоставить пользователям 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 безопаснее для клиентов, поскольку они смогут использовать только те функции, на которые явно согласились. Кроме того, это позволит независимо отменять требования к отдельным функциям, упрощая сопровождение API.

Пометить элементы API

Чтобы требовать явного согласия на использование элемента API, пометьте его объявление аннотацией требования к явному согласию:

@MyDateTime
class DateProvider

@MyDateTime
fun getTime(): Time {}

Обратите внимание, что к некоторым элементам языка нельзя применить аннотацию требования к явному согласию:

• Нельзя аннотировать поле хранения или геттер свойства — можно аннотировать только само свойство.

• Нельзя аннотировать локальную переменную или параметр-значение.