Spec-Zone.ru › Kotlin 2

Руководство по совместимости для Kotlin 2.2.x

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

Хотя большинство изменений языка уже были объявлены в других источниках, например в журналах изменений обновлений или предупреждениях компилятора, в этом документе собраны все изменения и приведена полная справочная информация для перехода с Kotlin 2.1 на Kotlin 2.2.

Основные понятия

В этом документе рассматриваются несколько видов совместимости:

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

  • бинарная: два бинарных артефакта считаются бинарно-совместимыми, если их взаимная замена не приводит к ошибкам загрузки или связывания

  • поведенческая: изменение считается нарушающим поведенческую совместимость, если одна и та же программа ведёт себя по-разному до и после его применения

Помните, что эти определения относятся только к чистому Kotlin. Совместимость кода Kotlin с точки зрения других языков (например, Java) выходит за рамки этого документа.

Язык

Отказ от поддержки -language-version для версий 1.6 и 1.7

Проблема: KT-71793

Компонент: Компилятор

Тип несовместимого изменения: исходная

Краткое описание: Начиная с Kotlin 2.2, компилятор больше не поддерживает -language-version=1.6 или -language-version=1.7. Это означает, что наборы языковых возможностей старше версии 1.8 больше не поддерживаются. Однако сам язык остаётся полностью обратно совместимым с Kotlin 1.0.

Цикл устаревания:

  • 2.1.0: выдаётся предупреждение при использовании -language-version с версиями 1.6 и 1.7

  • 2.2.0: выдаётся предупреждение при использовании -language-version с версиями 1.8 и 1.9; предупреждение для версий 1.6 и 1.7 становится ошибкой

Включение invokedynamic по умолчанию для лямбд с аннотациями

Проблема: KTLC-278

Компонент: Основной язык

Тип несовместимого изменения: поведенческая

Краткое описание: Теперь лямбды с аннотациями по умолчанию используют invokedynamic через LambdaMetafactory, что согласует их поведение с лямбдами Java. Это затрагивает код, использующий рефлексию и рассчитывающий на получение аннотаций из сгенерированных классов лямбд. Чтобы вернуться к прежнему поведению, используйте параметр компилятора -Xindy-allow-annotated-lambdas=false.

Цикл устаревания:

  • 2.2.0: для лямбд с аннотациями по умолчанию включён invokedynamic

Запрет вызова конструктора и наследования с псевдонимами типов, разворачивающимися в типы с вариативностью, в K2

Проблема: KTLC-4

Компонент: Основной язык

Тип несовместимого изменения: исходная

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

Цикл устаревания:

  • 2.0.0: выдаётся предупреждение при вызовах конструкторов или использовании в качестве супертипа псевдонимов типов, разворачивающихся в типы с модификаторами вариативности

  • 2.2.0: предупреждение становится ошибкой

Запрет синтетических свойств на основе геттеров Kotlin

Проблема: KTLC-272

Компонент: Основной язык

Тип несовместимого изменения: исходная

Краткое описание: Синтетические свойства больше не разрешены для геттеров, определённых в Kotlin. Это затрагивает случаи, когда классы Java наследуются от классов Kotlin, а также работу с отображаемыми типами, такими как java.util.LinkedHashSet. Для миграции замените обращение к свойству прямым вызовом соответствующей функции-геттера.

Цикл устаревания:

  • 2.0.0: выдаётся предупреждение при обращении к синтетическим свойствам, созданным на основе геттеров Kotlin

  • 2.2.0: предупреждение становится ошибкой

Изменение генерации методов по умолчанию для функций интерфейсов в JVM

Проблема: KTLC-269

Компонент: Основной язык

Тип несовместимого изменения: бинарная

Краткое описание: Теперь функции, объявленные в интерфейсах, компилируются в методы JVM по умолчанию, если не задана иная конфигурация. Это может привести к ошибкам компиляции кода Java, если в несвязанных супертипах определены конфликтующие реализации. Поведение задаётся стабильным параметром компилятора -jvm-default, который заменяет устаревший параметр -Xjvm-default. Чтобы восстановить прежнее поведение, при котором реализации по умолчанию генерируются только в классах DefaultImpls и их подклассах, используйте -jvm-default=disable.

Цикл устаревания:

  • 2.2.0: по умолчанию для параметра компилятора -jvm-default задаётся значение enable

Запрет аннотаций с целью field для свойств аннотаций

Проблема: KTLC-7

Компонент: Основной язык

Тип несовместимого изменения: исходная

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

