Kaip naudoti anotacijas Kotlin?

Kotlin'e anotacijos naudojamos pridėti metainformaciją prie klasių, savybių, funkcijų, išraiškų ir parametrų. Jos nesukelia tiesioginio veikimo, tačiau gali būti naudojamos kompiliatoriaus, karkaso ar kitų bibliotekų įvairiems apdorojimams:

Pagrindiniai naudojimo aspektai:

1. Sintaksė: Anotacijos nurodomos prieš elementą, prie kurio jos taikomos, kampinėse skliaustinėse @. Jei anotacija turi parametrų, jie nurodomi po vardo skliausteliuose:

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

2. Taikymas įvairiems elementams: Anotacijos gali būti taikomos:

   • Klasėms (class):

     @Serializable
     class User(val name: String)
     

   • Savybėms (val, var):

     @Inject
     lateinit var userRepository: UserRepository
     

   • Funkcijoms (fun):

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

   • Konstruktoriaus/funkcijos parametrams:

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

   • Išraiškoms:

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

   • Tipams (@Target(AnnotationTarget.TYPE)):

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

3. Naudojimo vietos (Use-site Targets): Norint išskirti, prie kurio elemento taikoma anotacija, kai jų keli, naudojami use-site targets:

   Target	Aprašymas
   @file:	Taikoma visai failo sričiai
   @property:	Taikoma visai savybei
   @field:	Taikoma fono laukui (backing field)
   @get:	Taikoma savybės getter'ui
   @set:	Taikoma savybės setter'ui
   @param:	Taikoma konstruktoriaus/funkcijos parametrui
   @setparam:	Taikoma savybės setter parametrui
   @delegate:	Taikoma deleguotos savybės instancijai
   @receiver:	Taikoma gavėjo tipui

   class Example(@field:Inject val dependency: Dependency) {
       // @field:Inject taikoma laukui 'dependency'
   }
   

4. Vartotojo apibrėžtos anotacijos: Savo anotacijas apibrėžia su annotation class. Anotacijos parametrai gali būti pradiniai tipai, eilutės, klasės (KClass), sąrašai, kitos anotacijos arba jų masyvai:

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

5. Meta-anotacijos: Anotacijos gali būti pažymėtos meta-anotacijomis, kurios apibrėžia jų elgseną ir taikymo sritį:

   • @Target: nurodo, kokie elementai gali būti anotiruojami.
   • @Retention: nurodo, kada anotacija galioja (SOURCE, BINARY, RUNTIME).
   • @Repeatable: leidžia taikyti anotaciją kelis kartus vienam elementui.
   • @MustBeDocumented: nurodo, kad anotacija turi būti dokumentacijos API dalis.

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

Anotacijos plačiai naudojamos Kotlin'e JVM karkasuose (Spring, Android), serializacijoje (Kotlinx.serialization), testavime (JUnit) ir kuriant savo bibliotekas, pagrįstas metainformacija.