KSP вместо runtime‑рефлексии: аннотация → генерация → код

1. Введение

Если вы только-только привыкли к мысли «ничего себе, я могу найти метод по имени и вызвать его», то вполне естественно захотеть применить это везде: автокоманды в CLI, автогенерация справки, «подцепить плагины», «обойтись без ручного реестра функций»… и так далее.

Проблема в том, что runtime‑рефлексия — это как искать нужный предмет в комнате с выключенным светом: в целом возможно, но вы будете часто биться мизинцем о табуретку. Даже если вы всё написали аккуратно, рефлексия почти всегда означает дополнительную работу в рантайме: поиск, проверки, упаковки аргументов, обработка ошибок, сложность отладки. Плюс, вы неизбежно начинаете завязываться на строки, а строки, как известно, не умеют «подсвечиваться красным» в IDE, когда вы в них ошиблись.

И тут появляется хороший инженерный вопрос: «А можно сделать так, чтобы компьютер сделал скучную работу за нас, но ещё до запуска программы?»

KSP: что это такое простыми словами

KSP (Kotlin Symbol Processing) — это механизм, который позволяет на этапе компиляции пройтись по вашему Kotlin-коду, найти нужные элементы (классы, функции, свойства), обычно помеченные аннотациями, и сгенерировать новый Kotlin-код (.kt файлы). После генерации компилятор просто компилирует эти файлы вместе с вашим проектом, как будто вы написали их руками.

Здесь важна мысль: KSP не «ускоряет компиляцию ради компиляции» и не «подменяет Kotlin». Он добавляет этап: обнаружили нужные элементы → сгенерировали исходники → дальше всё обычная компиляция.

Если рефлексия похожа на ситуацию «мы запускаем программу, и уже в процессе спрашиваем: “Эй, объект, какие у тебя есть методы?”», то KSP — это «мы ещё до запуска составили справочник, какие методы есть, и в рантайме просто читаем справочник».

2. Главный поток: «аннотация → генерация → обычный код»

Сейчас будет важная «картина мира». Постарайтесь воспринимать её как схему конвейера: сырьё на вход, готовая деталь на выход.

Схема конвейера

Пусть у нас есть исходники проекта, и мы хотим, чтобы часть кода «самоподключалась». Тогда общий пайплайн выглядит примерно так:

flowchart TD
    A["Ваши исходники (.kt)"] --> B["KSP: анализ символов (классы/функции/аннотации)"]
    B --> C["Сгенерированные .kt файлы (build/generated/...)"]
    C --> D["Обычная компиляция Kotlin"]
    D --> E["Байткод / JAR"]
    E --> F["Запуск: обычный Kotlin-код без рефлексии"]

Ключевой смысл: KSP делает работу там, где компилятору «видно всё», а рантайму «уже ничего искать не надо».

Аннотация — это просто метка

Очень частая путаница у новичков: «Я поставил аннотацию — почему ничего не произошло?»

Потому что аннотация сама по себе — это просто метка. Она начинает «что-то значить» только если есть инструмент, который эту метку читает и действует (в нашем случае — KSP‑процессор/генератор).

Простейшая аннотация-маркер может выглядеть так:

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

Сама по себе она не добавит команду в ваше приложение. Но она даст генератору понятный сигнал: «Вот это — команда, обработай её».

4. Практический пример: CLI «вручную», «через рефлексию» и «через KSP»

Чтобы KSP не остался абстрактным словом из мира сборки, привяжем его к нашему учебному консольному приложению. Допустим, мы продолжаем развивать CLI‑приложение (условно назовём его BudgetCli), где есть команды вроде "add", "list", "help".

Реестр команд вручную

Классический «простой» способ — завести Map<String, (List<String>) -> Unit> и вручную регистрировать команды. Это работает, но выглядит как бухгалтерия: полезно, но счастья не приносит.

typealias CommandHandler = (List<String>) -> Unit

val commands: Map<String, CommandHandler> = mapOf(
    "help" to ::cmdHelp,
    "list" to ::cmdList
)

Проблема здесь не в строках как таковых, а в том, что вы обязаны помнить про регистрацию. Добавили cmdAdd() — не добавили в Map — команда «как бы есть», но «как бы нет».

Runtime‑рефлексия как авто‑сканер