Цикл устаревания:

  • 2.1.0: аннотация @JvmField для свойств аннотаций помечается как устаревшая с предупреждением

  • 2.1.20: выдаётся предупреждение для всех аннотаций с целью field у свойств аннотаций

  • 2.2.0: предупреждение становится ошибкой

Запрет reified-параметров типа в псевдонимах типов

Проблема: KTLC-5

Компонент: Основной язык

Тип несовместимого изменения: исходная

Краткое описание: Модификатор reified больше нельзя использовать для параметров типа в псевдонимах типов. Reified-параметры типа допустимы только во встроенных функциях, поэтому их использование в псевдонимах типов не имело эффекта. Для миграции удалите модификатор reified из объявлений typealias.

Цикл устаревания:

  • 2.1.0: выдаётся предупреждение для reified-параметров типа в псевдонимах типов

  • 2.2.0: предупреждение становится ошибкой

Корректировка проверок типов для встроенных value-классов для Number и Comparable

Проблема: KTLC-21

Компонент: Kotlin/JVM

Тип несовместимого изменения: поведенческая

Краткое описание: Встроенные value-классы больше не считаются реализациями java.lang.Number или java.lang.Comparable при проверках is и as. Ранее эти проверки возвращали неверные результаты при применении к упакованным встроенным классам. Теперь оптимизация применяется только к примитивным типам и их оболочкам.

Цикл устаревания:

  • 2.2.0: включение нового поведения

Запрет недоступных обобщённых типов из транзитивных зависимостей

Проблема: KTLC-3

Компонент: Основной язык

Тип несовместимого изменения: исходная

Краткое описание: Теперь компилятор K2 сообщает об ошибках при использовании типов из транзитивных зависимостей, недоступных компилятору. Это затрагивает такие случаи, как параметры лямбд или аргументы обобщённых типов, когда указанный тип недоступен из-за отсутствующей зависимости.

Цикл устаревания:

  • 2.0.0: сообщается об ошибках для недоступных обобщённых типов в лямбдах и в отдельных случаях использования недоступных аргументов обобщённых типов; выдаются предупреждения для недоступных необобщённых типов в лямбдах и недоступных аргументов типов в типах выражений и супертипов

  • 2.1.0: предупреждение о недоступных необобщённых типах в лямбдах становится ошибкой

  • 2.2.0: предупреждение о недоступных аргументах типов в типах выражений становится ошибкой

Проверка видимости ограничений параметров типа

Проблема: KTLC-274

Компонент: Основной язык

Тип несовместимого изменения: исходная

Краткое описание: Функции и свойства больше не могут использовать ограничение параметра типа, видимость которого более ограничена, чем видимость самого объявления. Это предотвращает косвенное раскрытие недоступных типов, которое ранее компилировалось без ошибок, но в некоторых случаях приводило к сбоям во время выполнения или ошибкам проверки IR.

Цикл устаревания:

  • 2.1.0: выдаётся предупреждение, если ограничение параметра типа невидимо в области видимости объявления

  • 2.2.0: предупреждение становится ошибкой

Сообщение об ошибках при раскрытии приватных типов в неп приватных inline-функциях

Проблема: KT-70916

Компонент: Основной язык

Тип несовместимого изменения: исходная

Краткое описание: Обращение к приватным типам, функциям или свойствам из непубличных inline-функций больше не разрешено. Для миграции не обращайтесь к приватным сущностям, сделайте функцию приватной или удалите модификатор inline. Обратите внимание: удаление inline нарушает бинарную совместимость.

Цикл устаревания:

  • 2.2.0: сообщается об ошибке при обращении к приватным типам или членам из непубличных inline-функций

Запрет нелокальных операторов return в лямбдах, используемых в качестве значения параметра по умолчанию

Проблема: KTLC-286

Компонент: Основной язык

Тип несовместимого изменения: исходная

Краткое описание: Нелокальные операторы return больше не разрешены в лямбдах, используемых в качестве значения параметра по умолчанию. Ранее такой код компилировался, но приводил к сбоям во время выполнения. Для миграции перепишите лямбду, исключив нелокальные операторы return, или перенесите логику из значения по умолчанию.

Цикл устаревания:

  • 2.2.0: сообщается об ошибке для нелокальных операторов return в лямбдах, используемых в качестве значения параметра по умолчанию

Стандартная библиотека

Устаревание kotlin.native.Throws

Проблема: KT-72137

Компонент: Kotlin/Native

Тип несовместимого изменения: исходная

Краткое описание: kotlin.native.Throws устарел; вместо него используйте общую аннотацию kotlin.Throws.

Цикл устаревания:

  • 1.9.0: выдаётся предупреждение при использовании kotlin.native.Throws

  • 2.2.0: предупреждение становится ошибкой

