0Pricing
Kotlin Academy · Aula

Criando e direcionando anotações personalizadas

Defina anotações com políticas de retenção e aplique-as a classes, funções e propriedades.

Criando e direcionando anotações personalizadas é uma aula grátis de Kotlin Academy no CoddyKit. Esta é a aula 2 de 4. Você pode ler a aula completa abaixo gratuitamente — depois pratica ao vivo no navegador com um editor de código integrado e um tutor de IA 24/7. Faz parte do caminho de aprendizado de Kotlin Academy, e seu progresso é sincronizado entre a web e o app CoddyKit. O curso de Kotlin Academy inclui 4 aulas no total.

Por que usar anotações personalizadas?

Anotações são metadados associados a declarações (classes, funções, propriedades e parâmetros). As anotações personalizadas permitem marcar código para processamento por estruturas, ferramentas de compilação (KSP/KAPT) ou pela sua própria lógica em tempo de execução.

Declarando uma anotação

Use a palavra-chave annotation class. As classes de anotação podem ter parâmetros de construtor (apenas tipos primitivos, String, KClass, enumerações, outras anotações ou vetores desses tipos):

annotation class Validate(val minLength: Int = 1, val maxLength: Int = 255)

Meta-anotações: @Target

@Target restringe onde a anotação pode ser usada. Alvos comuns: CLASS, FUNCTION, PROPERTY, FIELD, VALUE_PARAMETER, CONSTRUCTOR.

@Target(AnnotationTarget.PROPERTY, AnnotationTarget.VALUE_PARAMETER)
annotation class Validate(val minLength: Int = 1, val maxLength: Int = 255)

@Retention: quando a anotação está disponível

@Retention controla o ciclo de vida da anotação:

  • SOURCE — descartada após a compilação
  • BINARY — armazenada no arquivo .class, mas não visível por reflexão
  • RUNTIME — armazenada e visível em tempo de execução (padrão na maioria dos casos)
@Retention(AnnotationRetention.RUNTIME)
@Target(AnnotationTarget.PROPERTY)
annotation class Validate(val minLength: Int = 1)

@Repeatable: aplicando a mesma anotação várias vezes

Por padrão, uma anotação só pode ser aplicada uma vez por declaração. Marque-a com @Repeatable para permitir várias aplicações:

@Repeatable
@Target(AnnotationTarget.FUNCTION)
annotation class Role(val name: String)

Anotando construtores e parâmetros

Você pode anotar parâmetros de construtores e propriedades do construtor primário. Use os alvos do local de uso @field:, @get: ou @param: para controlar qual elemento recebe a anotação:

data class User(
    @field:Validate(minLength = 2) val name: String,
    @field:Validate(minLength = 0, maxLength = 120) val email: String
)

Alvos do local de uso

O Kotlin gera vários elementos de código de bytes a partir de uma única propriedade (campo, acessador de leitura, acessador de escrita, parâmetro). Os alvos do local de uso especificam qual deles recebe a anotação:

  • @field: o campo de armazenamento
  • @get: o acessador de leitura
  • @set: o acessador de escrita
  • @param: o parâmetro do construtor

Anotando classes

Anotações em uma classe são úteis para marcá-la para processamento por uma estrutura (por exemplo, para indicar que uma classe é serializável, injetável ou parte de um módulo específico):

@Target(AnnotationTarget.CLASS)
@Retention(AnnotationRetention.RUNTIME)
annotation class Repository

@Repository
class UserRepository

@MustBeDocumented

Adicionar @MustBeDocumented garante que a anotação apareça na documentação da API gerada. Use-a para anotações que fazem parte do contrato da sua API pública.

@MustBeDocumented
@Target(AnnotationTarget.CLASS)
annotation class PublicApi(val since: String)

Parâmetros de anotações: valores padrão e vetores

Os parâmetros podem ter valores padrão e aceitar vetores usando a palavra-chave vararg ou tipos de vetor explícitos:

annotation class Roles(vararg val value: String)

@Roles("ADMIN", "EDITOR")
class AdminPanel

Parâmetros KClass em anotações

As anotações podem fazer referência a tipos de classe por meio de KClass:

annotation class Serializer(val using: KClass<out Any>)

@Serializer(using = GsonAdapter::class)
class Event

Verificação rápida

Qual valor de @Retention torna uma anotação personalizada acessível por reflexão do Kotlin em tempo de execução?

Recapitulação: anotações personalizadas

Principais conclusões:

  • Declare com annotation class; os parâmetros são limitados a tipos primitivos, String, KClass, enumerações e vetores
  • @Target — onde ela pode ser aplicada
  • @Retention — quando ela está disponível (use RUNTIME para reflexão)
  • @Repeatable — permite várias aplicações em uma declaração
  • Os alvos do local de uso (@field:, @get: etc.) controlam qual elemento de código de bytes recebe a anotação

Perguntas Frequentes

A aula “Criando e direcionando anotações personalizadas” é grátis?

Sim — o texto completo de “Criando e direcionando anotações personalizadas” é grátis para ler aqui na web. Para praticá-la interativamente (um editor de código integrado e um tutor de IA 24/7) e desbloquear o restante do curso de Kotlin Academy, atualize para CoddyKit PRO. O curso de Kotlin Academy inclui 4 aulas no total.

O que vou aprender em “Criando e direcionando anotações personalizadas”?

Defina anotações com políticas de retenção e aplique-as a classes, funções e propriedades. Você pratica Kotlin Academy com código prático que executa diretamente no navegador, e um tutor de IA 24/7 responde suas dúvidas enquanto trabalha na aula.

Preciso ter experiência prévia para começar Kotlin Academy?

Nenhuma experiência prévia é necessária. Kotlin Academy no CoddyKit é estruturado para alunos iniciantes até avançados, então você pode começar aqui ou desde o início e aprender no seu ritmo. Esta é a aula 2 de 4.

Quanto tempo leva a aula “Criando e direcionando anotações personalizadas”?

A maioria das aulas CoddyKit leva cerca de 5–10 minutos. Cada uma é compacta e interativa, então você faz progresso constante e retoma exatamente de onde parou entre web e app.

Posso escrever e executar código nesta aula de Kotlin Academy?

Sim. Cada aula de Kotlin Academy inclui um editor de código integrado, então você escreve e executa código real direto no navegador e recebe feedback de IA instantaneamente — nenhuma configuração local necessária.

Todas as aulas deste curso

  1. Reflexão no Kotlin: KClass, KFunction, KProperty
  2. Criando e direcionando anotações personalizadas
  3. Lendo anotações em tempo de execução
  4. Validação e mapeamento baseados em reflexão
← Voltar para Kotlin Academy