После лекции про рефлексию появляется соблазн: «А давайте найдём все функции с аннотацией @CliCommand в рантайме!»

Идея звучит красиво, но у неё есть цена: в рантайме нужно искать, фильтровать, обрабатывать ошибки. И если вы выбираете по строке имя метода или аннотации, вы снова живёте в мире строк.

Мы здесь не углубляемся в реализацию такого сканера (это было в прошлом занятии), но важно зафиксировать: runtime‑рефлексия — это «автосборка команд на месте», прямо при запуске.

KSP‑подход: команды «собираются» до запуска

Теперь делаем то же самое, но в стиле KSP: мы хотим пометить функции команд аннотацией, а дальше получить сгенерированный реестр.

Шаг 1. Пишем аннотацию

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

Шаг 2. Помечаем функции команд

Представим, что у нас есть файл Commands.kt:

@CliCommand("help")
fun cmdHelp(args: List<String>) {
    println("Команды: help, list") // Команды: help, list
}

@CliCommand("list")
fun cmdList(args: List<String>) {
    println("Пока список пуст") // Пока список пуст
}

Шаг 3. Что «условно» генерирует KSP

Важный момент: мы не пишем KSP‑процессор в этом курсе. Но мы можем понимать, какой код должен получиться «на выходе».

Например, генератор может создать файл GeneratedCliRegistry.kt:

typealias CommandHandler = (List<String>) -> Unit

object GeneratedCliRegistry {
    val commands: Map<String, CommandHandler> = mapOf(
        "help" to ::cmdHelp,
        "list" to ::cmdList
    )
}

Обратите внимание на приятную вещь: ::cmdHelp — это обычная callable reference, которую компилятор проверит. Если вы переименуете cmdHelp, а генерация (или генератор) не соответствует новым именам, вы получите ошибку компиляции, а не «команда не найдена» в рантайме. Это фундаментальное отличие.

Шаг 4. Используем реестр в main

fun runCommand(line: String) {
    val parts = line.trim().split(" ").filter { it.isNotBlank() }
    val name = parts.firstOrNull() ?: return
    val args = parts.drop(1)

    val handler = GeneratedCliRegistry.commands[name]
    handler?.invoke(args) ?: println("Неизвестная команда: $name")
}

И вот тут наступает «момент истины»: в рантайме мы больше не ищем функции через рефлексию. Мы просто достали обработчик из Map и вызвали его. Быстро, предсказуемо, типобезопасно (насколько это возможно для Map<String, ...>).

5. Почему сгенерированный код — сильная идея

С KSP легко «влюбиться», потому что он обещает автоматизацию без рантайм‑магии. Но лучше сразу держать в голове честный баланс.

Плюсы: скорость и предсказуемость

Когда KSP генерирует Kotlin‑код, дальше работает обычный компилятор: он проверяет типы, видимость, сигнатуры, существование функций. То, что в runtime‑рефлексии могло бы «упасть на пользователе», здесь падает на этапе сборки — а это почти всегда дешевле и безопаснее.

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

Минусы: сборка становится сложнее

KSP — это инструмент, который живёт рядом с компилятором. Поэтому он чувствителен к версиям Kotlin, Gradle‑плагинов и окружения.

Это не значит «KSP плохой». Это значит «KSP — часть сборочной экосистемы», а сборка — тоже часть продукта: её нужно поддерживать, обновлять аккуратно и проверять.

6. Как выбирать подход и проектировать генерацию

Очень хочется иметь «универсальный молоток». Но в инженерии универсальный молоток быстро превращается в универсальную проблему.

Таблица выбора

Смысл таблицы не в том, чтобы «запретить» что-то. Смысл в том, чтобы понимать: KSP — отличный инструмент, когда вы реально выигрываете от генерации. А если вы пишете один файл на 200 строк — генератор может оказаться сложнее, чем задача.

Почему генерация часто делает extension‑функции

Есть популярный стиль кодогенерации: KSP генерирует extension‑функции, чтобы ваш код выглядел «нативно», как будто это часть API.

Например, вместо GeneratedCliRegistry.formatHelp() можно сгенерировать:

fun String.toCommandName(): String = trim().lowercase()

Или для модели:

data class Expense(val title: String, val amount: Int)

