0Pricing
Kotlin Academy · Урок

Создание и применение пользовательских аннотаций

Определяйте аннотации с политиками хранения и применяйте их к классам, функциям и свойствам.

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

Зачем нужны пользовательские аннотации

Аннотации — это метаданные, прикреплённые к объявлениям (классам, функциям, свойствам и параметрам). Пользовательские аннотации позволяют помечать код для обработки фреймворками, инструментами сборки (KSP/KAPT) или собственной логикой во время выполнения.

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

Используйте ключевое слово annotation class. У классов аннотаций могут быть параметры конструктора (только примитивные типы, строки, KClass, перечисления, другие аннотации или массивы таких элементов):

annotation class Validate(val minLength: Int = 1, val maxLength: Int = 255)

Метааннотации: @Target

@Target ограничивает места применения аннотации. Распространённые цели: CLASS, FUNCTION, PROPERTY, FIELD, VALUE_PARAMETER, CONSTRUCTOR.

@Target(AnnotationTarget.PROPERTY, AnnotationTarget.VALUE_PARAMETER)
annotation class Validate(val minLength: Int = 1, val maxLength: Int = 255)

@Retention: когда доступна аннотация

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

  • SOURCE — удаляется после компиляции
  • BINARY — сохраняется в файле .class, но недоступна через рефлексию
  • RUNTIME — сохраняется и доступна во время выполнения (значение по умолчанию для большинства случаев)
@Retention(AnnotationRetention.RUNTIME)
@Target(AnnotationTarget.PROPERTY)
annotation class Validate(val minLength: Int = 1)

@Repeatable: многократное применение одной аннотации

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

@Repeatable
@Target(AnnotationTarget.FUNCTION)
annotation class Role(val name: String)

Аннотирование конструкторов и параметров

Можно аннотировать параметры конструктора и свойства первичного конструктора. Используйте цели применения @field:, @get: или @param:, чтобы указать, какой элемент получает аннотацию:

data class User(
    @field:Validate(minLength = 2) val name: String,
    @field:Validate(minLength = 0, maxLength = 120) val email: String
)

Цели применения

Kotlin создаёт несколько элементов байткода из одного свойства (поля, метода получения значения, метода установки значения и параметра). Цели применения указывают, какой из них получает аннотацию:

  • @field: — поле хранения
  • @get: — метод получения значения
  • @set: — метод установки значения
  • @param: — параметр конструктора

Аннотирование классов

Аннотации на классе полезны для пометки класса с целью обработки фреймворком (например, чтобы отметить класс как сериализуемый, доступный для внедрения или относящийся к определённому модулю):

@Target(AnnotationTarget.CLASS)
@Retention(AnnotationRetention.RUNTIME)
annotation class Repository

@Repository
class UserRepository

@MustBeDocumented

Добавление @MustBeDocumented гарантирует, что аннотация появится в сгенерированной документации API. Используйте её для аннотаций, являющихся частью контракта вашего открытого API.

@MustBeDocumented
@Target(AnnotationTarget.CLASS)
annotation class PublicApi(val since: String)

Параметры аннотаций: значения по умолчанию и массивы

Для параметров можно задавать значения по умолчанию и принимать массивы с помощью ключевого слова vararg или явных типов массивов:

annotation class Roles(vararg val value: String)

@Roles("ADMIN", "EDITOR")
class AdminPanel

Параметры KClass в аннотациях

Аннотации могут ссылаться на типы классов через KClass:

annotation class Serializer(val using: KClass<out Any>)

@Serializer(using = GsonAdapter::class)
class Event

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

Какое значение @Retention делает пользовательскую аннотацию доступной через рефлексию Kotlin во время выполнения?

Повторение: пользовательские аннотации

Основные выводы:

  • Объявляйте с помощью annotation class; параметры ограничены примитивными типами, строками, KClass, перечислениями и массивами
  • @Target — где аннотацию можно применить
  • @Retention — когда аннотация доступна (для рефлексии используйте RUNTIME)
  • @Repeatable — разрешает многократное применение к одному объявлению
  • Цели применения (@field:, @get: и т. д.) определяют, какой элемент байткода получает аннотацию

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

Урок «Создание и применение пользовательских аннотаций» бесплатный?

Да — полный текст урока «Создание и применение пользовательских аннотаций» бесплатно доступен здесь в веб-версии. Чтобы практиковать его интерактивно (встроенный редактор кода и ИИ-репетитор 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 — локальная установка не требуется.

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

  1. Рефлексия Kotlin: KClass, KFunction, KProperty
  2. Создание и применение пользовательских аннотаций
  3. Чтение аннотаций во время выполнения
  4. Валидация и отображение на основе рефлексии
← Назад к Kotlin Academy