O que é Annotation em Kotlin?

Annotations (anotações) são metadados que você adiciona ao código para fornecer informações extras ao compilador, a ferramentas de build ou a frameworks em tempo de execução. Elas não mudam o comportamento do código diretamente, mas servem como instruções pra quem processa o código.

Se você já usou @Override em Java ou @Composable no Jetpack Compose, já usou annotations.

Usando annotations existentes

class Animal {
    @Deprecated("Use falar() no lugar", ReplaceWith("falar()"))
    fun emitirSom() {
        println("Som genérico")
    }

    fun falar() {
        println("Som do animal")
    }
}

fun main() {
    val animal = Animal()
    animal.emitirSom()  // Aviso: Deprecated
    animal.falar()
}

Annotations comuns do Kotlin:

  • @Deprecated — marca algo como obsoleto
  • @Suppress — suprime avisos do compilador
  • @JvmStatic — gera método estático pra interop com Java
  • @Throws — declara exceções pra interop com Java

Criando suas próprias annotations

@Target(AnnotationTarget.FUNCTION)
@Retention(AnnotationRetention.RUNTIME)
annotation class LogExecucao(val nivel: String = "INFO")

@LogExecucao(nivel = "DEBUG")
fun processarDados() {
    println("Processando...")
}

Os meta-annotations controlam o comportamento:

  • @Target — onde pode ser aplicada (classe, função, propriedade, etc.)
  • @Retention — se fica disponível em runtime, só no binário, ou só no código fonte

Exemplo prático: validação

@Target(AnnotationTarget.PROPERTY)
@Retention(AnnotationRetention.RUNTIME)
annotation class CampoObrigatorio

data class Formulario(
    @CampoObrigatorio val nome: String,
    @CampoObrigatorio val email: String,
    val telefone: String = ""
)

Depois, usando reflexão, dá pra verificar quais campos têm @CampoObrigatorio e validar automaticamente.

Annotations com use-site targets

Em Kotlin, como propriedades geram campo, getter e setter, às vezes é necessário especificar onde a annotation vai:

class Config(
    @field:NotNull val nome: String,
    @get:JsonProperty("valor_padrao") val valorPadrao: String
)

Annotations são fundamentais no ecossistema Kotlin, especialmente com Spring Boot, Ktor, Room e outros frameworks que dependem de metadados para funcionar.