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

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

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

Основные термины

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

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

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

Язык

Удаление версии языка 1.3

Запрет вызова конструктора super, если тип суперинтерфейса является литералом функции

Запрет циклов в типах параметров аннотаций

Задача: KT-47932

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

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

Краткое описание: Kotlin 1.9 запрещает использовать тип аннотации в качестве одного из типов её параметров — напрямую или косвенно. Это предотвращает возникновение циклов. При этом в качестве типов параметров разрешено указывать Array или vararg типа аннотации.

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

1.7.0: выдавать предупреждение (или ошибку в прогрессивном режиме) для циклов в типах параметров аннотаций
1.9.0: повысить уровень предупреждения до ошибки; для временного возврата к поведению до версии 1.9 можно использовать -XXLanguage:-ProhibitCyclesInAnnotations

Запрет использования аннотации @ExtensionFunctionType для типов функций без параметров

Задача: KT-43527

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

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

Краткое описание: Kotlin 1.9 запрещает использовать аннотацию @ExtensionFunctionType для типов функций без параметров, а также для типов, не являющихся типами функций.

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

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

Запрет несовпадения типа поля Java при присваивании

Задача: KT-48994

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

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

Краткое описание: Kotlin 1.9 выдаёт ошибку компилятора, если обнаруживает, что тип значения, присваиваемого полю Java, не совпадает с проецируемым типом этого поля.

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

1.6.0: выдавать предупреждение (или ошибку в прогрессивном режиме), если проецируемый тип поля Java не совпадает с типом присваиваемого значения
1.9.0: повысить уровень предупреждения до ошибки; для временного возврата к поведению до версии 1.9 можно использовать -XXLanguage:-RefineTypeCheckingOnAssignmentsToJavaFields

Отсутствие фрагментов исходного кода в исключениях при проверке на null для платформенных типов

Задача: KT-57570

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

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

Краткое описание: В Kotlin 1.9 сообщения исключений для проверок выражений на null не содержат фрагментов исходного кода. Вместо этого отображается имя метода или поля. Если выражение не является методом или полем, в сообщении не приводится дополнительная информация.

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

< 1.9.0: сообщения исключений, сформированные проверками выражений на null, содержат фрагменты исходного кода
1.9.0: сообщения исключений, сформированные проверками выражений на null, содержат только имена методов или полей; для временного возврата к поведению до версии 1.9 можно использовать -XXLanguage:-NoSourceCodeInNotNullAssertionExceptions

Запрет делегирования вызовов super абстрактному члену суперкласса

Задачи: KT-45508, KT-49017, KT-38078

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

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

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

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

1.5.20: ввести предупреждение при использовании неабстрактных классов, которые не переопределяют все абстрактные члены
1.7.0: выдавать предупреждение, если вызов super фактически обращается к абстрактному члену суперкласса
1.7.0: выдавать ошибку во всех затронутых случаях, если включён режим совместимости -Xjvm-default=all или -Xjvm-default=all-compatibility; выдавать ошибку в прогрессивном режиме
1.8.0: выдавать ошибку при объявлении конкретного класса с непереопределённым абстрактным методом суперкласса, а также когда вызовы методов Any переопределяются как абстрактные в суперклассе
1.9.0: выдавать ошибку во всех затронутых случаях, включая явные вызовы super для абстрактного метода суперкласса

Устаревание неоднозначных грамматических конструкций в when с subject

Задача: KT-48385

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

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

Краткое описание: В Kotlin 1.6 несколько неоднозначных грамматических конструкций в выражениях условий when объявлены устаревшими.

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

1.6.20: ввести предупреждение об устаревании для затронутых выражений
1.8.0: повысить уровень этого предупреждения до ошибки; для временного возврата к поведению до версии 1.8 можно использовать -XXLanguage:-ProhibitConfusingSyntaxInWhenBranches
>= 2.1: использовать некоторые устаревшие конструкции для новых возможностей языка

