Hogyan használjuk az annotációkat Kotlinben?

A Kotlinban az annotációkat meta-információk hozzáadására használják osztályokhoz, tulajdonságokhoz, függvényekhez, kifejezésekhez és paraméterekhez. Nem hajtanak végre közvetlen műveletet, de fordító, keretrendszerek vagy más könyvtárak által különböző feldolgozásokhoz használhatók.

Főbb felhasználási szempontok:

1. Szintaxis: Az annotációkat az elem előtt helyezzük el, szögletes zárójelek között @ jellel. Ha az annotációnak paraméterei vannak, azok a név után zárójelben szerepelnek.

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

2. Alkalmazás különböző elemekre: Az annotációk alkalmazhatók:

   • Osztályokra (class):

     @Serializable
     class User(val name: String)
     

   • Tulajdonságokra (val, var):

     @Inject
     lateinit var userRepository: UserRepository
     

   • Függvényekre (fun):

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

   • Konstruktor és függvény paraméterekre:

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

   • Kifejezésekre:

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

   • Típusokra (@Target(AnnotationTarget.TYPE)):

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

3. Alkalmazási helyek (Use-site Targets): Az annotáció alkalmazásának pontos helyének diszambiguálására, ha több helyen is alkalmazható (pl. mező és getter), use-site targets használhatók.

   Target	Leírás
   @file:	Az egész fájlra alkalmazva
   @property:	Az egész tulajdonságra alkalmazva
   @field:	A backing field-re alkalmazva
   @get:	A tulajdonság getterére alkalmazva
   @set:	A tulajdonság setterére alkalmazva
   @param:	A konstruktor vagy függvény paraméterére alkalmazva
   @setparam:	A setter paraméterére alkalmazva
   @delegate:	A delegált tulajdonság példányára alkalmazva
   @receiver:	A fogadó típusára alkalmazva

   class Example(@field:Inject val dependency: Dependency) {
       // @field:Inject alkalmazva a 'dependency' mezőre
   }
   

4. Saját annotációk deklarálása: Saját annotációk annotation class kulcsszóval deklarálhatók. Az annotáció paraméterei primitív típusok, stringek, osztályok (KClass), enumok, más annotációk vagy ezek tömbjei lehetnek.

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

5. Meta-annotációk: Az annotációkat meta-annotációkkal lehet ellátni, amelyek meghatározzák viselkedésüket és alkalmazhatóságukat.

   • @Target: Megadja, mely elemek annotálhatók.
   • @Retention: Megadja, hogy az annotáció melyik életciklusban legyen jelen (SOURCE, BINARY, RUNTIME).
   • @Repeatable: Lehetővé teszi ugyanazon annotáció többszöri alkalmazását.
   • @MustBeDocumented: Megadja, hogy az annotációnak része legyen a nyilvános API-nak, amit dokumentációs eszközök generálnak.

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

Az annotációk széles körben használatosak Kotlinben JVM keretrendszerekkel (Spring, Android), szériázásnál (Kotlinx.serialization), tesztelésnél (JUnit) és saját könyvtárak létrehozásánál, meta-információkra alapozva.