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

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

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

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

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

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

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

Язык

Делайте операторы when с перечислениями, запечатанными типами и булевыми значениями исчерпывающими по умолчанию

Вопрос: KT-47709

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

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

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

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

1.6.0: введение предупреждения, если when оператор с перечислением, запечатанным типом или булевым значением не является исчерпывающим (ошибка в режиме постепенного обновления)
1.7.0: повышение этого предупреждения до уровня ошибки

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

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

Вопрос: KT-25289

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

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

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

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

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

Улучшения повышения точности нуллирования типов

Вопрос: KT-48623

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

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

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

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

1.4.30: введение предупреждений для случаев, когда более точное нуллирование типа может привести к ошибке
1.7.0: вывод более точного нуллирования типов 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 может быть использован для временного отключения отчета об ошибках

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

Запрет вызовов super из общедоступных inline-функций с abi

Вопрос: KT-45379

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

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

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

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

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

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

Вопрос: KT-48860

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

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

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

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

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

Запрет экспорта приватных вложенных типов из типов private-in-file

Вопрос: KT-20094

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

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

Краткое описание: В Kotlin 1.6 будет запрещено экспонировать приватные вложенные типы и внутренние классы из типов private-in-file.

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

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

Цель аннотации не анализируется в нескольких случаях для аннотаций на типе

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

Вопрос: KT-22562

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

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

Краткое описание: В 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, но с типом возвращаемого значения non-nullable

Устаревание функций массивов с плавающей точкой: 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.* в отдельную библиотеку

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

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

Инструменты

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

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

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

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

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

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

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

Последнее изменение: 28 декабря 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-16.html