Cargo Featuresの「地獄」を回避し、型安全なビルドの要塞を築く：マルチターゲット時代の設計黄金律
多くのRustエンジニアが、`Cargo.toml`の`[features]`セクションを単なる「オンオフスイッチ」だと誤解している。しかし、それは大きな間違いだ。フィーチャーフラグは、あなたのコードベースが膨大な組み合わせの爆発（Combinatorial Explosion）を制御するための「コンパイル時型システムの一環」である。
今回は、数百万行規模の複雑なマイクロサービスから、組み込み環境のSDKまでを支えてきた私が、Cargo Featuresを極限まで最適化し、CI/CDパイプラインと同期させるための「戦略的設計」を伝授する。
—
1. Features設計の黄金律：「包含」と「排他」の数学的アプローチ
初心者は`features`をフラットに並べがちだが、大規模プロジェクトでは「論理的階層」と「相互排他」を厳密に定義しなければならない。
包含関係の明示：`[dependencies]`と`[features]`の連鎖
機能を有効にした際、依存関係を自動的に引き込むべきだ。しかし、依存先が肥大化しすぎると、コンパイル時間が指数関数的に増大する。
[features]
基本機能のみ
default = [“std”]
std: 標準ライブラリ利用（No_std対応の分水嶺）
std = [“dep:serde”]
full: すべてのバックエンドを有効化（CI用のメタフィーチャー）
full = [“runtime-tokio”, “runtime-async-std”, “db-postgres”, “db-sqlite”]
依存関係をフィーチャーに紐づけて遅延ロードさせる
[dependencies]
serde = { version = “1.0”, optional = true }
tokio = { version = “1.0”, optional = true }
アーキテクトの視点:
`default`には最小限の依存関係のみを含めよ。ライブラリ開発において`full`をデフォルトにするのは、ユーザーに対する暴力である。バイナリサイズとコンパイル時間の削減こそが、Rustの最大の武器であることを忘れてはならない。
—
2. CI/CDの死角：`–all-features`の罠を突破せよ
多くのチームがCIで`cargo test –all-features`を叩くが、これには致命的な欠陥がある。「排他条件」の検証が漏れるからだ。
例えば、`db-postgres`と`db-sqlite`が同時に有効になってはいけない設計の場合、`–all-features`は単に両方を有効にしてビルドするだけで、意図しないコードの混入（リンクエラーや論理的競合）を見逃す。
推奨されるCI戦略：Matrixテスト
GitHub Actions等で、フィーチャーの組み合わせを直交配列でテストする。
CIワークフローの抜粋
strategy:
matrix:
# 相互排他関係にあるフィーチャーを別々のジョブで検証
include:
- features: “db-postgres,std”
- features: “db-sqlite,std”
- features: “no-std” # ゼロ依存の検証
これにより、各コンビネーションにおける「型安全なビルド」を保証できる。
—
3. Dockerビルドを極限まで加速する「キャッシュの魔術」
Rustのコンパイル時間は、Docker環境でのボトルネックになりやすい。フィーチャーごとに`target`ディレクトリを分けるか、`sccache`を導入してコンパイル結果をS3等にキャッシュするのが定石だが、真のプロは「フィーチャーに応じた依存関係の分離」を行う。
マルチステージビルドでのレイヤー分離
依存関係の先行ビルド用コンテナ
FROM rust:1.75-slim as builder
WORKDIR /app
Cargo.tomlとLockファイルだけコピーして依存をビルド
COPY Cargo.toml Cargo.lock ./
フィーチャーを明示的に指定して、依存関係のみをキャッシュさせる
RUN cargo fetch –locked
RUN cargo build –features “production-mode” –release
ここで重要なのは、「フィーチャーフラグが変わるたびに`Cargo.lock`のハッシュが変わる」という事実だ。環境変数を利用して、ビルド引数ごとにレイヤーを分割せよ。
—
4. 内部アーキテクチャのハック：`#[cfg(feature = “…”)]`の汚染を防ぐ
コードベースのあちこちに`#[cfg(feature = “xyz”)]`が散らばると、保守性は死ぬ。これを防ぐための「Trait抽象化」を紹介する。
// 内部モジュールによる抽象化
[cfg(feature = “db-postgres”)]
mod postgres_impl;
[cfg(feature = “db-sqlite”)]
mod sqlite_impl;
// 呼び出し側にはインターフェースのみを見せる
pub trait Database { … }
pub fn get_db() -> Box
#[cfg(feature = “db-postgres”)]
return Box::new(postgres_impl::Client::new());
// …
}
この手法を使えば、ビジネスロジックはフィーチャーフラグの存在を知ることなく、純粋なRustコードとして記述できる。
—
5. 終わりに：アーキテクトからの提言
CargoのFeaturesは単なる設定値ではない。それは、「どのような実行環境をサポートし、どのようなバイナリを生成するか」という、プロダクトの設計思想そのものである。
- 小規模プロジェクト: `default`フィーチャーを徹底的に絞る。
- 中規模プロジェクト: フィーチャーの包含関係をツリー構造で可視化する。
- 大規模プロジェクト: CI上で排他制御の検証を自動化し、依存関係をモジュール層で隠蔽する。
もし、あなたのプロジェクトで`Cargo.toml`が肥大化し、誰もその依存関係を把握できなくなっているなら、今すぐフィーチャーの断捨離を行うべきだ。コンパイル時間はあなたの寿命そのもの。その一秒を、より高度なロジックを設計するために使ってほしい。
健闘を祈る。ビルドが通るたびに、君たちのシステムはより強固になる。