0Pricing
Kotlin Academy · Lekcja

Tworzenie własnych adnotacji i określanie ich celów

Definiuj adnotacje z zasadami przechowywania i stosuj je do klas, funkcji oraz właściwości.

Tworzenie własnych adnotacji i określanie ich celów to bezpłatna lekcja Kotlin Academy na CoddyKit. To lekcja 2 z 4. Możesz przeczytać całą lekcję poniżej za darmo — a potem ćwiczyć ją interaktywnie w przeglądarce z wbudowanym edytorem kodu i tutorem AI dostępnym 24/7. To część ścieżki edukacyjnej Kotlin Academy, a Twój postęp synchronizuje się między webem a aplikacją CoddyKit. Kurs Kotlin Academy zawiera 4 lekcji w sumie.

Po co tworzyć własne adnotacje?

Adnotacje to metadane dołączone do deklaracji (klas, funkcji, właściwości i parametrów). Własne adnotacje pozwalają oznaczać kod do przetwarzania przez frameworki, narzędzia budowania (KSP/KAPT) lub własną logikę wykonywaną w czasie działania.

Deklarowanie adnotacji

Należy użyć słów kluczowych annotation class. Klasy adnotacji mogą mieć parametry konstruktora (wyłącznie typy prymitywne, String, KClass, wyliczenia, inne adnotacje lub tablice tych typów):

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

Metaadnotacje: @Target

@Target ogranicza miejsca, w których można użyć adnotacji. Typowe cele to: 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: kiedy adnotacja jest dostępna?

@Retention określa czas życia adnotacji:

  • SOURCE — usuwana po kompilacji
  • BINARY — zapisywana w pliku .class, ale niewidoczna za pośrednictwem refleksji
  • RUNTIME — zapisywana i widoczna w czasie działania (domyślna w większości przypadków)
@Retention(AnnotationRetention.RUNTIME)
@Target(AnnotationTarget.PROPERTY)
annotation class Validate(val minLength: Int = 1)

@Repeatable: wielokrotne stosowanie tej samej adnotacji

Domyślnie adnotację można zastosować tylko raz do jednej deklaracji. Należy oznaczyć ją adnotacją @Repeatable, aby umożliwić wielokrotne zastosowanie:

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

Adnotowanie konstruktorów i parametrów

Można adnotować parametry konstruktora oraz właściwości głównego konstruktora. Należy użyć celów zastosowania @field:, @get: lub @param:, aby określić, który element otrzyma adnotację:

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

Cele zastosowania

Kotlin generuje wiele elementów kodu bajtowego na podstawie jednej właściwości (pole, getter, setter, parametr). Cele zastosowania określają, który z nich otrzyma adnotację:

  • @field: pole zapasowe
  • @get: getter
  • @set: setter
  • @param: parametr konstruktora

Adnotowanie klas

Adnotacje na klasie są przydatne do oznaczania jej na potrzeby przetwarzania przez framework (np. jako serializowalnej, możliwej do wstrzykiwania lub należącej do określonego modułu):

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

@Repository
class UserRepository

@MustBeDocumented

Dodanie adnotacji @MustBeDocumented zapewnia umieszczenie adnotacji w wygenerowanej dokumentacji API. Należy jej używać w przypadku adnotacji stanowiących część kontraktu publicznego API.

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

Parametry adnotacji: wartości domyślne i tablice

Parametry mogą mieć wartości domyślne i mogą przyjmować tablice za pomocą słowa kluczowego vararg lub jawnych typów tablicowych:

annotation class Roles(vararg val value: String)

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

Parametry KClass w adnotacjach

Adnotacje mogą odwoływać się do typów klas za pomocą KClass:

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

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

Szybkie sprawdzenie

Jaka wartość @Retention sprawia, że własna adnotacja jest dostępna za pośrednictwem refleksji Kotlina w czasie działania?

Podsumowanie: własne adnotacje

Najważniejsze wnioski:

  • Należy deklarować je za pomocą annotation class; parametry mogą mieć wyłącznie typy prymitywne, String, KClass, wyliczenia i tablice
  • @Target — określa, gdzie można zastosować adnotację
  • @Retention — określa, kiedy adnotacja jest dostępna (w przypadku refleksji należy użyć RUNTIME)
  • @Repeatable — umożliwia wielokrotne zastosowanie do jednej deklaracji
  • Cele zastosowania (@field:, @get: itd.) określają, który element kodu bajtowego otrzyma adnotację

Często zadawane pytania

Czy lekcja „Tworzenie własnych adnotacji i określanie ich celów” jest bezpłatna?

Tak — pełny tekst „Tworzenie własnych adnotacji i określanie ich celów” jest dostępny za darmo tutaj w sieci. Aby ćwiczyć ją interaktywnie (wbudowany edytor kodu i tutor AI dostępny 24/7) i odblokować resztę kursu Kotlin Academy, przejdź na CoddyKit PRO. Kurs Kotlin Academy zawiera 4 lekcji w sumie.

Co nauczysz się w „Tworzenie własnych adnotacji i określanie ich celów”?

Definiuj adnotacje z zasadami przechowywania i stosuj je do klas, funkcji oraz właściwości. Ćwiczysz Kotlin Academy z praktycznym kodem, który uruchamiasz bezpośrednio w przeglądarce, a tutor AI dostępny 24/7 odpowiada na Twoje pytania podczas pracy nad lekcją.

Czy potrzebuję doświadczenia, aby zacząć Kotlin Academy?

Nie wymagamy żadnego doświadczenia. Kotlin Academy w CoddyKit jest strukturyzowany dla początkujących i zaawansowanych użytkowników, więc możesz zacząć tutaj lub od początku i uczyć się w swoim tempie. To lekcja 2 z 4.

Ile czasu zajmuje lekcja „Tworzenie własnych adnotacji i określanie ich celów”?

Większość lekcji CoddyKit trwa około 5–10 minut. Każda lekcja to mały, interaktywny krok, dzięki czemu robisz systematyczne postępy i zawsze wracasz dokładnie do tego samego miejsca — na webie i w aplikacji.

Czy mogę pisać i uruchamiać kod w tej lekcji Kotlin Academy?

Tak. Każda lekcja Kotlin Academy zawiera wbudowany edytor kodu, więc piszesz i uruchamiasz prawdziwy kod bezpośrednio w przeglądarce i od razu otrzymujesz sprzężenie zwrotne od AI — bez konfiguracji na komputerze.

Wszystkie lekcje w tym kursie

  1. Refleksja w Kotlinie: KClass, KFunction, KProperty
  2. Tworzenie własnych adnotacji i określanie ich celów
  3. Odczytywanie adnotacji w czasie działania
  4. Walidacja i mapowanie oparte na refleksji
← Powrót do Kotlin Academy