Предотвращение неявных преобразований между разными числовыми типами

Задача: KT-48645

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

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

Краткое описание: Kotlin перестанет автоматически преобразовывать числовые значения к примитивному числовому типу, если с точки зрения семантики требуется лишь приведение к этому типу.

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

< 1.5.30: старое поведение во всех затронутых случаях
1.5.30: исправить поведение приведения типов в сгенерированных аксессорах делегатов свойств; для временного возврата к поведению до исправления в версии 1.5.30 можно использовать -Xuse-old-backend
>= 2.0: исправить поведение приведения типов в других затронутых случаях

Запрет нарушения верхней границы при использовании обобщённого псевдонима типа (параметр типа используется как аргумент обобщённого типа в аргументе типа псевдонима)

Задача: KT-54066

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

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

Краткое описание: Kotlin запретит использование псевдонима типа с аргументами типа, нарушающими ограничения верхней границы для соответствующих параметров типа псевдонима, если параметр типа typealias используется как аргумент обобщённого типа в аргументе типа псевдонима; например, typealias Alias<T> = Base<List<T>>.

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

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

Сохранение допуска null при аппроксимации локальных типов в публичных сигнатурах

Задача: KT-53982

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

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

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

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

1.8.0: аппроксимировать гибкие типы гибкими супертипами
1.8.0: выдавать предупреждение, если объявление выводится как тип, не допускающий null, хотя должно допускать null; это побуждает пользователей указывать тип явно
2.0.0: аппроксимировать nullable-типы nullable-супертипами; для временного возврата к поведению до версии 2.0 можно использовать -XXLanguage:-KeepNullabilityWhenApproximatingLocalType

Не распространять устаревание через переопределения

Задача: KT-47902

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

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

Краткое описание: В Kotlin 1.9 устаревание больше не будет распространяться от устаревшего члена суперкласса на переопределяющий его член подкласса. Таким образом появится явный способ пометить член суперкласса как устаревший, оставив переопределяющий член в подклассе неустаревшим.

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

1.6.20: выдавать предупреждение с описанием будущего изменения поведения и предложением либо подавить это предупреждение, либо явно добавить аннотацию @Deprecated к переопределению устаревшего члена
1.9.0: прекратить распространение статуса устаревания на переопределяющие члены. Это изменение также немедленно вступает в силу в прогрессивном режиме

Запрет использования литералов коллекций в классах аннотаций вне объявлений их параметров

Задача: KT-39041

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

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

Краткое описание: Kotlin разрешает ограниченное использование литералов коллекций — для передачи массивов параметрам классов аннотаций или задания значений по умолчанию для этих параметров. Однако помимо этого Kotlin разрешал использовать литералы коллекций в любых других местах класса аннотации, например во вложенном объекте. Kotlin 1.9 запретит использовать литералы коллекций в классах аннотаций где-либо, кроме значений параметров по умолчанию.

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

1.7.0: выдавать предупреждение (или ошибку в прогрессивном режиме) для литералов массивов во вложенных объектах классов аннотаций
1.9.0: повысить уровень предупреждения до ошибки

Запрет ссылок на последующие параметры в выражениях значений по умолчанию

Задача: KT-25694

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

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

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

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

1.7.0: выдавать предупреждение (или ошибку в прогрессивном режиме), если на параметр со значением по умолчанию ссылаются в значении по умолчанию другого параметра, расположенного перед ним
1.9.0: повысить уровень предупреждения до ошибки; для временного возврата к поведению до версии 1.9 можно использовать -XXLanguage:-ProhibitIllegalValueParameterUsageInDefaultArguments

Запрет вызовов расширений для функциональных параметров inline

Задача: KT-52502

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

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

Краткое описание: Хотя Kotlin разрешал передавать функциональный параметр inline в другую функцию inline в качестве получателя, при компиляции такого кода всегда возникали исключения компилятора. Kotlin 1.9 запретит это и будет выдавать ошибку вместо аварийного завершения компилятора.

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

