rust-trait-api-design

Rust Trait API 設計

このスキルは、必要に応じて Rust API をジェネリックにし、シンプルにできる場合は具体的な型を使い、動的ディスパッチが設計の一部である場合はオブジェクトセーフにするために使用します。呼び出し側と実装者が理解できる、最小限の能力コントラクトを目指します。

基本的なワークフロー

1. API が振る舞いを消費、借用、返却、保持、またはディスパッチするかを特定します。
2. ローカルコードでは具体的な型から始めます。少なくとも 2 つの呼び出し元または実装で柔軟性が必要な場合にのみ、汎用化します。
3. コンパイル時のポリモーフィズムとインライン化にはジェネリック境界を使用します。異種の値、プラグインのような拡張ポイント、または実行時ディスパッチには dyn Trait を使用します。
4. 境界は必要な箇所に配置します。境界が長い場合や関連型を含む場合は、where 句を優先します。
5. トレイトを下流で実装できるようにするかを判断します。不変条件を外部から実装できないようにする必要がある場合は、トレイトをシールするか、フィールドを非公開にするか、コンストラクターを使用します。
6. 標準の変換トレイトが要件に完全に合う場合は、それを使用します。From、TryFrom、AsRef、AsMut、Borrow、ToOwned、Cow を確認する前に、独自の変換トレイトを作らないでください。
7. スキルが想定する方法で将来のユーザーが公開 API を呼び出せることを証明する、コンパイルテスト、単体テスト、または例を追加します。

API 設計ルール

• 呼び出し側が多様な具体型を渡せるようにする場合、パラメーターには impl Trait または名前付きジェネリックを使用します。
• 具体的な戻り値の型を隠す場合は impl Trait を返します。具体的な型が実行時に変わる場合は Box<dyn Trait> を返します。
• 各実装に自然な関連型が 1 つある場合は、関連型を優先します。1 つの実装が複数の対象型をサポートする場合は、ジェネリックなトレイトパラメーターを優先します。
• 失敗しない変換には From、失敗する可能性がある変換には TryFrom を実装します。これらを実装すると、呼び出し側は Into と TryInto を使用できます。
• 参照から参照への低コストな変換には AsRef を使用します。借用形式と所有形式で Eq、Hash、Ord の動作が同等である場合にのみ、Borrow を使用します。
• アルゴリズム上、ビット単位のコピーが必要な場合を除き、Copy 境界は避けます。

トレイトオブジェクトの確認

ジェネリックと dyn Trait のどちらを選ぶか決めるとき、または公開トレイトがオブジェクトセーフのチェックに失敗するときは、references/trait-api-patterns.md を読んでください。

公開トレイトをオブジェクトセーフにする前に、次の点を確認してください。

• メソッドがジェネリック型パラメーターを使用していない。
• メソッドが where Self: Sized で制約されていない限り、Self を返さない。
• 必要に応じて、トレイトオブジェクトで関連型が指定されている。
• オブジェクトが &dyn Trait、Box<dyn Trait>、Arc<dyn Trait + Send + Sync> などのポインターで保持されている。

よくある問題点

• イテレーションだけが必要なのに、公開関数が &Vec<T> を受け取る。
• API が String を受け取り、すぐに &str として借用する。
• API が From ではなく Into を直接実装する。
• トレイトに多くの包括的な境界があるが、それを必要とするのは 1 つのメソッドだけである。
• 実行時ディスパッチが必要だからではなく、ライフタイムがわかりにくいという理由でトレイトオブジェクトを使っている。
• トレイトにおけるネイティブな async fn、trait-variant、またはボックス化されたフューチャーが、ディスパッチと Send の要件により適合するか確認せずに、公開トレイトで async-trait を使用している。