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

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

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

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

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

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

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

Язык

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

Проблемы: KT-45508, KT-49017, KT-38078

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

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

Краткое описание: 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

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

Краткое описание: 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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Задача: KT-54066

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

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

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

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

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

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

Задача: KT-24643

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

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

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

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

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

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

Задача: KT-48516

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

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

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

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

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

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

Задача: KT-48162

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

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

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

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

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

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

Задача: KT-49658

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

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

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

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

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

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

Задача: KT-53982

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

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

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

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

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

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

Задача: KT-47902

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Краткое описание: 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: выводится предупреждение, когда параметр обобщения без ограничений передаётся в качестве параметра, где ожидается не nullable-тип
1.9.0: вместо вышеуказанного предупреждения выводится ошибка типа,
-XXLanguage:-ProhibitUsingNullableTypeParameterAgainstNotNullAnnotated может быть использован для временного возврата к поведению до версии 1.8

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

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

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

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

Краткое описание: 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

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

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

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

Компонент: Язык Core / 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 не могут быть изменены на стадии выполнения задачи (см. исключение в What's new in 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

Последнее изменение: 30 декабря 2022

© 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