Come usare le annotazioni in Kotlin?

Le annotazioni in Kotlin vengono utilizzate per aggiungere metainformazioni a classi, proprietà, funzioni, espressioni e parametri. Non eseguono azioni dirette, ma possono essere utilizzate dal compilatore, framework o altre librerie per vari processamenti.

Aspetti principali dell'uso:

1. Sintassi: Le annotazioni sono posizionate prima dell'elemento a cui si applicano, precedute da @. Se l'annotazione ha parametri, questi sono specificati tra parentesi dopo il nome.

   @Deprecated("Usa newFunction invece")
   fun oldFunction() {
       // ...
   }
   
   @JvmStatic
   fun staticMethod() {
       // ...
   }
   

2. Applicazione a diversi elementi: Le annotazioni possono essere applicate a:

   • Classi (class):

     @Serializable
     class User(val name: String)
     

   • Proprietà (val, var):

     @Inject
     lateinit var userRepository: UserRepository
     

   • Funzioni (fun):

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

   • Parametri di costruttori/funzioni:

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

   • Espressioni:

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

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

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

3. Luoghi di applicazione (Use-site Targets): Per disambiguare a quale elemento si applica esattamente l'annotazione, quando ce ne sono più (ad esempio, campo e getter), si utilizzano use-site targets.

   Target	Descrizione
   @file:	Si applica a tutto il file
   @property:	Si applica all'intera proprietà
   @field:	Si applica al campo di backing (backing field)
   @get:	Si applica al getter della proprietà
   @set:	Si applica al setter della proprietà
   @param:	Si applica al parametro del costruttore
   @setparam:	Si applica al parametro del setter della proprietà
   @delegate:	Si applica all'istanza della proprietà delegata
   @receiver:	Si applica al tipo del ricevitore

   class Example(@field:Inject val dependency: Dependency) {
       // @field:Inject si applica al campo 'dependency'
   }
   

4. Dichiarazione di annotazioni personalizzate: Le proprie annotazioni vengono dichiarate con la parola chiave annotation class. I parametri dell'annotazione possono essere di tipi primitivi, stringhe, classi (KClass), enumerazioni, altre annotazioni o array di questi tipi.

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

5. Meta-annotazioni: Le annotazioni possono essere contrassegnate con meta-annotazioni che ne definiscono il comportamento e l'applicabilità.

   • @Target: Indica quali elementi possono essere annotati.
   • @Retention: Indica a quale fase della vita l'annotazione è presente (SOURCE, BINARY, RUNTIME).
   • @Repeatable: Permette di applicare più volte l'annotazione allo stesso elemento.
   • @MustBeDocumented: Indica che l'annotazione deve essere parte dell'API pubblica generata dallo strumento di documentazione.

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

Le annotazioni sono ampiamente utilizzate in Kotlin per integrazione con framework JVM (Spring, Android), serializzazione (Kotlinx.serialization), testing (JUnit) e creazione di librerie proprie basate su metainformazioni.