Руководство по совместимости для Kotlin 2.1.x

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

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

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

В этом документе рассматриваются несколько видов совместимости:

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

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

Язык

Удаление версий языка 1.4 и 1.5

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

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

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

Краткое описание: В Kotlin 2.1 появилась версия языка 2.1 и прекращена поддержка версий языка 1.4 и 1.5. Версии языка 1.6 и 1.7 объявлены устаревшими.

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

1.6.0: выдавать предупреждение для версии языка 1.4
1.9.0: выдавать предупреждение для версии языка 1.5
2.1.0: выдавать предупреждение для версий языка 1.6 и 1.7; повысить уровень предупреждения до ошибки для версий языка 1.4 и 1.5

Изменение поведения функции typeOf() в Kotlin/Native

Запрет на раскрытие типов через ограничения параметров типа

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

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

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

Краткое описание: Теперь запрещено раскрывать типы с более низким уровнем видимости через ограничения параметров типа. Это устраняет несоответствия в правилах видимости типов. Благодаря этому к ограничениям параметров типа применяются те же правила видимости, что и к классам, и предотвращаются такие проблемы, как ошибки проверки IR в JVM.

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

2.1.0: выдавать предупреждение при раскрытии типов с более низким уровнем видимости через ограничения параметров типа
2.2.0: повысить уровень предупреждения до ошибки

Запрет на наследование абстрактного свойства var и свойства val с одинаковым именем

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

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

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

Краткое описание: Если класс наследует абстрактное свойство var от интерфейса и свойство val с тем же именем от суперкласса, теперь это приводит к ошибке компиляции. Это устраняет сбои во время выполнения, вызванные отсутствием сеттеров в таких случаях.

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

2.1.0: выдавать предупреждение (или ошибку в прогрессивном режиме), если класс наследует абстрактное свойство var от интерфейса и свойство val с тем же именем от суперкласса
2.2.0: повысить уровень предупреждения до ошибки

Выдача ошибки при обращении к неинициализированным элементам enum

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

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

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

Краткое описание: Теперь компилятор сообщает об ошибке, если к неинициализированным элементам enum обращаются во время инициализации класса enum или его элементов. Это приводит поведение в соответствие с правилами инициализации свойств-членов, предотвращая исключения во время выполнения и обеспечивая единообразную логику.

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

2.1.0: выдавать ошибку при обращении к неинициализированным элементам enum

Изменения в распространении smart cast в K2

Проблема: KTLC-34

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

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

Краткое описание: Компилятор K2 изменяет поведение распространения smart cast, вводя двунаправленное распространение информации о типах для выведенных переменных, например val x = y. Переменные с явно заданным типом, такие как val x: T = y, больше не распространяют информацию о типе, что обеспечивает более строгое соответствие объявленным типам.

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

2.1.0: включить новое поведение

Исправление обработки переопределений свойств-расширений-членов в подклассах Java

Приведение видимости геттеров и сеттеров свойств var, переопределяющих protected val, к единообразию

Повышение уровня диагностики несоответствий nullability в JSpecify до ошибок

Проблема: KTLC-11

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

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

Краткое описание: Несоответствия nullability, связанные с org.jspecify.annotations, например @NonNull, @Nullable и @NullMarked, теперь считаются ошибками, а не предупреждениями. Это обеспечивает более строгую безопасность типов при взаимодействии с Java. Чтобы изменить уровень этих диагностических сообщений, используйте параметр компилятора -Xnullability-annotations.

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

1.6.0: выдавать предупреждения о возможных несоответствиях nullability
1.8.20: расширить предупреждения, включив отдельные аннотации JSpecify, в том числе @Nullable, @NullnessUnspecified, @NullMarked и устаревшие аннотации из org.jspecify.nullness (JSpecify 0.2 и более ранние версии)
2.0.0: добавить поддержку аннотации @NonNull
2.1.0: изменить режим по умолчанию на strict для аннотаций JSpecify, преобразовав предупреждения в ошибки; чтобы переопределить поведение по умолчанию, используйте -Xnullability-annotations=@org.jspecify.annotations:warning или -Xnullability-annotations=@org.jspecify.annotations:ignore

Изменение разрешения перегрузок: при неоднозначности приоритет отдается функциям-расширениям, а не вызовам invoke

Проблема: KTLC-37

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

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

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

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

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

Запрет на возврат nullable-значений из лямбд в SAM-конструкторах функциональных интерфейсов JDK

Проблема: KTLC-42

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

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

Краткое описание: Возврат nullable-значений из лямбд в SAM-конструкторах функциональных интерфейсов JDK теперь приводит к ошибке компиляции, если указанный аргумент типа не допускает null. Это устраняет проблемы, при которых несоответствия nullability могли приводить к исключениям во время выполнения, и обеспечивает более строгую безопасность типов.

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

