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

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

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

Проблема: 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–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