როგორ გამოვიყენოთ ანოტაციები Kotlin-ში?

კოტლინში ანოტაციები გამოიყენება მეტა-მინიშნების დასამატებლად კლასებს, თვისებებს, ფუნქციებს, გამოხმაურებებს და პარამეტრებს. ისინი პირდაპირი მოქმედებით არ მუშაობენ, მაგრამ შეიძლება გამოყენებულ იქნას კომპილატორით, ფრეიმვორკებით ან სხვა ბიბლიოთეკებით სხვადასხვა დამუშავებისთვის:

მთავარი გამოყენების ასპექტები:

1. სინტაქსი: ანოტაციები მიუთითება იმ ელემენტის წინ, რომელსაც ისინი ეხება, კუთხის ბრეკეტებში @. თუ ანოტაცია აქვს პარამეტრები, ისინი მიუთითება სახელის შემდეგ ბრეკეტებში:

   @Deprecated("Use newFunction instead")
   fun oldFunction() {
       // ...
   }
   
   @JvmStatic
   fun staticMethod() {
       // ...
   }
   

2. მოქმედება სხვადასხვა ელემენტებზე: ანოტაციები შეიძლება გამოყენებულ იქნას:

   • კლასებზე (class):

     @Serializable
     class User(val name: String)
     

   • თვისებებზე (val, var):

     @Inject
     lateinit var userRepository: UserRepository
     

   • ფუნქციებზე (fun):

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

   • კონსტრუქტორის/ფუნქციის პარამეტრებზე:

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

   • გამოხმაურებებზე:

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

   • ტიპებზე (@Target(AnnotationTarget.TYPE)):

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

3. გამოყენების ადგილები (Use-site Targets): რამდენიმე შემთხვევაში, რათა განვსაზღვროთ, რომელ ელემენტზე გამოიყენება ანოტაცია, როდესაც ისინი მრავლად არიან (მაგ., ველი და getter), გამოიყენება use-site targets:

   Target	აღწერა
   @file:	გამოიყენება მთელ ფაილზე
   @property:	გამოიყენება მთლიანად თვისებაზე
   @field:	გამოიყენება backing field-ზე
   @get:	გამოიყენება თვისების getter-ზე
   @set:	გამოიყენება თვისების setter-ზე
   @param:	გამოიყენება კონსტრუქტორის/ფუნქციის პარამეტრზე
   @setparam:	გამოიყენება თვისების setter-ის პარამეტრზე
   @delegate:	გამოიყენება დელეგირებადი თვისების ინსტანსზე
   @receiver:	გამოიყენება მიმღების ტიპზე

   class Example(@field:Inject val dependency: Dependency) {
       // @field:Inject გამოიყენება 'dependency' ველზე
   }
   

4. მომხმარებლის განსაზღვრული ანოტაციები: საკუთარი ანოტაციები გამოაცხადება annotation class-ით. ანოტაციის პარამეტრები შეიძლება იყოს პრიმიტიული ტიპები, სტრინგები, კლასები (KClass), სიები, სხვა ანოტაციები ან მათი მასივები:

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

5. მეტა-ანოტაციები: ანოტაციები შეიძლება იყოს მითითებული მეტა-ანოტაციებით, რომლებიც განსაზღვრავენ მათ ქცევასა და გამოყენებადობას:

   • @Target: მიუთითებს, რომელი ელემენტები შეიძლება იყოს ანოტირებული.
   • @Retention: მიუთითებს, რომელი ეტაპზე არსებობს ანოტაცია (SOURCE, BINARY, RUNTIME).
   • @Repeatable: საშუალებას აძლევს გამოიყენოს ანოტაცია რამდენჯერმე ერთ ელემენტზე.
   • @MustBeDocumented: მიუთითებს, რომ ანოტაცია უნდა იყოს საჯარო API-ის ნაწილი, რომელიც დოკუმენტაციის ინსტრუმენტით გენერირებულია.

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

ანოტაციები ფართოდ გამოიყენება კოტლინში JVM ფრეიმვორკების (Spring, Android), სერილიზაციის (Kotlinx.serialization), ტესტირების (JUnit) და საკუთარი ბიბლიოთეკების შექმნისთვის, რომლებიც დაფუძნებულია მეტა-მინიშნებაზე.