Устаревание AbstractDoubleTimeSource

Проблема: KT-72137

Компонент: kotlin-stdlib

Тип несовместимого изменения: исходная

Краткое описание: AbstractDoubleTimeSource устарел; вместо него используйте AbstractLongTimeSource.

Цикл устаревания:

  • 1.8.20: выдаётся предупреждение при использовании AbstractDoubleTimeSource

  • 2.2.0: предупреждение становится ошибкой

Инструменты

Исправлена функция setSource() в KotlinCompileTool для замены исходных файлов

Задача: KT-59632

Компонент: Gradle

Тип несовместимого изменения: поведенческое

Краткое описание: Функция setSource() в интерфейсе KotlinCompileTool теперь заменяет настроенные исходные файлы, а не добавляет их. Чтобы добавить исходные файлы, не заменяя существующие, используйте функцию source().

Этапы устаревания:

  • 2.2.0: включение нового поведения

Устаревание свойства KotlinCompilationOutput#resourcesDirProvider

Задача: KT-70620

Компонент: Gradle

Тип несовместимого изменения: исходный код

Краткое описание: Свойство KotlinCompilationOutput#resourcesDirProvider устарело. Вместо него используйте KotlinSourceSet.resources в скрипте сборки Gradle, чтобы добавить дополнительные каталоги ресурсов.

Этапы устаревания:

  • 2.1.0: KotlinCompilationOutput#resourcesDirProvider устаревает с предупреждением

  • 2.2.0: предупреждение повышается до ошибки

Устаревание свойства BaseKapt.annotationProcessorOptionProviders

Задача: KT-58009

Компонент: Gradle

Тип несовместимого изменения: исходный код

Краткое описание: Свойство BaseKapt.annotationProcessorOptionProviders устарело в пользу BaseKapt.annotationProcessorOptionsProviders, которое принимает ListProperty<CommandLineArgumentProvider> вместо MutableList<Any>. Это четко задает ожидаемый тип элемента и предотвращает ошибки во время выполнения, вызванные добавлением элементов неправильного типа, например вложенных списков. Если ваш код добавляет список как один элемент, замените функцию add() функцией addAll().

Этапы устаревания:

  • 2.2.0: в API обеспечивается использование нового типа

Устаревание плагина kotlin-android-extensions

Задача: KT-72341

Компонент: Gradle

Тип несовместимого изменения: исходный код

Краткое описание: Плагин kotlin-android-extensions устарел. Вместо него используйте отдельный плагин kotlin-parcelize для генератора реализации Parcelable, а для синтетических представлений — привязки представлений Android Jetpack.

Этапы устаревания:

  • 1.4.20: плагин устаревает

  • 2.1.20: добавляется ошибка конфигурации, код плагина не выполняется

  • 2.2.0: код плагина удаляется

  • 2.4.0: идентификатор плагина удаляется

Устаревание DSL kotlinOptions

Задача: KT-54110

Компонент: Gradle

Тип несовместимого изменения: исходный код

Краткое описание: Возможность настраивать параметры компилятора с помощью DSL kotlinOptions и связанного с ним интерфейса задачи KotlinCompile<KotlinOptions> устарела в пользу нового DSL compilerOptions. В рамках этого устаревания каждое свойство интерфейса kotlinOptions также помечено как устаревшее. Для перехода используйте DSL compilerOptions для настройки параметров компилятора. Инструкции по переходу см. в разделе Переход с kotlinOptions {} на compilerOptions {}.

Этапы устаревания:

  • 2.0.0: для DSL kotlinOptions выводится предупреждение

  • 2.2.0: предупреждение повышается до ошибки, все свойства в kotlinOptions объявляются устаревшими

Удаление свойства kotlin.incremental.useClasspathSnapshot

Задача: KT-62963

Компонент: Gradle

Тип несовместимого изменения: исходный код

Краткое описание: Свойство Gradle kotlin.incremental.useClasspathSnapshot удалено. Это свойство управляло устаревшим режимом инкрементальной компиляции JVM на основе истории, который был заменен подходом на основе classpath, включенным по умолчанию начиная с Kotlin 1.8.20.

Этапы устаревания:

  • 2.0.20: свойство kotlin.incremental.useClasspathSnapshot устаревает с предупреждением

  • 2.2.0: свойство удаляется

Устаревшие возможности Kotlin Scripting

Задачи: KT-71685, KT-75632, KT-76196.

Компонент: Scripting

Тип несовместимого изменения: исходный код

