Какие риски совместимости возникают при обновлении Kotlin, Gradle и Kotlin/Native в KMP-проекте?

Почему обновления KMP опаснее, чем JVM-проекты

KMP-проект компилируется в несколько таргетов (JVM, Android, iOS/Native), и каждый таргет имеет свои зависимости. Kotlin/Native имеет собственный runtime и ABI, который не обязан быть обратно совместимым даже между minor-версиями Kotlin.

Основные источники рисков

1. Kotlin/Native ABI-несовместимость

Скомпилированный .klib с Kotlin 1.9.x может не загружаться в проект, собранный с Kotlin 2.0. Все KMP-зависимости нужно обновлять синхронно.

// libs.versions.toml — Version Catalog:
[versions]
kotlin = "2.0.21"
ksp = "2.0.21-1.0.27"  // KSP ДОЛЖЕН соответствовать версии Kotlin
ktor = "2.3.12"
sqldelight = "2.0.2"

[plugins]
kotlin-multiplatform = { id = "org.jetbrains.kotlin.multiplatform", version.ref = "kotlin" }
kotlin-serialization = { id = "org.jetbrains.kotlin.plugin.serialization", version.ref = "kotlin" }
ksp = { id = "com.google.devtools.ksp", version.ref = "ksp" }

2. Изменения Kotlin Memory Model

Kotlin 1.7.20 включил новую модель памяти Kotlin/Native по умолчанию. Старый код с @SharedImmutable, freeze(), DetachedObjectGraph — устарел и может не компилироваться в Kotlin 2.x.

// Старый код (до 1.7.20) — УБРАТЬ:
@SharedImmutable
val globalConfig = Config()  // freeze() вызывался неявно

// Новый код:
val globalConfig = Config()  // объект просто mutable, no freeze

3. Gradle Plugin API и AGP

Kotlin Multiplatform Plugin совместим только с определёнными версиями Android Gradle Plugin (AGP). Несоответствие приводит к ошибке: The Kotlin Gradle plugin was loaded multiple times.

// Совместимость версий (build.gradle.kts):
plugins {
    id("com.android.application") version "8.5.2"  // AGP
    kotlin("multiplatform") version "2.0.21"       // KMP
    // Обновляйте оба вместе, смотрите таблицу совместимости
}

4. Изменения в kotlinx.coroutines и Serialization

// kotlinx.coroutines >= 1.7.0: runBlocking запрещён в Main-потоке на iOS
// Старый код:
fun loadData(): List<Item> = runBlocking { fetchItems() }  // crash на iOS!

// Новый код:
suspend fun loadData(): List<Item> = fetchItems()
// Или в ViewModel:
viewModelScope.launch { _items.value = loadData() }

Безопасная процедура обновления

// 1. Обновить только Kotlin, зафиксировать тесты:
./gradlew clean allTests

// 2. Обновить зависимые плагины (KSP, Serialization):
./gradlew dependencies | grep -i "kotlin"

// 3. Обновить библиотеки (Ktor, SQLDelight, Coroutines):
./gradlew dependencyUpdates  // plugin: com.github.ben-manes.versions

// 4. Пересобрать iOS-фреймворк:
./gradlew assembleSharedReleaseXCFramework

// 5. Открыть Xcode, пересобрать iOS-приложение

Мониторинг совместимости

// Проверка конфликтов зависимостей:
./gradlew :shared:dependencies --configuration commonMainImplementation

// Поиск дублирующихся классов в Native klibs:
./gradlew :shared:linkDebugFrameworkIosArm64 --stacktrace

Подводные камни

• Обновление только Kotlin без обновления KSP вызывает KSP can only be used with the same version of Kotlin — всегда синхронно;
• AGP 8.x изменил API конфигурации Android-таргета: android { } блок внутри kotlin { } требует androidTarget(), а не android();
• После обновления Kotlin/Native все .klib-кэши в ~/.konan/ устаревают — первая сборка занимает 10–30 минут;
• Kotlin 2.0 изменил поведение expect/actual: неполные actual теперь ошибка компилятора, а не предупреждение;
• SQLDelight 2.x несовместим с 1.x — миграция требует переписывания всех .sq-файлов и API вызовов;
• Gradle Configuration Cache (включён по умолчанию в 8.x) конфликтует со старыми версиями KMP-плагина — обновляйте до 1.9.20+;
• Ktor 3.x убрал экспериментальный флаг для ряда API — код, собранный без @OptIn, перестанет компилироваться;
• Kotlinx.serialization не гарантирует совместимость формата между версиями для Protobuf — возможна поломка сохранённых данных.

• Отвечать определением без production-сценария.
• Не называть runtime boundary, security boundary или failure mode.
• Игнорировать версию API, observability и тестовую проверку.

• Объясняет механизм своими словами и без выдуманных API.
• Называет реальные риски, диагностику и критерий корректности.
• Связывает ответ с текущей документацией и миграционными ограничениями.