Руководство по совместимости Kotlin 1.6.x

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

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

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

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

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

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

Язык

Сделать операторы when с субъектами enum, sealed и Boolean исчерпывающими по умолчанию

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

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

Компонент: ядро языка

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

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

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

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

Запретить доступ к членам класса в вызове конструктора super его companion-объекта и вложенных объектов

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

Компонент: ядро языка

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

Краткое описание: в Kotlin 1.6 будет сообщаться об ошибке для аргументов вызова конструктора super у companion- и обычных объектов, если получатель таких аргументов ссылается на содержащую декларацию

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

1.5.20: добавить предупреждение для проблемных аргументов
1.6.0: повысить уровень этого предупреждения до ошибки; -XXLanguage:-ProhibitSelfCallsInNestedObjects можно использовать для временного возврата к поведению до версии 1.6

Улучшения уточнения nullability типов

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

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

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

Краткое описание: в Kotlin 1.7 изменится способ загрузки и интерпретации аннотаций nullability типов в коде Java

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

1.4.30: добавить предупреждения для случаев, когда более точная nullability типа может привести к ошибке
1.7.0: более точно определять nullability типов Java; -XXLanguage:-TypeEnhancementImprovementsInStrictMode можно использовать для временного возврата к поведению до версии 1.7

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

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

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

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

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

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

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

Запретить объявления повторяемых классов аннотаций, контейнерная аннотация которых нарушает требования JLS

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

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

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

Краткое описание: в Kotlin 1.6 будет проверяться, что контейнерная аннотация повторяемой аннотации удовлетворяет тем же требованиям, что и JLS 9.6.3: метод значения с типом-массивом, срок хранения и целевой элемент

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

1.5.30: добавить предупреждение для объявлений контейнерных аннотаций повторяемых аннотаций, нарушающих требования JLS (ошибка в прогрессивном режиме)
1.6.0: повысить уровень этого предупреждения до ошибки; -XXLanguage:-RepeatableAnnotationContainerConstraints можно использовать для временного отключения сообщений об ошибке

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

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

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

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

Краткое описание: в Kotlin 1.6 будет проверяться, что объявленная в Kotlin повторяемая аннотация не содержит вложенного класса с предопределённым именем Container

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

1.5.30: добавить предупреждение для вложенных классов с именем Container в классе повторяемой аннотации Kotlin (ошибка в прогрессивном режиме)
1.6.0: повысить уровень этого предупреждения до ошибки; -XXLanguage:-RepeatableAnnotationContainerConstraints можно использовать для временного отключения сообщений об ошибке

Запретить @JvmField для свойства первичного конструктора, переопределяющего свойство интерфейса

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

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

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

Краткое описание: в Kotlin 1.6 будет запрещено аннотировать аннотацией @JvmField свойство, объявленное в первичном конструкторе и переопределяющее свойство интерфейса

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

1.5.20: добавить предупреждение об использовании аннотации @JvmField для таких свойств первичного конструктора
1.6.0: повысить уровень этого предупреждения до ошибки; -XXLanguage:-ProhibitJvmFieldOnOverrideFromInterfaceInPrimaryConstructor можно использовать для временного отключения сообщений об ошибке

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

Запретить вызовы super из inline-функций с публичным ABI

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

Компонент: ядро языка

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

Краткое описание: в Kotlin 1.6 будет запрещён вызов функций с квалификатором super из публичных или защищённых inline-функций и свойств

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

1.5.0: добавить предупреждение о вызовах super из публичных или защищённых inline-функций и аксессоров свойств
1.6.0: повысить уровень этого предупреждения до ошибки; -XXLanguage:-ProhibitSuperCallsFromPublicInline можно использовать для временного отключения сообщений об ошибке

Запретить вызовы защищённых конструкторов из публичных inline-функций

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

Компонент: ядро языка

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

Краткое описание: в Kotlin 1.6 будет запрещён вызов защищённых конструкторов из публичных или защищённых inline-функций и свойств

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

