Jak używać adnotacji w Kotlinie?

Adnotacje w Kotlinie służą do dodawania informacji meta do klas, właściwości, funkcji, wyrażeń i parametrów. Nie wykonują one bezpośrednich działań, ale mogą być używane przez kompilator, frameworki lub inne biblioteki do różnych przetwarzań.

Główne aspekty użycia:

1. Składnia: Adnotacje umieszcza się przed elementem, do którego się odnoszą, poprzedzając je @. Jeśli adnotacja ma parametry, są one podawane w nawiasach po nazwie.

   @Deprecated("Użyj zamiast tego newFunction")
   fun oldFunction() {
       // ...
   }
   
   @JvmStatic
   fun staticMethod() {
       // ...
   }
   

2. Zastosowanie do różnych elementów: Adnotacje mogą być stosowane do:

   • Klas (class):

     @Serializable
     class User(val name: String)
     

   • Właściwości (val, var):

     @Inject
     lateinit var userRepository: UserRepository
     

   • Funkcji (fun):

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

   • Parametrów konstruktorów/funkcji:

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

   • Wyrażeń:

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

   • Typów (@Target(AnnotationTarget.TYPE)):

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

3. Miejsca stosowania (Use-site Targets): Aby rozstrzygnąć, do którego dokładnie elementu odnosi się adnotacja, gdy jest ich kilka (np. pole i getter), używa się use-site targets.

   Target	Opis
   @file:	Dotyczy całego pliku
   @property:	Dotyczy całej właściwości
   @field:	Dotyczy pola zaplecza (backing field)
   @get:	Dotyczy gettera właściwości
   @set:	Dotyczy settera właściwości
   @param:	Dotyczy parametru konstruktora
   @setparam:	Dotyczy parametru settera właściwości
   @delegate:	Dotyczy instancji właściwości delegowanej
   @receiver:	Dotyczy typu odbiorcy

   class Example(@field:Inject val dependency: Dependency) {
       // @field:Inject dotyczy pola 'dependency'
   }
   

4. Deklaracja własnych adnotacji: Własne adnotacje deklaruje się słowem kluczowym annotation class. Parametry adnotacji mogą mieć typy prymitywne, łańcuchy, klasy (KClass), wyliczenia, inne adnotacje lub tablice tych typów.

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

5. Meta-adnotacje: Adnotacje mogą być oznaczone meta-adnotacjami, które określają ich zachowanie i zastosowanie.

   • @Target: Wskazuje, które elementy mogą być adnotowane.
   • @Retention: Wskazuje, na którym etapie życia adnotacja jest obecna (SOURCE, BINARY, RUNTIME).
   • @Repeatable: Pozwala na wielokrotne stosowanie adnotacji do tego samego elementu.
   • @MustBeDocumented: Wskazuje, że adnotacja powinna być częścią publicznego API generowanego przez narzędzie dokumentacyjne.

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

Adnotacje są szeroko stosowane w Kotlinie do integracji z frameworkami JVM (Spring, Android), serializacji (Kotlinx.serialization), testowania (JUnit) i tworzenia własnych bibliotek opartych na meta-informacji.