Comment utiliser les annotations en Kotlin?

Les annotations en Kotlin sont utilisées pour ajouter des métadonnées aux classes, propriétés, fonctions, expressions et paramètres. Elles ne réalisent pas d'action directe, mais peuvent être utilisées par le compilateur, des frameworks ou d'autres bibliothèques pour divers traitements.

Principaux aspects d'utilisation :

1. Syntaxe : Les annotations sont placées avant l'élément auquel elles s'appliquent, précédées de @. Si l'annotation a des paramètres, ils sont spécifiés entre parenthèses après le nom.

   @Deprecated("Utilisez newFunction à la place")
   fun oldFunction() {
       // ...
   }
   
   @JvmStatic
   fun staticMethod() {
       // ...
   }
   

2. Application à différents éléments : Les annotations peuvent s'appliquer à :

   • Classes (class) :

     @Serializable
     class User(val name: String)
     

   • Propriétés (val, var) :

     @Inject
     lateinit var userRepository: UserRepository
     

   • Fonctions (fun) :

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

   • Paramètres de constructeurs/fonctions :

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

   • Expressions :

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

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

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

3. Lieux d'application (Cibles d'utilisation) : Pour désambiguïser à quel élément précis l'annotation s'applique, lorsqu'il y en a plusieurs (par exemple, champ et getter), on utilise use-site targets.

   Cible	Description
   @file:	S'applique à tout le fichier
   @property:	S'applique à la propriété dans son ensemble
   @field:	S'applique au champ de backing (backing field)
   @get:	S'applique au getter de la propriété
   @set:	S'applique au setter de la propriété
   @param:	S'applique au paramètre du constructeur
   @setparam:	S'applique au paramètre du setter de la propriété
   @delegate:	S'applique à l'instance de la propriété déléguée
   @receiver:	S'applique au type du récepteur

   class Example(@field:Inject val dependency: Dependency) {
       // @field:Inject s'applique au champ 'dependency'
   }
   

4. Déclaration d'annotations personnalisées : Les annotations propres sont déclarées avec le mot-clé annotation class. Les paramètres de l'annotation peuvent être de types primitifs, chaînes, classes (KClass), énumérations, autres annotations ou tableaux de ces types.

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

5. Meta-annotations : Les annotations peuvent être marquées avec des meta-annotations qui définissent leur comportement et leur applicabilité.

   • @Target : Indique quels éléments peuvent être annotés.
   • @Retention : Indique à quelle étape de la vie l'annotation est présente (SOURCE, BINARY, RUNTIME).
   • @Repeatable : Permet d'appliquer plusieurs fois la même annotation.
   • @MustBeDocumented : Indique que l'annotation doit faire partie de l'API publique générée par l'outil de documentation.

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

Les annotations sont largement utilisées en Kotlin pour l'intégration avec des frameworks JVM (Spring, Android), la sérialisation (Kotlinx.serialization), les tests (JUnit) et la création de bibliothèques propres basées sur la métainformation.