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

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

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

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

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

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

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

Несовместимые изменения

Порядок вычисления аргументов конструктора относительно вызова

Отсутствие аннотаций, нацеленных на геттеры, в параметрах конструктора аннотаций

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

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

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

Краткое описание: аннотации, нацеленные на геттеры, в параметрах конструктора аннотаций, будут корректно записаны в файлы class в версии 1.3

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

<1.3: аннотации, нацеленные на геттеры, в параметрах конструктора аннотаций, не применяются
>=1.3: аннотации, нацеленные на геттеры, в параметрах конструктора аннотаций, корректно применяются и записываются в сгенерированный код

Отсутствие ошибок в аннотациях @get: конструктора класса

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

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

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

Краткое описание: ошибки в аннотациях, нацеленных на геттеры, будут корректно сообщаться в версии 1.3

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

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

Утверждения о неименовании для доступа к типам Java, помеченных аннотациями @NotNull

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

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

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

Краткое описание: утверждения о неименовании для типов Java, помеченных аннотациями not-null, будут генерироваться более агрессивно, что приведёт к более быстрому отказу кода, который проходит null здесь.

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

<1.3: компилятор мог пропустить такие утверждения при использовании вывода типов, что допускало потенциальное null распространение во время компиляции по отношению к бинарникам (подробности см. в проблеме).
>=1.3: компилятор генерирует пропущенные утверждения. Это может привести к более быстрому отказу кода, который (ошибочно) проходил null здесь.
-XXLanguage:-StrictJavaNullabilityAssertions может быть использован для временного возврата к поведению до версии 1.3. Поддержка этого флага будет удалена в следующей основной версии.

Ненадёжные интеллектуальные преобразования типов на членах перечислений

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

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

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

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

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

<1.3: интеллектуальное преобразование типа на члене одной записи перечисления могло привести к ненадёжному интеллектуальному преобразованию типа на том же члене других записей перечисления.
>=1.3: интеллектуальное преобразование типа будет корректно применено только к члену одной записи перечисления.
-XXLanguage:-SoundSmartcastForEnumEntries временно вернёт старое поведение. Поддержка этого флага будет удалена в следующей основной версии.

Переназначение вспомогательного поля val в геттере

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

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

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

Краткое описание: переназначение вспомогательного поля val свойства в его геттере теперь запрещено

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

<1.2: компилятор Kotlin разрешал изменение вспомогательного поля val в его геттере. Это не только нарушает семантику Kotlin, но и генерирует плохое поведение байткода JVM, которое переназначает поле final.
1.2.X: предупреждение об устаревании сообщается для кода, который переназначает вспомогательное поле val
>=1.3: предупреждения об устаревании повышаются до ошибок

Захват массива перед циклом for, в котором он итерируется

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

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

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

Краткое описание: если выражение в диапазоне цикла for является локальной переменной, обновлённой в теле цикла, это изменение влияет на выполнение цикла. Это несовместимо с итерацией по другим контейнерам, таким как диапазоны, последовательности символов и коллекциям.

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

<1.2: описанные образцы кода компилировались корректно, но обновления локальной переменной влияли на выполнение цикла.
1.2.X: предупреждение об устаревании сообщается, если выражение диапазона в цикле for является локальной переменной типа массив, которая присваивается в теле цикла.
1.3: изменение поведения в таких случаях становится совместимым с другими контейнерами.

Вложенные классификаторы в записях перечисления

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

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

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

Краткое описание: начиная с Kotlin 1.3, вложенные классификаторы (классы, объекты, интерфейсы, аннотированные классы, перечисления классов) в записях перечислений запрещены

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

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

Переопределение копирования в классах данных

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

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

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

Краткое описание: начиная с Kotlin 1.3, классам данных запрещено переопределять copy()

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

<1.2: переопределение копирования в классах данных copy() компилировалось успешно, но могло привести к ошибкам во время выполнения/непредсказуемому поведению
1.2.X: для переопределения копирования в классах данных copy() выводились предупреждения об устаревании
>=1.3: предупреждения об устаревании стали ошибками

Вложенные классы, наследующие Throwable, которые捕获 обобщенные параметры из внешнего класса

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

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

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

Краткое описание: начиная с Kotlin 1.3, вложенным классам запрещено наследовать Throwable

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

<1.2: вложенные классы, наследующие Throwable, компилировались успешно. Если такие вложенные классы случайно захватили обобщенные параметры, это могло привести к странным паттернам кода, которые приводили к ошибкам во время выполнения.
1.2.X: для вложенных классов, наследующих Throwable, выводились предупреждения об устаревании.
>=1.3: предупреждения об устаревании стали ошибками.

Правила видимости для сложных иерархий классов с компаньон-объектами

Проблемы: KT-21515, KT-25333

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

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

Краткое описание: начиная с Kotlin 1.3, правила видимости коротких имен стали строже для сложных иерархий классов, включающих компаньон-объекты и вложенные классификаторы.

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

