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

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

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

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

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

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

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

Язык

Запрет делегирования вызовов 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-with-subject

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

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

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

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

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

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

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

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

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

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

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

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

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

Сделать частные конструкторы запечатанных классов действительно частными

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

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

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

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

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

1.6.20: выводить предупреждение (или ошибку в режиме поэтапного внедрения), когда закрытый конструктор запечатанного класса вызывается за пределами этого класса
1.8.0: использовать правила видимости по умолчанию для закрытых конструкторов (вызов закрытого конструктора может быть разрешен только если этот вызов находится внутри соответствующего класса), старое поведение можно временно вернуть, указав аргумент компилятора -XXLanguage:-UseConsistentRulesForPrivateConstructorsOfSealedClasses

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

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

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

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

Краткое описание: Kotlin 1.8 запретит использование оператора == на несовместимых числовых типах, например, Int и Long, в областях вывода лямбда-функций билдера, так же, как и в настоящее время в других контекстах

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

1.6.20: выводить предупреждение (или ошибку в режиме поэтапного внедрения) при использовании оператора == на несовместимых числовых типах
1.8.0: повысить предупреждение до ошибки, -XXLanguage:-ProperEqualityChecksInBuilderInferenceCalls может использоваться для временного возврата к поведению до 1.8

Запрет if без else и неполного when в правой части оператора Elvis

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

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

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

Краткое описание: Kotlin 1.8 запретит использование неполного when или выражения if без ветви else в правой части оператора Elvis (?:). Ранее это было разрешено, если результат оператора Elvis не использовался как выражение

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

1.6.20: выводить предупреждение (или ошибку в режиме поэтапного внедрения) для таких неполных выражений if и when
1.8.0: повысить это предупреждение до ошибки,
-XXLanguage:-ProhibitNonExhaustiveIfInRhsOfElvis может использоваться для временного возврата к поведению до 1.8

Запрет нарушения верхнего ограничения при использовании псевдонима типа (один параметр типа используется в нескольких аргументах типа алиасированного типа)

Проблемы: KT-29168

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

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

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

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

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

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

Вопрос: KT-54066

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

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

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

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

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

Запрет использования параметра типа, объявленного для расширяемого свойства, внутри делегата

Вопрос: KT-24643

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

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

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

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

1.6.0: выводить предупреждение (или ошибку в режиме поэтапного внедрения) при делегировании расширяемого свойства к типу, который использует параметры типа, выведенные из аргументов типа делегируемого свойства, определенным способом
1.8.0: повысить предупреждение до ошибки, -XXLanguage:-ForbidUsingExtensionPropertyTypeParameterInDelegate может быть использован для временного возврата к поведению до 1.8

Запрет аннотации @Synchronized на функции suspend

Вопрос: KT-48516

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

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

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

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

1.6.0: выводить предупреждение для функций suspend, помеченных аннотацией @Synchronized, предупреждение отображается как ошибка в режиме поэтапного внедрения
1.8.0: повысить предупреждение до ошибки, -XXLanguage:-SynchronizedSuspendError может быть использован для временного возврата к поведению до 1.8

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

Вопрос: KT-48162

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

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

Краткое описание: Kotlin разрешал передачу массивов с оператором spread (*) в параметры массивов, не являющиеся vararg, в определенных условиях. Начиная с Kotlin 1.8, это будет запрещено

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

1.6.0: выводить предупреждение (или ошибку в режиме поэтапного внедрения) при использовании оператора spread там, где ожидается параметр массива, не являющийся vararg
1.8.0: повысить предупреждение до ошибки, -XXLanguage:-ReportNonVarargSpreadOnGenericCalls может быть использован для временного возврата к поведению до 1.8

Запрет нарушения безопасности при работе с null в лямбдах, переданных в функции, перегруженные по типу возвращаемой лямбдой

Вопрос: KT-49658

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

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

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

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

1.6.20: выводить предупреждение о несоответствии типов (или ошибку в режиме поэтапного внедрения)
1.8.0: повысить предупреждение до ошибки, -XXLanguage:-DontLoseDiagnosticsDuringOverloadResolutionByReturnType может быть использован для временного возврата к поведению до 1.8

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

Вопрос: KT-53982

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

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

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

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

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

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

Вопрос: KT-47902

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

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

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

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

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

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

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

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

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

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

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

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

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

Проблема: 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 1.9 больше не будет разрешать вызов инфиксных функций с именем suspend с единственным аргументом функционального типа, переданным как литерал анонимной функции

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Краткое описание: 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
>=1.10: удаляется синтетическое свойство declaringClass

Устаревание режимов включения и совместимости компиляторной опции -Xjvm-default

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

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

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

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

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

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

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

1.6.20: выводится предупреждение, когда перегруженный метод вызывается со стандартной прогрессией или её наследником-диапазоном в качестве аргумента, если реализация интерфейса Collection этой прогрессией/диапазоном приводит к выбору другой перегрузки в этом вызове в будущем.
1.8.0: это предупреждение повышается до ошибки.
1.9.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
>= 1.9: перемещение API в пакеты kotlinx.* в отдельную библиотеку

Устаревание некоторых JS-специфичных API

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

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

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

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

END_OF_DOCUMENT_MARKER

Инструменты

Повышение уровня устаревания свойства classpath задачи KotlinCompile

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

Удаление системного свойства kotlin.compiler.execution.strategy

Изменения в параметрах компилятора

Проблемы: KT-27301, KT-48532

Компонент: Gradle

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

Краткое описание: Это изменение может повлиять на авторов плагинов Gradle. В kotlin-gradle-plugin, добавлены дополнительные общие параметры к некоторым внутренним типам (вам нужно добавить общие типы или *). Задача KotlinNativeLink больше не наследует задачу AbstractKotlinNativeCompile. KotlinJsCompilerOptions.outputFile и связанные с ними параметры KotlinJsOptions.outputFile устарели. Используйте вход Kotlin2JsCompile.outputFileProperty задачи вместо него. Вход kotlinOptions задачи и DSL-синтаксис для задачи kotlinOptions{...} находятся в режиме поддержки и будут устаревшими в будущих выпусках. compilerOptions и kotlinOptions нельзя изменить на фазе выполнения задачи (см. одно исключение в Что нового в Kotlin 1.8). freeCompilerArgs возвращает неизменяемый List<String> – kotlinOptions.freeCompilerArgs.remove("something") завершится ошибкой. Удалено свойство useOldBackend, которое позволяло использовать старый JVM-бэкенд

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

1.8.0: задача KotlinNativeLink больше не наследует AbstractKotlinNativeCompile. KotlinJsCompilerOptions.outputFile и связанные с ними параметры KotlinJsOptions.outputFile устарели. Удалено свойство useOldBackend, которое позволяло использовать старый JVM-бэкенд.

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

Последнее изменение: 10 января 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-18.html