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

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

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

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

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

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

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

Язык

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Улучшения расширения возможности проверки типов на возможность быть null

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

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

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

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

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

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

Устаревание режимов enabled и compatibility параметра компилятора -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

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

Последнее изменение: 04 апреля 2022

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