2.0.0: выдавать предупреждение об устаревании для nullable-возвращаемых значений в SAM-конструкторах функциональных интерфейсов JDK
2.1.0: включить новое поведение по умолчанию

Исправление обработки private-членов, конфликтующих с public-членами в Kotlin/Native

Проблема: KTLC-43

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

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

Краткое описание: В Kotlin/Native private-члены больше не переопределяют и не конфликтуют с public-членами суперкласса. Поведение приведено в соответствие с Kotlin/JVM. Это устраняет несоответствия при разрешении переопределений и исключает неожиданное поведение, вызванное раздельной компиляцией.

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

2.1.0: private-функции и свойства в Kotlin/Native больше не переопределяют и не затрагивают public-члены суперкласса; поведение приведено в соответствие с поведением JVM

Запрет на доступ к private-функциям-операторам из public inline-функций

Запрет на передачу недопустимых аргументов инвариантным параметрам с аннотацией @UnsafeVariance

Выдача ошибок nullability для nullable-аргументов с уровнем ошибки у типов Java с уровнем предупреждения

Проблема: KTLC-100

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

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

Краткое описание: Теперь компилятор обнаруживает несоответствия nullability в методах Java, где nullable-тип с уровнем предупреждения содержит аргументы типа с более строгим уровнем nullability — уровнем ошибки. Это позволяет правильно сообщать об ошибках в аргументах типа, которые ранее игнорировались.

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

2.0.0: выдавать предупреждение об устаревании при несоответствиях nullability в методах Java с более строгими аргументами типа
2.1.0: повысить уровень предупреждения до ошибки

Выдача сообщений о неявном использовании недоступных типов

Проблема: KTLC-3

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

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

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

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

2.0.0: выдавать предупреждения для литералов функций с параметрами или получателями недоступных негeneric-типов, а также для типов с недоступными аргументами типа; выдавать ошибки для литералов функций с параметрами или получателями недоступных generic-типов и для типов с недоступными generic-аргументами типа в определенных случаях
2.1.0: повысить уровень предупреждений до ошибок для литералов функций с параметрами и получателями недоступных негeneric-типов
2.2.0: повысить уровень предупреждений до ошибок для типов с недоступными аргументами типа

Стандартная библиотека

Устаревание функций преобразования регистра для Char и String, зависящих от локали

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

Компонент: kotlin-stdlib

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

Краткое описание: Среди прочих API стандартной библиотеки Kotlin устарели функции преобразования регистра для Char и String, зависящие от локали, например Char.toUpperCase() и String.toLowerCase(). Замените их альтернативами, не зависящими от локали, например String.lowercase(), или явно укажите локаль для поведения, зависящего от локали, например String.lowercase(Locale.getDefault()).

Полный список устаревших API стандартной библиотеки Kotlin в Kotlin 2.1.0 см. в разделе KT-71628.

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

1.4.30: представлены экспериментальные альтернативы, не зависящие от локали
1.5.0: функции преобразования регистра, зависящие от локали, помечены как устаревшие с предупреждением
2.1.0: предупреждение повышено до ошибки

Удаление артефакта JAR kotlin-stdlib-common

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

Компонент: kotlin-stdlib

Тип несовместимого изменения: бинарная совместимость

Краткое описание: Артефакт kotlin-stdlib-common.jar, ранее использовавшийся для метаданных объявлений в устаревшем формате мультиплатформенных проектов, признан устаревшим и заменен файлами .klib — стандартным форматом метаданных общих объявлений в мультиплатформенных проектах. Это изменение не затрагивает основные артефакты kotlin-stdlib.jar и kotlin-stdlib-all.jar.

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

2.1.0: артефакт kotlin-stdlib-common.jar объявлен устаревшим и удален

Устаревание appendln() в пользу appendLine()

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

Компонент: kotlin-stdlib

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

Краткое описание: API Kotlin/Native, связанные с заморозкой и ранее помеченные аннотацией @FreezingIsDeprecated, теперь признаны устаревшими. Это связано с появлением нового менеджера памяти, который устраняет необходимость замораживать объекты для совместного использования потоками. Подробную информацию о миграции см. в руководстве по миграции Kotlin/Native.

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

1.7.20: API, связанные с заморозкой, помечены как устаревшие с предупреждением
2.1.0: предупреждение повышено до ошибки

Изменение поведения Map.Entry: немедленная ошибка при структурном изменении

Инструменты

Устаревание KotlinCompilationOutput#resourcesDirProvider

Устаревание функции registerKotlinJvmCompileTask(taskName, moduleName)

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

Компонент: Gradle

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

Краткое описание: Функция registerKotlinJvmCompileTask(taskName, moduleName) признана устаревшей в пользу новой функции registerKotlinJvmCompileTask(taskName, compilerOptions, explicitApiMode), которая теперь принимает KotlinJvmCompilerOptions. Это позволяет передать экземпляр compilerOptions, обычно из расширения или цели, со значениями, используемыми в качестве значений по умолчанию для параметров задачи.

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

