kotlin-api-design

Kotlin API 設計

基本原則

呼び出し側にとって意味が最も明確になる場所に、振る舞い、型、プラットフォームとの境界を配置します。ドメインの言葉とプラットフォームからの独立性を保てる、最小限の公開抽象を使用します。

手順

1. ドメイン概念、その概念を所有する型またはモジュール、そしてそれに依存する必要がある呼び出し側を特定します。
2. 拡張関数、ファクトリー、ヘルパー、サービスレイヤーを追加する前に、関数の所有者を決めます。採用しないものがある場合は、代わりに呼び出し側が使うべき所有者を示します。
3. シールドされた結果を公開マッピングで扱う場合、呼び出し側から見える結果をすべて明示します。サブタイプを隠す包括的な else があれば指摘し、コントラクトが網羅的なままスマートキャストも保持できるよう、サブタイプごとに明示的な分岐を使うことを推奨します。
4. 単一フィールドのドメイン概念は、意味と相互運用性のコントラクトを保つ最小限の型で表現します。
5. 共有コードでは意味を扱い、ネイティブ SDK やプラットフォームの詳細は、インターフェースまたは正当な理由がある場合に限り、狭い範囲の expect/actual 境界の背後に置きます。
6. 以下で選択した判断に対応するリファレンスを読みます。
7. 公開 API がドメインの意図を示し、プラットフォームの詳細が末端に留まり、呼び出し側が明確な所有者のいない便宜的な抽象に依存しなくなった時点で完了です。

トピックの案内

目印	参照先
メンバー、トップレベル、拡張関数、ファクトリー、サービス、レシーバーの選択	関数の所有者
プリミティブ型への過度な依存、1フィールドのドメイン型、@JvmInline value class、データクラス、相互運用性、Compose の安定性	値クラス
ソースセット、プラットフォームサービス、ネイティブ SDK、ファイル、センサー、権限、Compose Multiplatform の相互運用、expect/actual	マルチプラットフォームの境界
分岐、ガード条件の形式、シールドされた結果のマッピング、包括的な else	Kotlin の制御フロー