Como usar anotações em Kotlin?

As anotações em Kotlin são usadas para adicionar metainformação a classes, propriedades, funções, expressões e parâmetros. Elas não realizam ações diretas, mas podem ser usadas pelo compilador, frameworks ou outras bibliotecas para diferentes processamentos.

Aspectos principais de uso:

1. Sintaxe: As anotações são colocadas antes do elemento ao qual se aplicam, precedidas de @. Se a anotação tiver parâmetros, eles são especificados entre parênteses após o nome.

   @Deprecated("Use newFunction em vez disso")
   fun oldFunction() {
       // ...
   }
   
   @JvmStatic
   fun staticMethod() {
       // ...
   }
   

2. Aplicação a diferentes elementos: As anotações podem ser aplicadas a:

   • Classes (class) :

     @Serializable
     class User(val name: String)
     

   • Propriedades (val, var) :

     @Inject
     lateinit var userRepository: UserRepository
     

   • Funções (fun) :

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

   • Parâmetros de construtores/funções :

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

   • Expressões :

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

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

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

3. Lugares de aplicação (Use-site Targets): Para desambiguar a qual elemento exatamente a anotação se aplica, quando há várias (por exemplo, campo e getter), usam-se use-site targets.

   Target	Descrição
   @file:	Aplica-se a todo o arquivo
   @property:	Aplica-se à propriedade inteira
   @field:	Aplica-se ao campo de backing (backing field)
   @get:	Aplica-se ao getter da propriedade
   @set:	Aplica-se ao setter da propriedade
   @param:	Aplica-se ao parâmetro do construtor
   @setparam:	Aplica-se ao parâmetro do setter da propriedade
   @delegate:	Aplica-se à instância da propriedade delegada
   @receiver:	Aplica-se ao tipo receptor

   class Example(@field:Inject val dependency: Dependency) {
       // @field:Inject aplica-se ao campo 'dependency'
   }
   

4. Declaração de anotações personalizadas: Anotações próprias são declaradas com a palavra-chave annotation class. Os parâmetros da anotação podem ser de tipos primitivos, strings, classes (KClass), enumerações, outras anotações ou arrays desses tipos.

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

5. Meta-anotações: Anotações podem ser marcadas com meta-anotações que definem seu comportamento e aplicabilidade.

   • @Target: Indica quais elementos podem ser anotados.
   • @Retention: Indica em que etapa da vida a anotação está presente (SOURCE, BINARY, RUNTIME).
   • @Repeatable: Permite aplicar a anotação várias vezes ao mesmo elemento.
   • @MustBeDocumented: Indica que a anotação deve fazer parte da API pública gerada pela ferramenta de documentação.

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

Anotações são amplamente usadas em Kotlin para integração com frameworks JVM (Spring, Android), serialização (Kotlinx.serialization), testes (JUnit) e criação de bibliotecas próprias baseadas em metainformação.