Краткое описание: В Kotlin 2.2.0 объявлена устаревшей поддержка следующих возможностей:

  • REPL: чтобы продолжить использовать REPL через kotlinc, включите параметр компилятора -Xrepl.

  • JSR-223: поскольку JSR находится в состоянии отзыва. Реализация JSR-223 продолжает работать с версией языка 1.9, но планов по переходу на компилятор K2 нет.

  • Плагин Maven KotlinScriptMojo. При дальнейшем использовании будут выводиться предупреждения компилятора.

Дополнительные сведения см. в нашей статье в блоге.

Этапы устаревания:

  • 2.1.0: использование REPL в kotlinc объявляется устаревшим с предупреждением

  • 2.2.0: для использования REPL через kotlinc включите параметр компилятора -Xrepl; поддержка JSR-223 объявляется устаревшей, ее можно восстановить, переключившись на версию языка 1.9; плагин Maven KotlinScriptMojo объявляется устаревшим

  • 2.4.0: выполнение скриптов Kotlin через плагин Maven KotlinScriptMojo удаляется

Устаревание свойств классификатора для разрешения неоднозначности

Задача: KT-58231

Компонент: Gradle

Тип несовместимого изменения: исходный код

Краткое описание: Параметры, управлявшие тем, как плагин Kotlin Gradle разрешает неоднозначность имен наборов исходных файлов и импортов IDE, устарели. Поэтому следующие свойства интерфейса KotlinTarget теперь считаются устаревшими:

  • useDisambiguationClassifierAsSourceSetNamePrefix

  • overrideDisambiguationClassifierOnIdeImport

Этапы устаревания:

  • 2.0.0: при использовании свойств Gradle выводится предупреждение

  • 2.1.0: предупреждение повышается до ошибки

  • 2.2.0: свойства Gradle удаляются

Устаревание параметров обобщения

Задача: KT-75161

Компонент: Gradle

Тип несовместимого изменения: исходный код

Краткое описание: Параметры экспериментальных режимов обобщения устарели в плагине Kotlin Gradle. Эти параметры могут приводить к созданию некорректных артефактов компиляции, которые затем кэшируются. Чтобы удалить затронутые артефакты:

  1. Удалите следующие параметры из файла gradle.properties:

    kotlin.mpp.enableOptimisticNumberCommonization
