0Pricing
Kotlin Academy · Lección

Crear y aplicar anotaciones personalizadas

Defina anotaciones con políticas de retención y aplíquelas a clases, funciones y propiedades.

Crear y aplicar anotaciones personalizadas es una lección gratuita de Kotlin Academy en CoddyKit. Esta es la lección 2 de 4. Puedes leer la lección completa abajo gratuitamente — luego la practicas en el navegador con un editor de código integrado y un tutor de IA 24/7. Forma parte de la ruta de aprendizaje de Kotlin Academy, y tu progreso se sincroniza en la web y la app de CoddyKit. El curso de Kotlin Academy incluye 4 lecciones en total.

¿Por qué usar anotaciones personalizadas?

Las anotaciones son metadatos asociados a declaraciones (clases, funciones, propiedades y parámetros). Las anotaciones personalizadas permiten marcar código para que lo procesen frameworks, herramientas de compilación (KSP/KAPT) o su propia lógica en tiempo de ejecución.

Declarar una anotación

Use la palabra clave annotation class. Las clases de anotación pueden tener parámetros de constructor (solo tipos primitivos, String, KClass, enumeraciones, otras anotaciones o matrices de estos tipos):

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

Metaanotaciones: @Target

@Target restringe dónde se puede utilizar la anotación. Destinos habituales: 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: ¿cuándo está disponible la anotación?

@Retention controla el tiempo de vida de la anotación:

  • SOURCE — se descarta después de la compilación
  • BINARY — se almacena en el archivo .class, pero no es visible mediante reflexión
  • RUNTIME — se almacena y es visible en tiempo de ejecución (valor predeterminado para la mayoría de los casos de uso)
@Retention(AnnotationRetention.RUNTIME)
@Target(AnnotationTarget.PROPERTY)
annotation class Validate(val minLength: Int = 1)

@Repeatable: aplicar la misma anotación varias veces

De forma predeterminada, una anotación solo se puede aplicar una vez por declaración. Márquela con @Repeatable para permitir varias aplicaciones:

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

Anotar constructores y parámetros

Puede anotar parámetros de constructores y propiedades del constructor principal. Use los destinos de uso @field:, @get: o @param: para controlar qué elemento recibe la anotación:

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

Destinos de uso

Kotlin genera varios elementos de bytecode a partir de una sola propiedad (campo, getter, setter y parámetro). Los destinos de uso especifican cuál recibe la anotación:

  • @field: el campo de respaldo
  • @get: el getter
  • @set: el setter
  • @param: el parámetro del constructor

Anotar clases

Las anotaciones en una clase resultan útiles para marcarla para su procesamiento por parte de un framework (por ejemplo, para marcarla como serializable, inyectable o perteneciente a un módulo específico):

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

@Repository
class UserRepository

@MustBeDocumented

Añadir @MustBeDocumented garantiza que la anotación aparezca en la documentación de la API generada. Úsela para las anotaciones que formen parte del contrato de su API pública.

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

Parámetros de anotaciones: valores predeterminados y matrices

Los parámetros pueden tener valores predeterminados y aceptar matrices mediante la palabra clave vararg o tipos de matriz explícitos:

annotation class Roles(vararg val value: String)

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

Parámetros KClass en anotaciones

Las anotaciones pueden hacer referencia a tipos de clase mediante KClass:

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

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

Comprobación rápida

¿Qué valor de @Retention hace que una anotación personalizada sea accesible mediante la reflexión de Kotlin en tiempo de ejecución?

Resumen: anotaciones personalizadas

Conclusiones clave:

  • Declare con annotation class; los parámetros están limitados a tipos primitivos, String, KClass, enumeraciones y matrices
  • @Target — dónde se puede aplicar
  • @Retention — cuándo está disponible (use RUNTIME para la reflexión)
  • @Repeatable — permite varias aplicaciones en una declaración
  • Los destinos de uso (@field:, @get:, etc.) controlan qué elemento de bytecode recibe la anotación

Preguntas frecuentes

¿La lección «Crear y aplicar anotaciones personalizadas» es gratis?

Sí — el texto completo de «Crear y aplicar anotaciones personalizadas» es gratis para leer aquí en la web. Para practicarla de forma interactiva (editor de código integrado y tutor de IA 24/7) y desbloquear el resto del curso de Kotlin Academy, actualiza a CoddyKit PRO. El curso de Kotlin Academy incluye 4 lecciones en total.

¿Qué aprenderé en «Crear y aplicar anotaciones personalizadas»?

Defina anotaciones con políticas de retención y aplíquelas a clases, funciones y propiedades. Practicas Kotlin Academy con código real que ejecutas directamente en el navegador, y un tutor de IA 24/7 responde tus preguntas mientras trabajas en la lección.

¿Necesito experiencia previa para empezar Kotlin Academy?

No se requiere experiencia previa. Kotlin Academy en CoddyKit está estructurado para principiantes hasta estudiantes avanzados, así que puedes empezar aquí o desde el inicio y avanzar a tu ritmo. Esta es la lección 2 de 4.

¿Cuánto tiempo toma la lección «Crear y aplicar anotaciones personalizadas»?

La mayoría de las lecciones de CoddyKit toman alrededor de 5–10 minutos. Cada una es compacta e interactiva, así que avanzas constantemente y retomas exactamente por donde dejaste en la web y la app.

¿Puedo escribir y ejecutar código en esta lección de Kotlin Academy?

Sí. Cada lección de Kotlin Academy incluye un editor de código integrado, así que escribes y ejecutas código real directamente en tu navegador y obtienes retroalimentación instantánea de IA — sin configuración local necesaria.

Todas las lecciones de este curso

  1. Reflexión de Kotlin: KClass, KFunction y KProperty
  2. Crear y aplicar anotaciones personalizadas
  3. Leer anotaciones en tiempo de ejecución
  4. Validación y mapeo basados en reflexión
← Volver a Kotlin Academy