Как использовать аннотации в Kotlin?

Аннотации в Kotlin используются для добавления метаинформации к классам, свойствам, функциям, выражениям и параметрам. Они не выполняют прямого действия, но могут быть использованы компилятором, фреймворками или другими библиотеками для различной обработки.

Основные аспекты использования:

1. Синтаксис: Аннотации указываются перед элементом, к которому они применяются, в угловых скобках @. Если аннотация имеет параметры, они указываются в скобках после имени.

   @Deprecated("Use newFunction instead")
   fun oldFunction() {
       // ...
   }
   
   @JvmStatic
   fun staticMethod() {
       // ...
   }
   

2. Применение к различным элементам: Аннотации могут применяться к:

   • Классам (class):

     @Serializable
     class User(val name: String)
     

   • Свойствам (val, var):

     @Inject
     lateinit var userRepository: UserRepository
     

   • Функциям (fun):

     @Test
     fun testSomething() {
         // ...
     }
     

   • Параметрам конструкторов/функций:

     fun processUser(@NotNull user: User) {
         // ...
     }
     

   • Выражениям:

     fun calculate(@Ignore parameter: Int) {
         // ...
     }
     

   • Типам (@Target(AnnotationTarget.TYPE)):

     val list: @NotNull List<String> = emptyList()
     

3. Места применения (Use-site Targets): Для disambiguation того, к какому именно элементу применяется аннотация, когда их несколько (например, поле и геттер), используются use-site targets.

   Target	Описание
   @file:	Применяется ко всему файлу
   @property:	Применяется к свойству целиком
   @field:	Применяется к полю бэкинга (backing field)
   @get:	Применяется к геттеру свойства
   @set:	Применяется к сеттеру свойства
   @param:	Применяется к параметру конструктора
   @setparam:	Применяется к параметру сеттера свойства
   @delegate:	Применяется к инстансу делегированного свойства
   @receiver:	Применяется к типу получателя

   class Example(@field:Inject val dependency: Dependency) {
       // @field:Inject применяется к полю 'dependency'
   }
   

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

   annotation class MyAnnotation(val value: String, val count: Int = 0)
   
   @MyAnnotation("Hello", count = 5)
   class AnnotatedClass {
       // ...
   }
   

5. Мета-аннотации: Аннотации могут быть помечены мета-аннотациями, которые определяют их поведение и применимость.

   • @Target: Указывает, какие элементы могут быть аннотированы.
   • @Retention: Указывает, на каком этапе жизни аннотация присутствует (SOURCE, BINARY, RUNTIME).
   • @Repeatable: Позволяет применять аннотацию несколько раз к одному и тому же элементу.
   • @MustBeDocumented: Указывает, что аннотация должна быть частью публичного API, генерируемого инструментом документации.

   @Target(AnnotationTarget.CLASS, AnnotationTarget.FUNCTION)
   @Retention(AnnotationRetention.RUNTIME)
   annotation class ProcessedByFramework
   

Аннотации широко используются в Kotlin для интеграции с JVM фреймворками (Spring, Android), сериализации (Kotlinx.serialization), тестирования (JUnit) и создания собственных библиотек, основанных на метаинформации.