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

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

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

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

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

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

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

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

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

Отсутствующие аннотации для получения значений параметров конструктора аннотаций

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

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

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

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

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

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

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

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

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

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

Краткое описание: ошибки в аннотациях @get: будут корректно отображаться в версии 1.3

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

<1.2: ошибки компиляции в аннотациях @get: не отображались, приводя к компиляции некорректного кода.
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-массива.

END_OF_DOCUMENT_MARKER

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

Вопрос: KT-13762

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

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

Краткое описание: начиная с Kotlin 1.3, разрешена только аннотация SOURCE для аннотаций с целевым значением EXPRESSION

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

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

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

Вопрос: KT-9580

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

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

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

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