Kotlin Academy · Урок

Использование аннотаций

Аннотируйте код

«Использование аннотаций» — бесплатный урок Kotlin Academy на CoddyKit. Это урок 1 из 4. Ты можешь прочитать весь урок бесплатно ниже — а потом практиковать его прямо в браузере с встроенным редактором кода и ИИ-репетитором 24/7. Это часть пути обучения Kotlin Academy, и твой прогресс синхронизируется между веб-версией и приложением CoddyKit. Курс Kotlin Academy содержит 4 уроков всего.

Что такое аннотации

Аннотации прикрепляют метаданные к коду. Сами по себе они не изменяют поведение, но инструменты, компиляторы и библиотеки считывают их, чтобы принимать решения.

Аннотация записывается как @, за которым следует её имя, непосредственно перед элементом, к которому она применяется.

Первая аннотация

Стандартная библиотека содержит несколько полезных аннотаций. @Deprecated помечает код, который больше не следует использовать, и показывает предупреждение в месте вызова.

@Deprecated("Use newGreet() instead")
fun greet() = "Hi"

fun newGreet() = "Hello"

fun main() {
    println(newGreet())
}

Аннотации с аргументами

Аннотации могут принимать аргументы, записываемые подобно параметрам конструктора. @Deprecated принимает сообщение и, при необходимости, подсказку ReplaceWith.

@Deprecated(
    message = "Renamed for clarity",
    replaceWith = ReplaceWith("sum(a, b)")
)
fun add(a: Int, b: Int) = a + b

fun sum(a: Int, b: Int) = a + b

fun main() {
    println(sum(2, 3))
}

Подавление предупреждений

@Suppress указывает компилятору не показывать определённые предупреждения для аннотированного элемента. Имена предупреждений передаются как строки.

@Suppress("UNUSED_VARIABLE")
fun main() {
    val unused = 42
    println("Runs without the unused-variable warning")
}

JvmStatic и связанные аннотации

Некоторые аннотации влияют на то, как Kotlin компилируется для JVM. @JvmStatic, @JvmField и @JvmName управляют байткодом, чтобы вызывающий код на Java видел более удобные API.

Для кода только на Kotlin они ничего не делают, но важны для взаимодействия с другими языками.

class Math {
    companion object {
        @JvmStatic
        fun square(x: Int) = x * x
    }
}

fun main() {
    println(Math.square(5))
}

Точки применения аннотаций

Из свойства может быть создано несколько элементов JVM: поле, геттер, сеттер и параметры конструктора. Точки применения указывают, где должна находиться аннотация.

Синтаксис: @get:, @set:, @field:, @param:.

class User(@get:JvmName("fetchName") val name: String)

fun main() {
    val u = User("Ada")
    println(u.name)
}

Аннотация @Throws для взаимодействия с Java

В Kotlin нет проверяемых исключений, поэтому вызывающий код на Java никогда не видит предложения throws, если Вы не добавите @Throws. Эта аннотация записывает тип исключения в сигнатуру байткода.

import java.io.IOException

@Throws(IOException::class)
fun readData(): String {
    return "data"
}

fun main() {
    println(readData())
}

Несколько аннотаций

Вы можете поместить несколько аннотаций на один элемент. Каждая аннотация указывается на отдельной строке или отделяется пробелами. Порядок не имеет значения.

@Deprecated("old")
@Suppress("DEPRECATION")
fun legacy() = "still here"

fun main() {
    println(legacy())
}

Аннотации для выражений

Аннотации можно применять не только к функциям или классам верхнего уровня, но и к выражениям и локальным объявлениям. Это часто используется с @Suppress внутри тела функции.

fun main() {
    @Suppress("UNUSED_VARIABLE")
    val temp = computeOnce()
    println("Done")
}

fun computeOnce() = 99

OptIn и экспериментальные API

Библиотеки помечают нестабильные API собственными аннотациями, требующими явного согласия. Чтобы использовать такие API, подтвердите принятие риска с помощью @OptIn(SomeApi::class) или передайте эту аннотацию дальше.

Так экспериментальные возможности остаются явными, а не используются случайно.

fun main() {
    // @OptIn would appear here when calling an experimental function
    println("Opt-in keeps unstable APIs visible")
}

Зачем нужны аннотации

Аннотации позволяют сообщать о намерениях инструментам: компиляторы предупреждают об обращениях к устаревшим элементам, библиотеки сериализации сопоставляют поля, тестовые платформы находят методы для тестирования, а платформы внедрения зависимостей связывают зависимости.

Метаданные, а не логика
Читаются во время компиляции или выполнения
Хранят настройки рядом с кодом

Быстрая проверка

Проверьте, насколько хорошо Вы поняли использование аннотаций.

Итоги

Вы научились использовать встроенные аннотации:

@Deprecated, @Suppress, @Throws
Взаимодействие с JVM: @JvmStatic, @JvmName
Точки применения, например @get: и @field:
Явное согласие на использование экспериментальных API

Далее Вы создадите собственные аннотации.

Часто задаваемые вопросы

Урок «Использование аннотаций» бесплатный?

Да — полный текст урока «Использование аннотаций» бесплатно доступен здесь в веб-версии. Чтобы практиковать его интерактивно (встроенный редактор кода и ИИ-репетитор 24/7) и разблокировать остальной курс Kotlin Academy, подпишись на CoddyKit PRO. Курс Kotlin Academy содержит 4 уроков всего.

Чему я научусь в уроке «Использование аннотаций»?

Аннотируйте код Ты практикуешь Kotlin Academy с помощью реального кода, который запускаешь прямо в браузере, и ИИ-репетитор 24/7 отвечает на твои вопросы во время урока.

Нужен ли мне опыт, чтобы начать Kotlin Academy?

Предыдущий опыт не требуется. Kotlin Academy на CoddyKit структурирован для всех уровней — от новичков до продвинутых, поэтому ты можешь начать отсюда или с самого начала и учиться в своем темпе. Это урок 1 из 4.

Сколько времени занимает урок «Использование аннотаций»?

Большинство уроков CoddyKit занимают около 5–10 минут. Каждый из них компактный и интерактивный, поэтому ты постоянно делаешь прогресс и продолжаешь с того же места в веб-версии и приложении.

Можно ли писать и запускать код в этом уроке Kotlin Academy?

Да. Каждый урок Kotlin Academy включает встроенный редактор кода, поэтому ты пишешь и запускаешь реальный код прямо в браузере и получаешь моментальную обратную связь от AI — локальная установка не требуется.

Все уроки этого курса

← Назад к Kotlin Academy