1.7.20: выдавать предупреждение (или ошибку в прогрессивном режиме) для вызовов функций-расширений inline с функциональными параметрами inline
1.9.0: повысить уровень предупреждения до ошибки

Запрет вызовов инфиксных функций с именем suspend и аргументом-функцией без имени

Задача: KT-49264

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

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

Краткое описание: В Kotlin 1.9 больше нельзя будет вызывать инфиксные функции с именем suspend, имеющие единственный аргумент функционального типа, переданный в виде литерала анонимной функции.

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

1.7.20: выдавать предупреждение при инфиксных вызовах suspend с литералом анонимной функции
1.9.0: повысить уровень предупреждения до ошибки; для временного возврата к поведению до версии 1.9 можно использовать -XXLanguage:-ModifierNonBuiltinSuspendFunError
TODO: изменить интерпретацию парсером последовательности токенов suspend fun

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

Задача: KT-50947

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

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

Краткое описание: Kotlin 1.9 запретит использовать параметры типа внешнего класса с вариантностью in или out во внутреннем классе этого класса в позициях, нарушающих объявленную вариантность этих параметров типа.

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

1.7.0: выдавать предупреждение (или ошибку в прогрессивном режиме), если позиция использования параметра типа внешнего класса нарушает правила вариантности этого параметра
1.9.0: повысить уровень предупреждения до ошибки; для временного возврата к поведению до версии 1.9 можно использовать -XXLanguage:-ReportTypeVarianceConflictOnQualifierArguments

Запрет рекурсивного вызова функции без явно указанного типа возвращаемого значения в операторах составного присваивания

Задача: KT-48546

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

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

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

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

1.7.0: выдавать предупреждение (или ошибку в прогрессивном режиме), если функция без явно указанного типа возвращаемого значения рекурсивно вызывается в аргументе оператора составного присваивания внутри её тела
1.9.0: повысить уровень предупреждения до ошибки

Запрет небезопасных вызовов с ожидаемым @NotNull T и параметром обобщённого типа Kotlin с nullable-ограничением

Задача: KT-36770

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

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

Краткое описание: Kotlin 1.9 запретит вызовы методов, при которых значение потенциально nullable-типа передаётся параметру метода Java с аннотацией @NotNull.

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

1.5.20: выдавать предупреждение, если параметр обобщённого типа без ограничений передаётся туда, где ожидается тип, не допускающий null
1.9.0: вместо указанного выше предупреждения выдавать ошибку несоответствия типов;
для временного возврата к поведению до версии 1.8 можно использовать -XXLanguage:-ProhibitUsingNullableTypeParameterAgainstNotNullAnnotated

Запретить доступ к членам companion-объекта enum-класса из инициализаторов элементов этого enum

Задача: KT-49110

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

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

Краткое описание: В Kotlin 1.9 будет запрещен любой доступ к companion-объекту enum из инициализатора элемента enum.

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

1.6.20: выдавать предупреждение (или ошибку в прогрессивном режиме) при таком обращении к члену companion-объекта
1.9.0: повысить уровень предупреждения до ошибки; -XXLanguage:-ProhibitAccessToEnumCompanionMembersInEnumConstructorCall можно использовать для временного возврата к поведению до версии 1.8

Устаревание и удаление синтетического свойства Enum.declaringClass

Задача: KT-49653

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

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

Краткое описание: Kotlin разрешал использовать синтетическое свойство declaringClass для значений Enum, полученных из метода getDeclaringClass() базового класса Java java.lang.Enum, хотя этот метод недоступен для типа Kotlin Enum. В Kotlin 1.9 использование этого свойства будет запрещено; вместо него будет предложено перейти на свойство-расширение declaringJavaClass.

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

