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

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

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

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

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

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

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

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

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

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

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

END_OF_DOCUMENT_MARKER

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

Проблема: 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, делая присвоение массива эквивалентным присвоению развёрнутого массива.

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

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

Вопрос: 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

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