Kā izmantot anotācijas Kotlin?

Kotlin anotācijas tiek izmantotas metainformācijas pievienošanai klasēm, īpašībām, funkcijām, izteiksmēm un parametriem. Tās neveic tiešu darbību, bet var tikt izmantotas kompilatora, ietvara vai citu bibliotēku dažādiem apstrādes mērķiem:

Galvenie lietošanas aspekti:

1. Sintakse: Anotācijas tiek norādītas pirms elementa, uz kuru tās attiecas, leņķa iekavās @. Ja anotācijai ir parametri, tie tiek norādīti pēc nosaukuma iekavās:

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

2. Pielietojums dažādiem elementiem: Anotācijas var tikt izmantotas:

   • Klases (class):

     @Serializable
     class User(val name: String)
     

   • Īpašībām (val, var):

     @Inject
     lateinit var userRepository: UserRepository
     

   • Funkcijām (fun):

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

   • Konstruktoru/funkciju parametriem:

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

   • Izteiksmēm:

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

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

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

3. Lietojuma vietas (Use-site Targets): Lai precizētu, uz kura elementa tiek piemērota anotācija, kad to ir vairāk, tiek izmantoti use-site targets:

   Target	Apraksts
   @file:	Tiek piemērots visai faila daļai
   @property:	Tiek piemērots visai īpašībai
   @field:	Tiek piemērots fona laukam (backing field)
   @get:	Tiek piemērots īpašības getter'im
   @set:	Tiek piemērots īpašības setter'im
   @param:	Tiek piemērots konstruktoru/funkcijas parametram
   @setparam:	Tiek piemērots īpašības setter parametram
   @delegate:	Tiek piemērots deleģētās īpašības instancēm
   @receiver:	Tiek piemērots saņēmēja tipam

   class Example(@field:Inject val dependency: Dependency) {
       // @field:Inject tiek piemērots laukam 'dependency'
   }
   

4. Lietotāja definētas anotācijas: Pašas anotācijas tiek definētas ar annotation class. Anotācijas parametri var būt primitiivi tipi, virknes, klases (KClass), saraksti, citas anotācijas vai to masīvi:

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

5. Meta-anotācijas: Anotācijas var tikt atzīmētas ar meta-anotācijām, kas nosaka to uzvedību un piemērojamību:

   • @Target: norāda, kuri elementi var tikt anotēti.
   • @Retention: norāda, kad anotācija ir pieejama (SOURCE, BINARY, RUNTIME).
   • @Repeatable: ļauj vairākas reizes piemērot anotāciju vienam elementam.
   • @MustBeDocumented: norāda, ka anotācijai jābūt daļai no publiskā API, kas ģenerēts ar dokumentācijas rīku.

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

Anotācijas plaši tiek izmantotas Kotlinā JVM ietvaros (Spring, Android), serializācijā (Kotlinx.serialization), testēšanā (JUnit) un savu bibliotēku izstrādē, kas balstīta uz metainformāciju.