2.1.0: функция registerKotlinJvmCompileTask(taskName, moduleName) признана устаревшей

Устаревание функции registerKaptGenerateStubsTask(taskName)

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

Компонент: Gradle

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

Краткое описание: Функция registerKaptGenerateStubsTask(taskName) признана устаревшей. Вместо нее используйте новую функцию registerKaptGenerateStubsTask(compileTask, kaptExtension, explicitApiMode). Эта версия позволяет связать значения по умолчанию с соответствующей задачей KotlinJvmCompile, чтобы обе задачи использовали один и тот же набор параметров.

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

2.1.0: функция registerKaptGenerateStubsTask(taskName) признана устаревшей

Устаревание интерфейсов KotlinTopLevelExtension и KotlinTopLevelExtensionConfig

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

Компонент: Gradle

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

Краткое описание: Интерфейсы KotlinTopLevelExtension и KotlinTopLevelExtensionConfig признаны устаревшими в пользу нового интерфейса KotlinTopLevelExtension. Этот интерфейс объединяет KotlinTopLevelExtensionConfig, KotlinTopLevelExtension и KotlinProjectExtension, упрощая иерархию API и предоставляя официальный доступ к инструментарию JVM и свойствам компилятора.

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

2.1.0: интерфейсы KotlinTopLevelExtension и KotlinTopLevelExtensionConfig признаны устаревшими

Удаление kotlin-compiler-embeddable из зависимостей среды выполнения сборки

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

Компонент: Gradle

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

Краткое описание: Зависимость kotlin-compiler-embeddable удалена из среды выполнения Kotlin Gradle Plugin (KGP). Необходимые модули теперь включены непосредственно в артефакты KGP; версия языка Kotlin ограничена версией 2.0 для поддержки совместимости со средой выполнения Gradle Kotlin в версиях ниже 8.2.

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

2.1.0: при использовании kotlin-compiler-embeddable выдается предупреждение
2.2.0: предупреждение повышено до ошибки

Сокрытие символов компилятора в API Kotlin Gradle Plugin

Добавление поддержки нескольких файлов конфигурации стабильности

Удаление устаревших идентификаторов платформенных плагинов

26 мая 2025 г.

© 2010–2026 JetBrains s.r.o. and Kotlin Programming Language contributors
Licensed under the Apache License, Version 2.0.
https://kotlinlang.org/docs/compatibility-guide-21.html

Руководство по совместимости для Kotlin 2.1.x

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

Язык

Удаление версий языка 1.4 и 1.5

Изменение поведения функции typeOf() в Kotlin/Native

Запрет на раскрытие типов через ограничения параметров типа

Запрет на наследование абстрактного свойства var и свойства val с одинаковым именем

Выдача ошибки при обращении к неинициализированным элементам enum

Изменения в распространении smart cast в K2

Исправление обработки переопределений свойств-расширений-членов в подклассах Java

Приведение видимости геттеров и сеттеров свойств var, переопределяющих protected val, к единообразию

Повышение уровня диагностики несоответствий nullability в JSpecify до ошибок

Изменение разрешения перегрузок: при неоднозначности приоритет отдается функциям-расширениям, а не вызовам invoke

Запрет на возврат nullable-значений из лямбд в SAM-конструкторах функциональных интерфейсов JDK

Исправление обработки private-членов, конфликтующих с public-членами в Kotlin/Native

Запрет на доступ к private-функциям-операторам из public inline-функций

Запрет на передачу недопустимых аргументов инвариантным параметрам с аннотацией @UnsafeVariance

Выдача ошибок nullability для nullable-аргументов с уровнем ошибки у типов Java с уровнем предупреждения

Выдача сообщений о неявном использовании недоступных типов

Стандартная библиотека

Устаревание функций преобразования регистра для Char и String, зависящих от локали

Удаление артефакта JAR kotlin-stdlib-common

Устаревание appendln() в пользу appendLine()

Устаревание API, связанных с заморозкой, в Kotlin/Native

Изменение поведения Map.Entry: немедленная ошибка при структурном изменении

Инструменты

Устаревание KotlinCompilationOutput#resourcesDirProvider

Устаревание функции registerKotlinJvmCompileTask(taskName, moduleName)

Устаревание функции registerKaptGenerateStubsTask(taskName)

Устаревание интерфейсов KotlinTopLevelExtension и KotlinTopLevelExtensionConfig

Удаление kotlin-compiler-embeddable из зависимостей среды выполнения сборки

Сокрытие символов компилятора в API Kotlin Gradle Plugin

Добавление поддержки нескольких файлов конфигурации стабильности

Удаление устаревших идентификаторов платформенных плагинов