rust-idioms

Rust Community Rust リファクタリングのベストプラクティス

Rust Community がメンテナンスする、Rust アプリケーション向けの包括的なリファクタリングおよび慣用パターンのガイドです。自動リファクタリングとコード生成の指針となるよう、影響度順に優先順位を付けた 8 カテゴリ、44 のルールを収録しています。

適用するタイミング

以下の場合に、このガイドラインを参照してください。

• 強い型保証を備えた新しい Rust コードを書くとき
• 所有権と借用のパターンをリファクタリングするとき
• エラーハンドリング戦略を設計するとき
• トレイトとジェネリクスを使用して公開 API を作成するとき
• モジュールを整理し、可視性を制御するとき

優先度別のルールカテゴリ

優先度	カテゴリ	影響度	プレフィックス
1	型安全性と Newtype パターン	CRITICAL	type-
2	所有権と借用	CRITICAL	own-
3	エラーハンドリングパターン	HIGH	err-
4	API 設計とトレイト	HIGH	api-
5	モジュールと可視性	MEDIUM-HIGH	mod-
6	変換トレイト	MEDIUM	conv-
7	慣用パターン	MEDIUM	idiom-
8	イテレーターとコレクション	LOW-MEDIUM	iter-

クイックリファレンス

1. 型安全性と Newtype パターン（CRITICAL）

• type-newtype-units - 単位の安全性に Newtype パターンを使用する
• type-newtype-invariants - Newtype のコンストラクターに不変条件をエンコードする
• type-non-exhaustive-enums - 拡張可能な列挙型には non-exhaustive を使用する
• type-phantom-data - 型レベルの状態に PhantomData を使用する
• type-strong-typing-strings - 文字列型に依存した API を強い型に置き換える
• type-builder-required-fields - 必須フィールドには typestate ビルダーを使用する

2. 所有権と借用（CRITICAL）

• own-prefer-borrowing - パラメーターでは所有権より借用を優先する
• own-cow-conditional-clone - 条件付きの所有権には Cow を使用する
• own-accept-borrowed-types - 所有された参照より借用型を受け入れる
• own-return-owned-for-flexibility - 呼び出し側の柔軟性を高めるため、所有型を返す
• own-avoid-unnecessary-clone - 不要な clone 呼び出しを避ける
• own-lifetime-elision - ライフタイム省略のルールを活用する

3. エラーハンドリングパターン（HIGH）

• err-use-result-not-panic - 回復可能なエラーには panic! ではなく Result を使用する
• err-thiserror-for-libraries - ライブラリのエラー型には thiserror を使用する
• err-anyhow-for-applications - アプリケーションのエラーハンドリングには anyhow を使用する
• err-question-mark-propagation - エラー伝播には疑問符演算子を使用する
• err-option-for-absence - 値がないことを示すには、番兵値ではなく Option を使用する

4. API 設計とトレイト（HIGH）

• api-derive-common-traits - 公開型には一般的なトレイトを derive する
• api-impl-standard-traits - 使いやすい API のために標準トレイトを実装する
• api-generic-bounds - ジェネリックの柔軟性を高めるためにトレイト境界を使用する
• api-sealed-traits - 外部からの実装を防ぐには sealed trait を使用する
• api-builder-pattern - 複雑な構築にはビルダーパターンを使用する
• api-extension-traits - 外部型にメソッドを追加するには拡張トレイトを使用する

5. モジュールと可視性（中〜高）

• mod-minimize-pub-api - 公開 API の範囲を最小限に抑える
• mod-pub-use-reexports - モジュールをすっきり再エクスポートするために pub use を使う
• mod-split-large-modules - 大きなモジュールをサブモジュールに分割する
• mod-crate-prefix-imports - 内部インポートには crate:: プレフィックスを使う
• mod-tests-submodule - ユニットテストには tests サブモジュールを使う

6. 変換トレイト（中）

• conv-impl-from-not-into - Into ではなく From を実装する
• conv-asref-for-flexibility - 文字列パラメーターを柔軟に扱うために AsRef を受け入れる
• conv-impl-deref-for-newtypes - newtype に透過的にアクセスできるよう Deref を実装する
• conv-tryfrom-for-fallible - 失敗する可能性のある変換には TryFrom を使う
• conv-inner-function-pattern - モノモーフィゼーションを減らすために内部関数パターンを使う

7. 慣用的なパターン（中）

• idiom-default-trait - 引数なしの new() の代わりに Default を実装する
• idiom-constructor-naming - コンストラクターの命名規則に従う
• idiom-let-else - パターンマッチに失敗したときの早期リターンには let-else を使う
• idiom-struct-update-syntax - 一部の値を上書きするには構造体更新構文を使う
• idiom-destructuring-assignment - 複数の戻り値やフィールドへのアクセスには分配を使う
• idiom-match-guards - 複雑な条件には match ガードを使う

8. イテレーターとコレクション（低〜中）

• iter-prefer-iterators-over-loops - 手動ループよりイテレーターメソッドを優先する
• iter-use-collect-turbofish - collect の型を明示するにはターボフィッシュを使う
• iter-filter-map-combined - フィルターと変換を組み合わせるには filter_map を使う
• iter-avoid-collect-then-iterate - collect してからイテレートするのは避ける
• iter-enumerate-for-indices - 手動でインデックスを追跡する代わりに enumerate を使う

使用方法

詳しい説明とコード例については、各リファレンスファイルをお読みください。

• セクションの定義 - カテゴリー構成と影響レベル
• ルールテンプレート - 新しいルールを追加するためのテンプレート

コンパイル済み完全版ドキュメント

単一ファイルの包括的なガイドについては、AGENTS.mdをご覧ください。