1.7.0: выдавать предупреждение (или ошибку в прогрессивном режиме) при использовании свойства declaringClass и предлагать перейти на расширение declaringJavaClass
1.9.0: повысить уровень предупреждения до ошибки; -XXLanguage:-ProhibitEnumDeclaringClass можно использовать для временного возврата к поведению до версии 1.9
2.0.0: удалить синтетическое свойство declaringClass

Устаревание режимов enable и compatibility параметра компилятора -Xjvm-default

Запретить неявный вывод переменной типа в верхнюю границу в контексте builder inference

Задача: KT-47986

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

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

Краткое описание: В Kotlin 2.0 будет запрещен вывод переменной типа в верхнюю границу соответствующего параметра типа, если в области видимости лямбда-функций builder inference отсутствует информация о типе из места использования; сейчас в других контекстах действует такое же ограничение.

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

1.7.20: выдавать предупреждение (или ошибку в прогрессивном режиме), если параметр типа выводится в объявленные верхние границы при отсутствии информации о типе из места использования
2.0.0: повысить уровень предупреждения до ошибки

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

Предупреждение о возможном изменении разрешения перегрузок после реализации Collection в Range/Progression

Задача: KT-49276

Компонент: основной язык / kotlin-stdlib

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

Краткое описание: В Kotlin 1.9 планируется реализовать интерфейс Collection в стандартных последовательностях и конкретных диапазонах, унаследованных от них. Это может привести к выбору другой перегрузки при разрешении перегрузок, если для некоторого метода есть две перегрузки: одна принимает элемент, а другая — коллекцию. Kotlin сообщит об этой ситуации, выдавая предупреждение или ошибку при вызове такого перегруженного метода с аргументом типа «диапазон» или «последовательность».

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

1.6.20: выдавать предупреждение при вызове перегруженного метода со стандартной последовательностью или диапазоном-наследником в качестве аргумента, если реализация этой последовательностью/диапазоном интерфейса Collection в будущем приведет к выбору другой перегрузки при вызове
1.8.0: повысить уровень этого предупреждения до ошибки
2.1.0: перестать сообщать об ошибке и реализовать интерфейс Collection в последовательностях, изменив тем самым результат разрешения перегрузок в затронутых случаях

Перенос объявлений из пакетов kotlin.dom и kotlin.browser в kotlinx.*

Задача: KT-39330

Компонент: kotlin-stdlib (JS)

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

Краткое описание: объявления из пакетов kotlin.dom и kotlin.browser переносятся в соответствующие пакеты kotlinx.*, чтобы подготовить их к выделению из stdlib.

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

1.4.0: добавить API-замену в пакеты kotlinx.dom и kotlinx.browser
1.4.0: объявить API в пакетах kotlin.dom и kotlin.browser устаревшим и предложить новое API выше в качестве замены
1.6.0: повысить уровень устаревания до ошибки
1.8.20: удалить устаревшие функции из stdlib для целевой платформы JS-IR
>= 2.0: перенести API из пакетов kotlinx.* в отдельную библиотеку

Устаревание некоторых API только для JS

Задача: KT-48587

Компонент: kotlin-stdlib (JS)

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

Краткое описание: ряд функций stdlib, предназначенных только для JS, объявляется устаревшим и подлежащим удалению. К ним относятся: String.concat(String), String.match(regex: String), String.matches(regex: String), а также функции sort для массивов, принимающие функцию сравнения, например Array<out T>.sort(comparison: (a: T, b: T) -> Int).

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

1.6.0: объявить соответствующие функции устаревшими с выдачей предупреждения
1.9.0: повысить уровень устаревания до ошибки
>=2.0: удалить устаревшие функции из публичного API

Инструменты

Удаление флага enableEndorsedLibs из конфигурации Gradle

Удаление соглашений Gradle

Удаление свойства classpath задачи KotlinCompile

Устаревание свойства kotlin.internal.single.build.metrics.file

26 мая 2025 г.

© 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-19.html