fun Expense.toLogLine(): String = "Expense(title=$title, amount=$amount)"

Почему это удобно? Потому что extension‑функции в Kotlin разрешаются статически, на этапе компиляции: компилятор выбирает, какую extension‑функцию вызвать, исходя из объявленного типа, а не «в рантайме по чуду». Это один из факторов, почему сгенерированный код обычно быстрый и предсказуемый.

Ещё один плюс extension‑стиля: он помогает не городить гигантские GeneratedUtil123 классы. Вы получаете маленькие функции рядом с теми типами, для которых они предназначены, и IDE делает вам автодополнение как обычно.

Как «думать KSP‑ом»: контракт важнее догадок

Когда люди впервые проектируют генерацию, они часто хотят «сделать умно»: чтобы генератор сам догадался, сам исправил, сам придумал имя, сам обработал все случаи жизни. Обычно это заканчивается тем, что генератор начинает быть похож на второго компилятора… только хуже (потому что ваш).

Здоровый подход к KSP — относиться к нему как к строгому конвейеру: на вход подаём понятные правила (контракт), на выходе получаем очень предсказуемый код.

Например, для наших CLI‑команд можно заранее договориться о контракте:

Текст команды задаётся в @CliCommand("name"), функция обязана иметь сигнатуру (List<String>) -> Unit, а все команды собираются в GeneratedCliRegistry.commands. Всё.

Никаких «а если функция без аргументов, то я её тоже возьму», никаких «а если два одинаковых имени, то я выберу последнюю». Такие «добрые догадки» обычно превращаются в неотлаживаемую лотерею.

7. Типичные ошибки при использовании идеи KSP

Ошибка №1: ожидание, что аннотация «сама сработает».
Очень легко поставить @CliCommand над функцией и ждать, что команда появится. Но аннотация — это просто метка в коде. Пока в проект не добавлен обработчик (генератор), ничего не происходит, и это нормально. В голове нужно держать модель: «аннотация — входные данные для инструмента».

Ошибка №2: попытка сделать генератор заменой архитектуры.
Иногда люди начинают генерировать всё подряд: бизнес‑логику, алгоритмы, половину приложения. Это быстро приводит к тому, что проект превращается в «сборку вокруг генерации», а не «генерацию вокруг проекта». Хороший генератор обычно автоматизирует скучные связки: регистрация, простые адаптеры, однотипный код. Если генератор пишет за вас смысловые решения — это тревожный сигнал.

Ошибка №3: слишком «умные» правила и неявные приоритеты.
Как только в генерации появляются правила вида «если есть два варианта — выбери самый подходящий», вам придётся объяснять, что значит «подходящий», и почему сегодня выбрался один, а завтра другой. На практике лучше, когда генератор либо делает ровно то, что вы сказали, либо падает с понятной ошибкой и просит поправить входные данные.

Ошибка №4: отсутствие fail‑fast поведения при конфликте.
Если две функции помечены @CliCommand("list"), генератор должен не «как-нибудь разрулить», а остановить сборку и объяснить конфликт. Иначе вы получите ситуацию: приложение запускается, команда работает «не та», а вы полдня думаете, что у вас баг в логике, хотя на самом деле баг в регистрации.

Ошибка №5: зависимость от версий и игнорирование того, что сборка — часть продукта.
KSP живёт рядом с компилятором и Gradle‑инфраструктурой, поэтому он чувствителен к обновлениям. Это не страшилка, а реальность инструментов такого уровня: если проект использует генерацию, «обновить Kotlin наобум» — это уже не мелочь, а событие, которое требует внимательности.

Ошибка №6: генерация API, которым невозможно пользоваться без чтения исходников генератора.
Сгенерированный код — это тоже API. Если вы генерируете странные имена, неожиданные классы и запутанные сигнатуры, то пользоваться этим будет трудно даже вам через месяц. Хороший стиль: генерировать минимальный, читаемый Kotlin, который не стыдно показать человеку.

Ошибка №7: вера в то, что «генерированный код нельзя трогать».
Его действительно нельзя править руками (потому что перегенерируется), но его нужно уметь читать. Когда что-то сломалось, самый практичный навык — открыть сгенерированные .kt файлы и посмотреть: «А что именно получилось?» Это часто быстрее любых предположений и гаданий.