kotlin.mpp.enablePlatformIntegerCommonization

  2. Очистите кэш обобщения в каталоге ~/.konan/*/klib/commonized или выполните следующую команду:

    ./gradlew cleanNativeDistributionCommonization

Этапы устаревания:

  • 2.2.0: параметры обобщения объявляются устаревшими с ошибкой

  • 2.2.20: параметры обобщения удаляются

Устаревание поддержки компиляции метаданных прежнего формата

Задача: KT-61817

Компонент: Gradle

Тип несовместимого изменения: исходный код

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

  • isCompatibilityMetadataVariantEnabled

  • withGranularMetadata

  • isKotlinGranularMetadataEnabled

Этапы устаревания:

  • 2.2.0: параметры компилятора удаляются из плагина Kotlin Gradle

Устаревание API KotlinCompilation.source

Задача: KT-64991

Компонент: Gradle

Тип несовместимого изменения: исходный код

Краткое описание: Доступ к API KotlinCompilation.source, который позволял добавлять наборы исходных файлов Kotlin непосредственно в компиляцию Kotlin, объявлен устаревшим.

Этапы устаревания:

  • 1.9.0: при использовании KotlinCompilation.source выводится предупреждение

  • 1.9.20: предупреждение повышается до ошибки

  • 2.2.0: KotlinCompilation.source удаляется из плагина Kotlin Gradle; попытки его использовать приводят к ошибкам «неразрешенная ссылка» при компиляции скрипта сборки

Устаревание API предустановок целевых платформ

Задача: KT-71698

Компонент: Gradle

Тип несовместимого изменения: исходный код

Краткое описание: Предустановки целевых платформ Kotlin Multiplatform устарели; те же сценарии использования теперь поддерживаются функциями DSL целевых платформ, такими как jvm() или iosSimulatorArm64(). Все API, связанные с предустановками, объявлены устаревшими:

  • Свойство presets в org.jetbrains.kotlin.gradle.dsl.KotlinMultiplatformExtension

  • Интерфейс org.jetbrains.kotlin.gradle.plugin.KotlinTargetPreset и все его наследники

  • Перегруженные варианты fromPreset

Этапы устаревания:

  • 1.9.20: при любом использовании API, связанного с предустановками, выводится предупреждение

  • 2.0.0: предупреждение повышается до ошибки

  • 2.2.0: API, связанное с предустановками, удаляется из публичного API плагина Kotlin Gradle; исходный код, в котором оно по-прежнему используется, вызывает ошибки «неразрешенная ссылка», а двоичные файлы (например, плагины Gradle) могут вызывать ошибки связывания, если их не перекомпилировать с последними версиями плагина Kotlin Gradle

Устаревание сокращенных обозначений целевых платформ Apple

Задача: KT-70615

Компонент: Gradle

Тип несовместимого изменения: исходный код

Краткое описание: Сокращенные обозначения целевых платформ ios(), watchos() и tvos() объявлены устаревшими в DSL Kotlin Multiplatform. Эти обозначения частично создавали иерархию наборов исходных файлов для целевых платформ Apple. Теперь плагин Kotlin Multiplatform Gradle предоставляет встроенный шаблон иерархии. Вместо сокращенных обозначений укажите список целевых платформ, и плагин автоматически настроит для них промежуточные наборы исходных файлов.

Этапы устаревания:

  • 1.9.20: при использовании сокращенных обозначений целевых платформ выводится предупреждение; вместо них по умолчанию включен шаблон иерархии

  • 2.1.0: при использовании сокращенных обозначений целевых платформ выводится ошибка

  • 2.2.0: DSL сокращенных обозначений целевых платформ удаляется из плагина Kotlin Multiplatform Gradle

Устаревание функции publishAllLibraryVariants()

Задача: KT-60623

Компонент: Gradle

Тип несовместимого изменения: исходный код

Краткое описание: Функция publishAllLibraryVariants() объявлена устаревшей. Она предназначалась для публикации всех вариантов сборки целевых платформ Android. Теперь такой подход не рекомендуется, поскольку он может вызывать проблемы при разрешении вариантов, особенно при использовании нескольких вариантов продукта и типов сборки. Вместо нее используйте функцию publishLibraryVariants(), задающую варианты сборки.

Этапы устаревания:

  • 2.2.0: publishAllLibraryVariants() объявлена устаревшей

Устаревание целевой платформы android

Задача: KT-71608

Компонент: Gradle

Тип несовместимого изменения: исходный код

Краткое описание: Имя целевой платформы android объявлено устаревшим в текущем DSL Kotlin. Вместо него используйте androidTarget.

Этапы устаревания:

  • 1.9.0: в проектах Kotlin Multiplatform при использовании имени android появляется предупреждение об устаревании

  • 2.1.0: предупреждение повышается до ошибки

  • 2.2.0: DSL целевой платформы android удаляется из плагина Kotlin Multiplatform Gradle

Устаревание konanVersion в CInteropProcess

Задача: KT-71069

Компонент: Gradle

Тип несовместимого изменения: исходный код

Краткое описание: Свойство konanVersion в задаче CInteropProcess объявлено устаревшим. Вместо него используйте CInteropProcess.kotlinNativeVersion.

Этапы устаревания:

  • 2.1.0: при использовании свойства konanVersion выводится предупреждение

  • 2.2.0: предупреждение повышается до ошибки

  • 2.3.0: свойство konanVersion удаляется из плагина Kotlin Gradle

Устаревание destinationDir в CInteropProcess

Задача: KT-71068

Компонент: Gradle

Тип несовместимого изменения: исходный код

Краткое описание: Свойство destinationDir в задаче CInteropProcess объявлено устаревшим. Вместо него используйте функцию CInteropProcess.destinationDirectory.set().

Этапы устаревания:

  • 2.1.0: при использовании свойства destinationDir выводится предупреждение

  • 2.2.0: предупреждение повышается до ошибки

  • 2.3.0: свойство destinationDir удаляется из плагина Kotlin Gradle

Устаревание API kotlinArtifacts

Задача: KT-74953

Компонент: Gradle

Тип несовместимого изменения: исходный код

Краткое описание: Экспериментальный API kotlinArtifacts объявлен устаревшим. Используйте текущий DSL плагина Kotlin Gradle, чтобы собирать итоговые бинарные файлы для нативных платформ. Если этого недостаточно для перехода, оставьте комментарий в этой задаче YouTrack.

Этапы устаревания:

  • 2.2.0: при использовании API kotlinArtifacts выводится предупреждение

  • 2.3.0: предупреждение повышается до ошибки

2 июня 2026 г.
Что нового в Kotlin 2.2.0Что нового в Kotlin 2.1.20

© 2010–2026 JetBrains s.r.o. and Kotlin Programming Language contributors
Licensed under the Apache License, Version 2.0.
https://kotlinlang.org/docs/compatibility-guide-22.html

Spec-Zone.ru

Настройки Оффлайн Что нового Помощь О нас
Spec-Zone .ru
спецификации, руководства, описания, API