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

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

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

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

В данном документе мы вводим несколько видов совместимости:

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

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

Язык

Запрет вызова конструктора super, когда тип интерфейса super — это функция-литерал

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

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

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

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

Краткое описание: Kotlin 1.9 запрещает использование типа аннотации в качестве одного из типов параметров аннотации, прямо или косвенно. Это предотвращает создание циклов. Однако вы можете использовать типы параметров, которые являются Array или vararg типа аннотации.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Запрет делегирования вызовов 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: вывод ошибки в случаях объявления конкретного класса с непереопределённым абстрактным методом из суперкласса, и вызовы super для Any методов переопределяются как абстрактные в суперклассе
1.9.0: вывод ошибки во всех затронутых случаях, включая явные вызовы super к абстрактному методу из суперкласса

Устаревание запутанной грамматики в when-с-субъектом

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Сохранение возможности использования null при приближении локальных типов в общедоступных подписях

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

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

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

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

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

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

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

Проблема: 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: преобразовать предупреждение в ошибку, -XXLanguage:-ProhibitIllegalValueParameterUsageInDefaultArguments можно использовать для временного возврата к поведению до 1.9

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

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

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

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

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

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

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

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

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

Компонент: Язык Kotlin

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

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

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

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

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

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

Компонент: Язык Kotlin

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

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

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

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

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

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

Компонент: Язык Kotlin

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

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

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

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

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

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

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

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

Краткое описание: Kotlin 1.9 запретит вызовы методов, где значение потенциально необязательного параметра обобщенного типа передается для параметра Java-метода, помеченного @NotNull.

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

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

Запрет доступа к членам компаньона перечисления из инициализаторов элементов этого перечисления

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

Компонент: Язык Kotlin

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

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

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

1.6.20: выводить предупреждение (или ошибку в режиме пошаговой переработки) при доступе к члену такого компаньона
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

END_OF_DOCUMENT_MARKER

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

Задача: KT-47986

Компонент: Язык Kotlin

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

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

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

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

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

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

Задача: KT-49276

Компонент: Язык Kotlin / kotlin-stdlib

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

Краткое описание: планируется реализовать интерфейс Collection в стандартных прогрессиях и конкретных диапазонах, унаследованных от них, в Kotlin 1.9. Это может привести к выбору другой перегрузки при разрешении перегрузки, если есть две перегрузки какого-либо метода, одна принимающая элемент, а другая принимающая коллекцию. 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)

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

Краткое описание: ряд функций JS-only в stdlib устаревают для удаления. Они включают: 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

Последнее изменение: 03 июля 2023 г.

© 2010–2023 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