互換性
このドキュメントでは、バージョン 1.0.0 以降の kotlinx.coroutines ライブラリの互換性ポリシーと、互換性固有のアノテーションのセマンティクスについて説明します。
パブリックAPIの種類
kotlinx.coroutines のパブリックAPIには、安定（stable）、実験的（experimental）、廃止予定（obsolete）、内部（internal）、非推奨（deprecated）の5つの種類があります。 安定APIを除くすべてのパブリックAPIには、対応するアノテーションが付けられています。
実験的API (Experimental API)
実験的APIは @ExperimentalCoroutinesApi アノテーションでマークされています。 APIの設計に未解決の懸念事項があり、最終的にAPIのセマンティクスの変更や非推奨化につながる可能性がある場合、そのAPIは実験的としてマークされます。
デフォルトでは、ほとんどの新しいAPIは実験的としてマークされ、新たな問題が発生しなければ、その後のメジャーリリースのいずれかで安定版になります。 問題が発生した場合は、ABIを変更せずにセマンティクスを修正するか、あるいは非推奨化サイクルに入ります。
実験的APIの使用が危険な場合：
kotlinx.coroutinesに依存するライブラリを作成しており、そのライブラリの安定したAPIの中で実験的なコルーチンAPIを使用したい場合。ライブラリの最終ユーザーがkotlinx.coroutinesのバージョンを更新した際に、実験的APIのセマンティクスがわずかに異なっていると、予期しない結果を招く可能性があります。- アプリケーションのコアインフラストラクチャを実験的APIを中心に構築したい場合。
FlowプレビューAPI (Flow preview API)
すべての Flow 関連のAPIは @FlowPreview アノテーションでマークされています。 このアノテーションは、Flow APIがプレビュー状態であることを示しています。 プレビュー機能については、バイナリ、ソース、およびセマンティクスの互換性を含め、リリース間での互換性は保証されません。
プレビューAPIの使用が危険な場合：
- ライブラリやフレームワークを作成しており、安定したリリースや安定したAPIの中で Flow APIを使用したい場合。
- アプリケーションのコアインフラストラクチャで Flow を使用したい場合。
- Flow を「使い捨て」のソリューションとして使用したいが、
kotlinx.coroutinesのアップデートに伴う追加のメンテナンスコストを許容できない場合。
Obsolete API (廃止予定のAPI)
Obsolete APIは @ObsoleteCoroutinesApi アノテーションでマークされています。 Obsolete APIは実験的APIに似ていますが、すでに重大な設計上の欠陥があることが判明しており、潜在的な代替手段が存在する（ただし、代替手段はまだ実装されていない）ものを指します。
このAPIのセマンティクスが変更されることはありませんが、代替手段の準備ができ次第、非推奨化サイクルに入ります。
内部API (Internal API)
内部APIは @InternalCoroutinesApi でマークされているか、kotlinx.coroutines.internal パッケージの一部となっています。 このAPIには安定性の保証はなく、将来のリリースで変更または削除される可能性があります。 どうしても内部APIを使用せざるを得ない場合は、イシュートラッカーに報告してください。
安定API (Stable API)
安定APIは、そのABIとドキュメント化されたセマンティクスが維持されることが保証されています。万が一、修正不可能な設計上の欠陥が発見された場合、そのAPIは非推奨化サイクルに入りますが、可能な限りバイナリ互換性は維持されます。
非推奨化サイクル (Deprecation cycle)
APIが非推奨（deprecated）になると、複数のステージを経て廃止されます。各ステージの間には少なくとも1つのメジャーリリースが挟まれます。
- 機能がコンパイル警告とともに非推奨になります。ほとんどの場合、IntelliJ IDEAの機能を利用して非推奨箇所の移行を自動化できるよう、適切な代替手段（および対応する
replaceWith宣言）が提供されます。 - 非推奨レベルが
errorまたはhiddenに引き上げられます。ABIにはまだ存在していますが、非推奨のAPIに対して新しいコードをコンパイルすることはできなくなります。 - APIが完全に削除されます。削除しないよう最善の努力を払い、現時点でAPIを削除する計画はありませんが、セキュリティホールなどの予期せぬ問題に備えて、この選択肢は残されています。
アノテーション付きAPIの使用
すべてのAPIアノテーションは kotlin.Experimental です。 これは、実験的または廃止予定のAPIを使用していることに対してコンパイル警告を出すためです。 警告は、特定の呼び出し箇所に対してプログラムで無効にするか、モジュール全体に対してグローバルに無効にすることができます。
プログラムによる指定
特定の呼び出し箇所で警告を無効にするには、OptIn アノテーションを使用します：
@OptIn(ExperimentalCoroutinesApi::class) // 実験的なコルーチンAPIに関する警告を無効にします
fun experimentalApiUsage() {
someKotlinxCoroutinesExperimentalMethod()
}Gradle
Gradleプロジェクトでは、build.gradle ファイルでコンパイラフラグを渡すことで警告を無効にできます：
tasks.withType(org.jetbrains.kotlin.gradle.tasks.AbstractKotlinCompile).all {
kotlinOptions.freeCompilerArgs += ["-Xuse-experimental=kotlinx.coroutines.ExperimentalCoroutinesApi"]
}Maven
Mavenプロジェクトでは、pom.xml ファイルでコンパイラフラグを渡すことで警告を無効にできます：
<plugin>
<artifactId>kotlin-maven-plugin</artifactId>
<groupId>org.jetbrains.kotlin</groupId>
... 既存の設定 ...
<configuration>
<args>
<arg>-Xuse-experimental=kotlinx.coroutines.ExperimentalCoroutinesApi</arg>
</args>
</configuration>
</plugin>