Kotlin Academy · Урок

Определение аннотаций

Создавайте собственные аннотации

«Определение аннотаций» — бесплатный урок Kotlin Academy на CoddyKit. Это урок 2 из 4. Ты можешь прочитать весь урок бесплатно ниже — а потом практиковать его прямо в браузере с встроенным редактором кода и ИИ-репетитором 24/7. Это часть пути обучения Kotlin Academy, и твой прогресс синхронизируется между веб-версией и приложением CoddyKit. Курс Kotlin Academy содержит 4 уроков всего.

Объявление аннотации

Аннотация определяется с помощью ключевых слов annotation class. Самая простая аннотация не содержит данных и служит маркером.

annotation class Beta

@Beta
fun newFeature() = "experimental"

fun main() {
    println(newFeature())
}

Параметры аннотаций

Аннотации могут хранить данные в параметрах конструктора. Допустимые типы ограничены: примитивные типы, String, перечисления, другие аннотации, KClass и массивы этих типов.

annotation class ApiVersion(val value: Int)

@ApiVersion(2)
fun endpoint() = "v2"

fun main() {
    println(endpoint())
}

@Target

@Target ограничивает места, где можно применять Вашу аннотацию. Вы передаёте одно или несколько значений AnnotationTarget, например CLASS, FUNCTION или PROPERTY.

@Target(AnnotationTarget.FUNCTION)
annotation class Loggable

@Loggable
fun process() = "processing"

fun main() {
    println(process())
}

@Retention

@Retention управляет тем, как долго сохраняется аннотация:

SOURCE — компилятор отбрасывает её
BINARY — сохраняется в файле класса, но недоступна через рефлексию
RUNTIME — сохраняется и доступна через рефлексию (значение по умолчанию)

@Retention(AnnotationRetention.RUNTIME)
annotation class Important

@Important
class Order

fun main() {
    println("Important is readable at runtime")
}

Несколько целей

Перечислите несколько целей, чтобы разрешить применение аннотации в разных местах. В этом примере аннотацию можно применять и к классам, и к функциям.

@Target(AnnotationTarget.CLASS, AnnotationTarget.FUNCTION)
annotation class Audited

@Audited
class Account {
    @Audited
    fun withdraw() = "ok"
}

fun main() {
    println(Account().withdraw())
}

Значения параметров по умолчанию

У параметров аннотаций могут быть значения по умолчанию, поэтому вызывающий код может не указывать их. Это делает распространённые случаи использования более краткими.

annotation class Cache(val seconds: Int = 60)

@Cache
fun cheap() = 1

@Cache(seconds = 300)
fun expensive() = 2

fun main() {
    println("" + cheap() + " " + expensive())
}

Параметры-массивы

Вы можете использовать типы массивов. Передавайте значения с помощью синтаксиса литерала массива [ ... ] при использовании аннотации.

annotation class Roles(val names: Array<String>)

@Roles(["admin", "editor"])
fun restricted() = "secret"

fun main() {
    println(restricted())
}

@Repeatable

По умолчанию аннотацию можно указать для элемента только один раз. Пометьте её аннотацией @Repeatable, чтобы применять её несколько раз.

@Repeatable
annotation class Tag(val value: String)

@Tag("db")
@Tag("cache")
fun layered() = "ok"

fun main() {
    println(layered())
}

Вложенные параметры аннотаций

Параметром аннотации может быть другая аннотация, что позволяет создавать структурированные метаданные.

annotation class Author(val name: String)
annotation class Module(val owner: Author)

@Module(Author("Grace"))
class Payments

fun main() {
    println("Nested annotation metadata defined")
}

Создание качественных аннотаций

Хорошо спроектированная аннотация:

Имеет ясное единственное назначение
Задаёт @Target, чтобы неправильное использование вызывало ошибку компиляции
Использует сохранение RUNTIME только тогда, когда это нужно для рефлексии
Предоставляет разумные значения по умолчанию

От определения к использованию

Определение аннотации — только половина дела. Сама по себе она представляет собой неактивные метаданные. Кто-то должен её прочитать — обычно это делает рефлексия во время выполнения или обработчик аннотаций во время компиляции. Вскоре Вы воспользуетесь рефлексией.

Быстрая проверка

Проверьте, насколько хорошо Вы поняли определение аннотаций.

Итоги

Вы научились определять аннотации:

annotation class с параметрами
@Target для ограничения места применения
@Retention для управления сроком сохранения
@Repeatable и значения по умолчанию

Далее: изучение типов с помощью рефлексии.

Часто задаваемые вопросы

Урок «Определение аннотаций» бесплатный?

Да — полный текст урока «Определение аннотаций» бесплатно доступен здесь в веб-версии. Чтобы практиковать его интерактивно (встроенный редактор кода и ИИ-репетитор 24/7) и разблокировать остальной курс Kotlin Academy, подпишись на CoddyKit PRO. Курс Kotlin Academy содержит 4 уроков всего.

Чему я научусь в уроке «Определение аннотаций»?

Создавайте собственные аннотации Ты практикуешь Kotlin Academy с помощью реального кода, который запускаешь прямо в браузере, и ИИ-репетитор 24/7 отвечает на твои вопросы во время урока.

Нужен ли мне опыт, чтобы начать Kotlin Academy?

Предыдущий опыт не требуется. Kotlin Academy на CoddyKit структурирован для всех уровней — от новичков до продвинутых, поэтому ты можешь начать отсюда или с самого начала и учиться в своем темпе. Это урок 2 из 4.

Сколько времени занимает урок «Определение аннотаций»?

Большинство уроков CoddyKit занимают около 5–10 минут. Каждый из них компактный и интерактивный, поэтому ты постоянно делаешь прогресс и продолжаешь с того же места в веб-версии и приложении.

Можно ли писать и запускать код в этом уроке Kotlin Academy?

Да. Каждый урок Kotlin Academy включает встроенный редактор кода, поэтому ты пишешь и запускаешь реальный код прямо в браузере и получаешь моментальную обратную связь от AI — локальная установка не требуется.

Все уроки этого курса

← Назад к Kotlin Academy