1.4.30: добавить предупреждение о вызовах защищённых конструкторов из публичных или защищённых inline-функций и аксессоров свойств
1.6.0: повысить уровень этого предупреждения до ошибки; -XXLanguage:-ProhibitProtectedConstructorCallFromPublicInline можно использовать для временного отключения сообщений об ошибке

Запретить раскрытие приватных вложенных типов из типов, приватных в пределах файла

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

Компонент: ядро языка

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

Краткое описание: в Kotlin 1.6 будет запрещено раскрывать приватные вложенные типы и внутренние классы из типов, приватных в пределах файла

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

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

В некоторых случаях целевой элемент аннотации не анализируется для аннотаций типа

Запретить вызовы функций с именем suspend и завершающим лямбда-выражением

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

Компонент: ядро языка

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

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

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

1.3.0: добавить предупреждение о таких вызовах функций
1.6.0: повысить уровень этого предупреждения до ошибки
>= 1.7.0: изменить грамматику языка, чтобы suspend перед { разбиралось как ключевое слово

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

Удаление ненадёжной оптимизации contains в minus/removeAll/retainAll

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

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

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

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

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

< 1.6: прежнее поведение: в некоторых случаях аргумент преобразуется в множество
1.6.0: если аргумент функции является коллекцией, он больше не преобразуется в Set. Если аргумент не является коллекцией, вместо этого он может быть преобразован в List.
Прежнее поведение можно временно включить обратно в JVM, задав системное свойство kotlin.collections.convert_arg_to_set_in_removeAll=true
>= 1.7: указанное выше системное свойство больше не будет действовать

Изменение алгоритма генерации значений в Random.nextLong

Постепенное изменение типа возвращаемого значения функций min и max для коллекций на не допускающий null

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

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

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

Краткое описание: тип возвращаемого значения функций min и max для коллекций станет не допускающим null в Kotlin 1.7

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

1.4.0: добавление функций ...OrNull в качестве синонимов и устаревание затронутого API (подробности см. в описании проблемы)
1.5.0: повышение уровня устаревания затронутого API до ошибки
1.6.0: исключение устаревших функций из публичного API
>= 1.7: возвращение затронутого API с типом возвращаемого значения, не допускающим null

Устаревание функций массивов с числами с плавающей точкой: contains, indexOf, lastIndexOf

Перенос объявлений из пакетов 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.7: удаление устаревших функций из stdlib
>= 1.7: перенос API из пакетов kotlinx.* в отдельную библиотеку

Отказ от inline для функции Regex.replace в Kotlin/JS

Различное поведение функции Regex.replace в JVM и JS, если строка замены содержит ссылку на группу

Использование свёртки регистра Unicode в JS Regex

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

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

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

Краткое описание: класс Regex в Kotlin/JS будет использовать флаг unicode при вызове базового движка регулярных выражений JS для поиска и сравнения символов согласно правилам Unicode. Это накладывает определённые требования к версии среды JS и приводит к более строгой проверке избыточного экранирования в строке шаблона регулярного выражения.

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

1.5.0: включение свёртки регистра Unicode в большинстве функций класса JS Regex
1.6.0: включение свёртки регистра Unicode в функции Regex.replaceFirst

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

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

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

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

Краткое описание: ряд функций стандартной библиотеки, доступных только в 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.7.0: повышение уровня устаревания до ошибки
1.8.0: удаление устаревших функций из публичного API

Скрытие функций, специфичных для реализации и взаимодействия, из публичного API классов в Kotlin/JS

Инструменты

Устаревание класса KotlinGradleSubplugin

Удаление параметра сборки kotlin.useFallbackCompilerSearch

Удаление нескольких параметров компилятора

Устаревание параметра компилятора useIR

Устаревание свойства Gradle kapt.use.worker.api

Удаление свойства Gradle kotlin.parallel.tasks.in.project

Устаревание параметра DSL Gradle kotlin.experimental.coroutines и свойства Gradle kotlin.coroutines

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-16.html