<1.2: старые правила видимости (см. проблему для получения подробностей)
1.2.X: для коротких имен, которые больше не будут доступны, выводились предупреждения об устаревании. Инструменты предлагали автоматическую миграцию путем добавления полного имени.
>=1.3: предупреждения об устаревании стали ошибками. Для устранения проблемы необходимо добавить полные квалификаторы или явные импорты.

Непостоянные параметры vararg аннотаций

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

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

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

Краткое описание: начиная с Kotlin 1.3, установление непостоянных значений в качестве параметров vararg аннотаций запрещено.

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

<1.2: компилятор позволял передавать непостоянные значения в качестве параметра vararg аннотации, но на самом деле отбрасывал это значение во время генерации байткода, что приводило к неявным последствиям.
1.2.X: для таких паттернов кода выводились предупреждения об устаревании.
>=1.3: предупреждения об устаревании стали ошибками.

Локальные классы аннотаций

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

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

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

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

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

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

<1.2: компилятор позволял выполнять умные преобразования типов для локальных делегированных свойств, что могло привести к некорректным умным преобразованиям в случае плохо работающих делегатов.
1.2.X: умные преобразования типов для локальных делегированных свойств считались устаревшими (компилятор выводил предупреждения).
>=1.3: предупреждения об устаревании стали ошибками.

Конвенция оператора mod

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

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

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

Краткое описание: начиная с Kotlin 1.3, объявление оператора mod запрещено, а также вызовы, которые разрешаются на такие объявления.

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

1.1.X, 1.2.X: выводились предупреждения об устаревании при объявлении operator mod, а также при вызовах, которые разрешались на него.
1.3.X: предупреждения об устаревании стали ошибками, но вызовы всё ещё разрешались на объявления operator mod.
1.4.X: вызовы operator mod больше не разрешаются.

Передача одного элемента в vararg в именованной форме

Проблемы: KT-20588, KT-20589. Также см. KT-20171

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

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

Краткое описание: в Kotlin 1.3 присвоение одного элемента в vararg устарело и должно быть заменено последовательным применением spread и построением массива.

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

<1.2: присвоение одного элемента vararg в именованной форме компилировалось успешно и обрабатывалось как присвоение *единственного* элемента массиву, что приводило к неявным последствиям при присвоении массива vararg.
1.2.X: для таких присвоений выводились предупреждения об устаревании, пользователям предлагалось перейти к последовательному применению spread и построению массива.
1.3.X: предупреждения об устаревании стали ошибками.
>= 1.4: меняется семантика присвоения одного элемента vararg, делая присвоение массива эквивалентным присвоению spread массива.

Сохранение аннотаций с целевым выражением EXPRESSION

Аннотации с целевым параметром PARAMETER не должны применяться к типу параметра

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

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

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

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

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

<1.2: вышеупомянутые шаблоны кода компилируются нормально; аннотации молча игнорируются и отсутствуют в байт-коде
1.2.X: предупреждения об устаревании сообщаются при таком использовании
>=1.3: предупреждения повышаются до ошибок

Array.copyOfRange вызывает исключение, когда индексы выходят за границы, вместо увеличения возвращаемого массива

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

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

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

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

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

<1.3: в случае, если toIndex в вызове Array.copyOfRange больше размера массива, недостающие элементы в диапазоне будут заполнены null, нарушая корректность системы типов Kotlin.
>=1.3: проверьте, находится ли toIndex в границах массива, и выбросьте исключение, если это не так

Прогрессии целых чисел и длинных чисел с шагом Int.MIN_VALUE и Long.MIN_VALUE запрещены и не будут разрешены для создания

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

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

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

Краткое описание: начиная с Kotlin 1.3, запрещено значение шага для целочисленных прогрессий, являющееся минимальным отрицательным значением его целочисленного типа (Long или Int), так что вызов IntProgression.fromClosedRange(0, 1, step = Int.MIN_VALUE) будет вызывать IllegalArgumentException

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

<1.3: можно было создать IntProgression с шагом Int.MIN_VALUE, что дает два значения [0, -2147483648], что является не очевидным поведением
>=1.3: выбросить IllegalArgumentException, если шаг является минимальным отрицательным значением его целочисленного типа

Проверка переполнения индекса в операциях над очень длинными последовательностями

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

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

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

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

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

<1.3: вызов таких методов для очень длинных последовательностей может давать отрицательные результаты из-за переполнения целых чисел
>=1.3: обнаружение переполнения в таких методах и немедленное выброс исключения

Унификация результата разделения по пустому совпадению регулярного выражения на разных платформах

Прекращенные устаревшие артефакты в дистрибутиве компилятора

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

Компонент: другие

Тип несовместимого изменения: Бинарный

Краткое описание: Kotlin 1.3 прекращает поддержку следующих устаревших бинарных артефактов:

kotlin-runtime: используйте kotlin-stdlib вместо этого
kotlin-stdlib-jre7/8: используйте kotlin-stdlib-jdk7/8 вместо этого
kotlin-jslib в дистрибутиве компилятора: используйте kotlin-stdlib-js вместо этого

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

1.2.X: артефакты были помечены как устаревшие, компилятор сообщал предупреждение об использовании этих артефактов
>=1.3: артефакты прекращены

Аннотации в stdlib

Последнее изменение: 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-13.html