Kotlin 1.9.x 互換性ガイド
「言語をモダンに保つ」と「快適なアップデート」は、Kotlin 言語設計における基本的な原則の一つです。前者は言語の進化を妨げる構文は削除されるべきであるという原則で、後者はコードの移行をできるだけスムーズにするために、その削除を事前に十分に周知すべきであるという原則です。
言語の変更の多くは、アップデートの変更ログやコンパイラの警告など、他のチャネルを通じてすでに発表されていますが、このドキュメントではそれらをすべて要約し、Kotlin 1.8 から Kotlin 1.9 への移行に関する完全なリファレンスを提供します。
基本用語
このドキュメントでは、いくつかの種類の互換性を紹介します：
- ソース（source）: ソース互換性のない変更は、以前は正常にコンパイルできていた（エラーや警告が出ていなかった）コードがコンパイルできなくなる変更です。
- バイナリ（binary）: 2つのバイナリアーティファクトを入れ替えても、ロードエラーやリンケージエラーが発生しない場合、それらはバイナリ互換であると言います。
- 振る舞い（behavioral）: 変更を適用する前後で、同じプログラムが異なる動作を示す場合、その変更は振る舞い互換性がないと言います。
これらの定義は純粋な Kotlin に対してのみ適用されることに注意してください。他の言語の観点（例：Java）からの Kotlin コードの互換性は、このドキュメントの範囲外です。
言語
言語バージョン 1.3 の削除
イシュー: KT-61111
コンポーネント: 言語コア
互換性のない変更の種類: ソース
概要: Kotlin 1.9 では言語バージョン 1.9 が導入され、言語バージョン 1.3 のサポートが削除されます。
非推奨化サイクル:
- 1.6.0: 警告を表示
- 1.9.0: 警告をエラーに引き上げる
スーパーインターフェース型が関数リテラルの場合のスーパーコンストラクタ呼び出しを禁止
イシュー: KT-46344
コンポーネント: 言語コア
互換性のない変更の種類: ソース
概要: インターフェースが関数リテラル型を継承している場合、そのようなコンストラクタは存在しないため、Kotlin 1.9 ではスーパーコンストラクタの呼び出しを禁止します。
非推奨化サイクル:
- 1.7.0: 警告を表示（プログレッシブモードではエラー）
- 1.9.0: 警告をエラーに引き上げる
アノテーションパラメータ型における循環を禁止
イシュー: KT-47932
コンポーネント: 言語コア
互換性のない変更の種類: ソース
概要: Kotlin 1.9 では、直接的または間接的に、アノテーションの型をそのパラメータ型の一つとして使用することを禁止します。これにより循環の発生を防ぎます。 ただし、アノテーション型の
Arrayまたはvarargであるパラメータ型を持つことは許可されます。非推奨化サイクル:
- 1.7.0: アノテーションパラメータ型の循環に対して警告を表示（プログレッシブモードではエラー）
- 1.9.0: 警告をエラーに引き上げる。一時的に 1.9 以前の動作に戻すには
-XXLanguage:-ProhibitCyclesInAnnotationsを使用可能。
引数のない関数型での @ExtensionFunctionType アノテーションの使用を禁止
イシュー: KT-43527
コンポーネント: 言語コア
互換性のない変更の種類: ソース
概要: Kotlin 1.9 では、引数のない関数型、または関数型ではない型に対して
@ExtensionFunctionTypeアノテーションを使用することを禁止します。非推奨化サイクル:
- 1.7.0: 関数型ではない型のアノテーションに対しては警告を表示し、関数型である型のアノテーションに対してはエラーを表示
- 1.9.0: 関数型に対する警告をエラーに引き上げる
代入時の Java フィールド型の不一致を禁止
イシュー: KT-48994
コンポーネント: Kotlin/JVM
互換性のない変更の種類: ソース
概要: Kotlin 1.9 では、Java フィールドに代入される値の型が、Java フィールドの射影された型（projected type）と一致しないことを検出した場合、コンパイラエラーを報告します。
非推奨化サイクル:
- 1.6.0: 射影された Java フィールド型が代入された値の型と一致しない場合に警告を表示（プログレッシブモードではエラー）
- 1.9.0: 警告をエラーに引き上げる。一時的に 1.9 以前の動作に戻すには
-XXLanguage:-RefineTypeCheckingOnAssignmentsToJavaFieldsを使用可能。
プラットフォーム型の null 許容性アサーション例外におけるソースコードの抜粋を廃止
イシュー: KT-57570
コンポーネント: Kotlin/JVM
互換性のない変更の種類: 振る舞い
概要: Kotlin 1.9 では、式の null チェックによる例外メッセージにソースコードの抜粋が含まれなくなります。代わりに、メソッド名またはフィールド名が表示されます。 式がメソッドまたはフィールドでない場合、メッセージに追加情報は提供されません。
非推奨化サイクル:
- < 1.9.0: 式の null チェックによって生成される例外メッセージにソースコードの抜粋が含まれる
- 1.9.0: 式の null チェックによって生成される例外メッセージにメソッド名またはフィールド名のみが含まれる。一時的に 1.9 以前の動作に戻すには
-XXLanguage:-NoSourceCodeInNotNullAssertionExceptionsを使用可能。
抽象スーパークラスメンバへのスーパー呼び出しの委譲を禁止
イシュー: KT-45508, KT-49017, KT-38078
コンポーネント: 言語コア
互換性のない変更の種類: ソース
概要: スーパーインターフェースにデフォルト実装がある場合でも、明示的または暗黙的なスーパー呼び出しがスーパークラスの「抽象」メンバに委譲される場合、Kotlin はコンパイルエラーを報告します。
非推奨化サイクル:
- 1.5.20: すべての抽象メンバをオーバーライドしていない非抽象クラスが使用された場合に警告を導入
- 1.7.0: スーパー呼び出しが実際にはスーパークラスの抽象メンバにアクセスしている場合に警告を表示
- 1.7.0:
-Xjvm-default=allまたは-Xjvm-default=all-compatibility互換モードが有効な場合、影響を受けるすべてのケースでエラーを表示。プログレッシブモードでエラーを表示。- 1.8.0: スーパークラスのオーバーライドされていない抽象メソッドを持つ具象クラスを宣言した場合、およびスーパークラスで
Anyのメソッドが抽象としてオーバーライドされている場合のスーパー呼び出しに対してエラーを表示- 1.9.0: スーパークラスの抽象メソッドへの明示的なスーパー呼び出しを含む、影響を受けるすべてのケースでエラーを表示
引数付き when における紛らわしい文法の非推奨化
イシュー: KT-48385
コンポーネント: 言語コア
互換性のない変更の種類: ソース
概要: Kotlin 1.6 では、
when条件式におけるいくつかの紛らわしい文法構造を非推奨にしました。非推奨化サイクル:
- 1.6.20: 該当する式に非推奨警告を導入
- 1.8.0: この警告をエラーに引き上げる。一時的に 1.8 以前の動作に戻すには
-XXLanguage:-ProhibitConfusingSyntaxInWhenBranchesを使用可能。- >= 2.1: 非推奨となった構造の一部を新しい言語機能のために転用
異なる数値型間の暗黙的な型変換の防止
イシュー: KT-48645
コンポーネント: Kotlin/JVM
互換性のない変更の種類: 振る舞い
概要: Kotlin は、意味的にその型へのダウンキャストのみが必要な箇所で、数値をプリミティブ数値型へ自動的に変換することを避けるようになります。
非推奨化サイクル:
- < 1.5.30: 影響を受けるすべてのケースで古い動作を適用
- 1.5.30: 生成されたプロパティデリゲートアクセサでのダウンキャスト動作を修正。一時的に 1.5.30 修正前の動作に戻すには
-Xuse-old-backendを使用可能。- >= 2.0: 影響を受ける他のケースでのダウンキャスト動作を修正
ジェネリック型エイリアスの使用における上限境界違反の禁止（型エイリアス先の型の型引数の型引数として型パラメータが使用されている場合）
イシュー: KT-54066
コンポーネント: 言語コア
互換性のない変更の種類: ソース
概要: 型エイリアスの型パラメータがエイリアス先の型の型引数の型引数として使用されている場合（例：
typealias Alias<T> = Base<List<T>>）、エイリアス先の型の対応する型パラメータの上限境界制限に違反する型引数を持つ型エイリアスの使用を禁止します。非推奨化サイクル:
- 1.8.0: ジェネリック型エイリアスの使用が、エイリアス先の型の対応する型パラメータの上限境界制約に違反する型引数を持つ場合に警告を表示
- 2.0.0: 警告をエラーに引き上げる
公開シグネチャでローカル型を近似する際の null 許容性の維持
イシュー: KT-53982
コンポーネント: 言語コア
互換性のない変更の種類: ソース、バイナリ
概要: 戻り値型が明示的に指定されていない式形式の関数からローカル型や匿名型が返される際、Kotlin コンパイラはその型の既知のスーパークラスを使用して戻り値型を推論（または近似）します。この際、実際には null 値が返される可能性があるにもかかわらず、コンパイラが null 非許容型を推論してしまうことがありました。
非推奨化サイクル:
- 1.8.0: フレキシブル型をフレキシブルなスーパークラスで近似する
- 1.8.0: 宣言が null 許容であるべきなのに null 非許容型として推論される場合に警告を表示し、ユーザーに型を明示的に指定するよう促す
- 2.0.0: null 許容型を null 許容なスーパークラスで近似する。一時的に 2.0 以前の動作に戻すには
-XXLanguage:-KeepNullabilityWhenApproximatingLocalTypeを使用可能。
オーバーライドを通じて非推奨状態を伝播させない
イシュー: KT-47902
コンポーネント: 言語コア
互換性のない変更の種類: ソース
概要: Kotlin 1.9 では、スーパークラスの非推奨メンバからサブクラスのオーバーライドメンバへ非推奨状態を伝播させなくなります。これにより、スーパークラスのメンバを非推奨にしつつ、サブクラスでは非推奨ではない状態にする明示的なメカニズムが提供されます。
非推奨化サイクル:
- 1.6.20: 将来の動作変更に関するメッセージと、この警告を抑制するか、非推奨メンバのオーバーライドに明示的に
@Deprecatedアノテーションを記述することを促す警告を表示- 1.9.0: オーバーライドされたメンバへの非推奨ステータスの伝播を停止。この変更はプログレッシブモードでも即座に有効になります。
アノテーションクラスのパラメータ宣言以外でのコレクションリテラルの使用を禁止
イシュー: KT-39041
コンポーネント: 言語コア
互換性のない変更の種類: ソース
概要: Kotlin ではコレクションリテラルの使用が制限されており、アノテーションクラスのパラメータへの配列の受け渡しや、これらのパラメータのデフォルト値の指定に使用できます。 しかし、それ以外にも、アノテーションクラス内部（例えばネストされたオブジェクト内など）であればどこでもコレクションリテラルの使用が許可されていました。Kotlin 1.9 では、アノテーションクラス内のパラメータのデフォルト値以外でのコレクションリテラルの使用を禁止します。
非推奨化サイクル:
- 1.7.0: アノテーションクラス内のネストされたオブジェクトでの配列リテラルに対して警告を表示（プログレッシブモードではエラー）
- 1.9.0: 警告をエラーに引き上げる
デフォルト値の式におけるパラメータの前方参照を禁止
イシュー: KT-25694
コンポーネント: 言語コア
互換性のない変更の種類: ソース
概要: Kotlin 1.9 では、他のパラメータのデフォルト値式におけるパラメータの前方参照を禁止します。これにより、デフォルト値の式でパラメータがアクセスされるときには、そのパラメータに関数に渡された値か、自身のデフォルト値の式によって初期化された値が既に存在することが保証されます。
非推奨化サイクル:
- 1.7.0: デフォルト値を持つパラメータが、それより前に定義された別のパラメータのデフォルト値の中で参照されている場合に警告を表示（プログレッシブモードではエラー）
- 1.9.0: 警告をエラーに引き上げる。一時的に 1.9 以前の動作に戻すには
-XXLanguage:-ProhibitIllegalValueParameterUsageInDefaultArgumentsを使用可能。
インライン関数パラメータに対する拡張呼び出しを禁止
イシュー: KT-52502
コンポーネント: 言語コア
互換性のない変更の種類: ソース
概要: Kotlin では、インライン関数パラメータをレシーバとして別のインライン関数に渡すことが許可されていましたが、そのようなコードをコンパイルすると常にコンパイラ例外が発生していました。 Kotlin 1.9 ではこれを禁止し、コンパイラをクラッシュさせる代わりにエラーを報告するようにします。
非推奨化サイクル:
- 1.7.20: インライン関数パラメータに対するインライン拡張呼び出しについて警告を表示（プログレッシブモードではエラー）
- 1.9.0: 警告をエラーに引き上げる
匿名関数の引数を持つ suspend という名前の infix 関数の呼び出しを禁止
イシュー: KT-49264
コンポーネント: 言語コア
互換性のない変更の種類: ソース
概要: Kotlin 1.9 では、匿名関数リテラルとして渡される関数型の単一引数を持つ、
suspendという名前の infix 関数の呼び出しを許可しなくなります。非推奨化サイクル:
- 1.7.20: 匿名関数リテラルを伴う suspend infix 呼び出しに対して警告を表示
- 1.9.0: 警告をエラーに引き上げる。一時的に 1.9 以前の動作に戻すには
-XXLanguage:-ModifierNonBuiltinSuspendFunErrorを使用可能。- TODO: パーサーによる
suspend funトークンシーケンスの解釈方法を変更
内部クラスでキャプチャされた型パラメータを変異性に反して使用することを禁止
イシュー: KT-50947
コンポーネント: 言語コア
互換性のない変更の種類: ソース
概要: Kotlin 1.9 では、
inまたはout変異性を持つ外部クラスの型パラメータを、その型パラメータの宣言された変異性に違反する位置で内部クラス内で使用することを禁止します。非推奨化サイクル:
- 1.7.0: 外部クラスの型パラメータの使用位置がそのパラメータの変異性規則に違反している場合に警告を表示（プログレッシブモードではエラー）
- 1.9.0: 警告をエラーに引き上げる。一時的に 1.9 以前の動作に戻すには
-XXLanguage:-ReportTypeVarianceConflictOnQualifierArgumentsを使用可能。
複合代入演算子内での明示的な戻り値型のない関数の再帰呼び出しを禁止
イシュー: KT-48546
コンポーネント: 言語コア
互換性のない変更の種類: ソース
概要: Kotlin 1.9 では、関数の本体内の他の式と同様に、複合代入演算子の引数内で明示的に戻り値型が指定されていない関数を呼び出すことを禁止します。
非推奨化サイクル:
- 1.7.0: 明示的に指定された戻り値型のない関数が、その関数の本体内の複合代入演算子の引数で再帰的に呼び出された場合に警告を表示（プログレッシブモードではエラー）
- 1.9.0: 警告をエラーに引き上げる
@NotNull T が期待され、null 許容境界を持つ Kotlin ジェネリックパラメータが渡される不健全な呼び出しを禁止
イシュー: KT-36770
コンポーネント: Kotlin/JVM
互換性のない変更の種類: ソース
概要: Kotlin 1.9 では、Java メソッドの
@NotNullアノテーションが付いたパラメータに対して、null 許容の可能性があるジェネリック型の値が渡されるメソッド呼び出しを禁止します。非推奨化サイクル:
- 1.5.20: null 非許容型が期待される箇所に、制約のないジェネリック型パラメータが渡された場合に警告を表示
- 1.9.0: 上記の警告の代わりに型不一致エラーを報告。一時的に 1.8 以前の動作に戻すには
-XXLanguage:-ProhibitUsingNullableTypeParameterAgainstNotNullAnnotatedを使用可能。
enum クラスのエントリ初期化子からその enum のコンパニオンメンバへのアクセスを禁止
イシュー: KT-49110
コンポーネント: 言語コア
互換性のない変更の種類: ソース
概要: Kotlin 1.9 では、enum エントリ初期化子から enum のコンパニオンオブジェクトへのあらゆる種類のアクセスを禁止します。
非推奨化サイクル:
- 1.6.20: そのようなコンパニオンメンバへのアクセスに対して警告を表示（プログレッシブモードではエラー）
- 1.9.0: 警告をエラーに引き上げる。一時的に 1.8 以前の動作に戻すには
-XXLanguage:-ProhibitAccessToEnumCompanionMembersInEnumConstructorCallを使用可能。
Enum.declaringClass 合成プロパティの非推奨化と削除
イシュー: KT-49653
コンポーネント: Kotlin/JVM
互換性のない変更の種類: ソース
概要: Kotlin では、基底となる Java クラス
java.lang.EnumのメソッドgetDeclaringClass()から生成される合成プロパティdeclaringClassをEnumの値で使用することが許可されていました（このメソッドは Kotlin のEnum型では利用できないにもかかわらず）。Kotlin 1.9 ではこのプロパティの使用を禁止し、代わりに拡張プロパティdeclaringJavaClassへの移行を提案します。非推奨化サイクル:
- 1.7.0:
declaringClassプロパティの使用に対して警告を表示（プログレッシブモードではエラー）し、declaringJavaClass拡張への移行を提案- 1.9.0: 警告をエラーに引き上げる。一時的に 1.9 以前の動作に戻すには
-XXLanguage:-ProhibitEnumDeclaringClassを使用可能。- 2.0.0:
declaringClass合成プロパティを削除
コンパイラオプション -Xjvm-default の enable および compatibility モードの非推奨化
コンポーネント: Kotlin/JVM
互換性のない変更の種類: ソース
概要: Kotlin 1.9 では、
-Xjvm-defaultコンパイラオプションのenableおよびcompatibilityモードの使用を禁止します。非推奨化サイクル:
- 1.6.20:
-Xjvm-defaultコンパイラオプションのenableおよびcompatibilityモードに対して警告を導入- 1.9.0: この警告をエラーに引き上げる
ビルダー推論コンテキストにおいて型変数を上限境界へ暗黙的に推論することを禁止
イシュー: KT-47986
コンポーネント: 言語コア
互換性のない変更の種類: ソース
概要: Kotlin 2.0 では、ビルダー推論ラムダ関数のスコープにおいて、利用サイトの型情報がない場合に型変数を対応する型パラメータの上限境界へ推論することを、他のコンテキストと同様に禁止します。
非推奨化サイクル:
- 1.7.20: 利用サイトの型情報がない場合に型パラメータが宣言された上限境界に推論されると警告を表示（プログレッシブモードではエラー）
- 2.0.0: 警告をエラーに引き上げる
標準ライブラリ
Range/Progression が Collection を実装し始めることによるオーバーロード解決の変更の可能性についての警告
イシュー: KT-49276
コンポーネント: 言語コア / kotlin-stdlib
互換性のない変更の種類: ソース
概要: Kotlin 1.9 では、標準の progression とそれらを継承する具体的な range に
Collectionインターフェースを実装する予定です。これにより、あるメソッドに要素を受け取るオーバーロードとコレクションを受け取るオーバーロードの 2 つがある場合、オーバーロード解決で異なるものが選択される可能性があります。Kotlin は、そのようなオーバーロードされたメソッドが range または progression の引数で呼び出されたときに警告またはエラーを報告することで、この状況を可視化します。非推奨化サイクル:
- 1.6.20: 標準の progression またはその range 継承者を引数としてオーバーロードされたメソッドが呼び出され、将来的に
Collectionインターフェースを実装することで別のオーバーロードが選択されることになる場合に警告を表示- 1.8.0: この警告をエラーに引き上げる
- 2.1.0: エラーの報告を停止し、progression に
Collectionインターフェースを実装することで、影響を受けるケースでのオーバーロード解決の結果を変更
kotlin.dom および kotlin.browser パッケージの宣言を kotlinx.* へ移行
イシュー: KT-39330
コンポーネント: kotlin-stdlib (JS)
互換性のない変更の種類: ソース
概要:
kotlin.domおよびkotlin.browserパッケージの宣言は、stdlib からの切り離しの準備として、対応するkotlinx.*パッケージに移動されました。非推奨化サイクル:
- 1.4.0:
kotlinx.domおよびkotlinx.browserパッケージに代替 API を導入- 1.4.0:
kotlin.domおよびkotlin.browserパッケージの API を非推奨にし、上記の新しい API を代替として提案- 1.6.0: 非推奨レベルをエラーに引き上げる
- 1.8.20: JS-IR ターゲットの stdlib から非推奨の関数を削除
- >= 2.0: kotlinx.* パッケージの API を別のライブラリに移動
一部の JS 専用 API の非推奨化
イシュー: KT-48587
コンポーネント: kotlin-stdlib (JS)
互換性のない変更の種類: ソース
概要: stdlib 内の多数の JS 専用関数が削除のために非推奨になりました。これには、
String.concat(String)、String.match(regex: String)、String.matches(regex: String)、および比較関数を受け取る配列のsort関数（例：Array<out T>.sort(comparison: (a: T, b: T) -> Int)）が含まれます。非推奨化サイクル:
- 1.6.0: 該当する関数を警告付きで非推奨にする
- 1.9.0: 非推奨レベルをエラーに引き上げる
- >=2.0: 公開 API から非推奨の関数を削除
ツール
Gradle 設定から enableEndorsedLibs フラグを削除
イシュー: KT-54098
コンポーネント: Gradle
互換性のない変更の種類: ソース
概要: Gradle 設定において
enableEndorsedLibsフラグはサポートされなくなりました。非推奨化サイクル:
- < 1.9.0: Gradle 設定で
enableEndorsedLibsフラグをサポート- 1.9.0: Gradle 設定で
enableEndorsedLibsフラグをサポートしない
Gradle コンベンションの削除
イシュー: KT-52976
コンポーネント: Gradle
互換性のない変更の種類: ソース
概要: Gradle コンベンション（conventions）は Gradle 7.1 で非推奨になり、Gradle 8 で削除されました。
非推奨化サイクル:
- 1.7.20: Gradle コンベンションを非推奨化
- 1.9.0: Gradle コンベンションを削除
KotlinCompile タスクの classpath プロパティの削除
イシュー: KT-53748
コンポーネント: Gradle
互換性のない変更の種類: ソース
概要:
KotlinCompileタスクのclasspathプロパティが削除されました。非推奨化サイクル:
- 1.7.0:
classpathプロパティを非推奨化- 1.8.0: 非推奨レベルをエラーに引き上げる
- 1.9.0: 公開 API から非推奨の関数を削除
kotlin.internal.single.build.metrics.file プロパティの非推奨化
イシュー: KT-53357
コンポーネント: Gradle
互換性のない変更の種類: ソース
概要: ビルドレポート用に単一のファイルを定義するために使用される
kotlin.internal.single.build.metrics.fileプロパティを非推奨にします。 代わりにkotlin.build.report.output=single_fileと共にkotlin.build.report.single_fileプロパティを使用してください。非推奨化サイクル:
- 1.8.0: 非推奨レベルを警告に引き上げる
- >= 1.9: プロパティを削除