Rust Crate 選擇指南
適用場景
- 啟動新專案需要選擇依賴時
- 在多個同類型 crate 間做技術決策時
- 需要管理 Cargo.toml 的 features 與版本鎖定時
- 評估第三方 crate 的品質與維護狀態時
- 解決依賴衝突、重複版本、編譯時間過長等問題時
- 需要按功能領域快速查找推薦 crate 時
核心知識
Crate 選擇五項標準
| 標準 | 說明 | 檢查方式 |
|---|
| 下載量與趨勢 | crates.io 總下載量及近期趨勢，反映社群採用度 | crates.io 頁面、lib.rs 排名 |
| 維護狀態 | 最近 commit 時間、issue 回應速度、release 頻率 | GitHub 主頁、CHANGELOG |
| 文件品質 | docs.rs 文件完整度、範例豐富度、README 清晰度 | docs.rs、crate README |
| API 設計 | 是否符合 Rust 慣用風格、型別安全、ergonomics | 實際使用體驗、API review |
| 依賴鏈深度 | 傳遞依賴數量，影響編譯時間與供應鏈安全 | cargo tree、cargo deny |
補充考量：
- MSRV（最低支援 Rust 版本）：是否與專案相容
- License 相容性：MIT/Apache-2.0 雙授權最常見且安全
- unsafe 使用量：可用
cargo geiger 檢查 - 是否有知名團隊或組織維護：如 tokio、RustCrypto、serde-rs
依領域推薦 Crate 表格
Web 框架
| Crate | 版本 | 說明 |
|---|
| axum | 0.8 | tokio 團隊維護，tower 中介層生態系，型別安全路由 |
| actix-web | 4.9 | 高效能多執行緒框架，成熟穩定 |
| poem | 3.1 | 輕量優雅，OpenAPI 內建支援 |
HTTP Client
| Crate | 版本 | 說明 |
|---|
| reqwest | 0.12 | 最廣泛使用的 HTTP client，支援 async/blocking |
| hyper | 1.5 | 低階 HTTP 實作，適合需要完全控制的場景 |
| ureq | 3.0 | 純 blocking、零 async 依賴，適合 CLI 工具 |
序列化
| Crate | 版本 | 說明 |
|---|
| serde | 1.0 | Rust 序列化框架標準，derive 巨集生態系 |
| serde_json | 1.0 | JSON 序列化/反序列化，搭配 serde 使用 |
| toml | 0.8 | TOML 格式解析，適合設定檔 |
CLI
| Crate | 版本 | 說明 |
|---|
| clap | 4.5 | 功能最完整的命令列解析器，支援 derive 巨集 |
| dialoguer | 0.11 | 互動式終端提示（選單、確認、輸入） |
| indicatif | 0.17 | 進度條與 spinner，適合長時間操作 |
日誌 / 追蹤
| Crate | 版本 | 說明 |
|---|
| tracing | 0.1 | 結構化追蹤框架，支援 span 與 async，tokio 生態系標配 |
| tracing-subscriber | 0.3 | tracing 的訂閱者實作，格式化輸出與過濾 |
| log | 0.4 | 輕量日誌 facade，適合 library crate |
| env_logger | 0.11 | 搭配 log 使用，透過環境變數控制日誌等級 |
錯誤處理
| Crate | 版本 | 說明 |
|---|
| thiserror | 2.0 | derive 巨集定義自訂錯誤型別，適合 library |
| anyhow | 1.0 | 便捷錯誤傳播，適合 application |
| miette | 7.4 | 美觀的診斷訊息輸出，適合 CLI 工具 |
加密
| Crate | 版本 | 說明 |
|---|
| ring | 0.17 | 高效能密碼學原語（TLS、雜湊、簽章） |
| rustls | 0.23 | 純 Rust TLS 實作，取代 OpenSSL |
| argon2 | 0.5 | 密碼雜湊（Argon2id），RustCrypto 維護 |
資料庫
| Crate | 版本 | 說明 |
|---|
| sqlx | 0.8 | 編譯期 SQL 查詢驗證，async-first，支援多資料庫 |
| diesel | 2.2 | 型別安全 ORM / Query Builder，同步導向 |
| sea-orm | 1.1 | async ORM，基於 sqlx，ActiveRecord 風格 |
非同步
| Crate | 版本 | 說明 |
|---|
| tokio | 1.44 | 最主流 async runtime，多執行緒排程器 |
| async-trait | 0.1 | 在 trait 中使用 async fn（Rust 1.75+ 可用原生 AFIT） |
| futures | 0.3 | async 組合子與工具（join!、select!、Stream） |
測試
| Crate | 版本 | 說明 |
|---|
| proptest | 1.6 | 屬性測試框架，自動生成測試資料 |
| mockall | 0.13 | Mock 物件生成，支援 trait mocking |
| criterion | 0.5 | 統計基準測試，產出效能報告圖表 |
GUI
| Crate | 版本 | 說明 |
|---|
| egui | 0.31 | Immediate mode GUI，簡單快速，適合工具 |
| iced | 0.13 | Elm 架構 GUI，宣告式 UI，跨平台 |
| tauri | 2.2 | Web 技術 + Rust 後端，輕量桌面應用 |
時間日期
| Crate | 版本 | 說明 |
|---|
| chrono | 0.4 | 功能齊全的日期時間庫，社群最廣泛使用 |
| time | 0.3 | 較輕量替代方案，更少 unsafe，API 更現代 |
| jiff | 0.2 | 新世代日期時間庫，正確處理時區與 DST |
版本鎖定策略
SemVer 規則
toml# 插入號（預設）— 允許相容更新
serde = "1.0" # 等同 >=1.0.0, <2.0.0
tokio = "1.44" # 等同 >=1.44.0, <2.0.0
# 波浪號 — 僅允許 patch 更新
axum = "~0.8" # 等同 >=0.8.0, <0.9.0
# 精確鎖定 — 不自動更新
ring = "=0.17.8" # 僅此版本
# 星號 — 萬用字元（不建議用於生產）
rand = "0.8.*" # 等同 >=0.8.0, <0.9.0
Cargo.lock 管理策略
| 專案類型 | Cargo.lock 是否提交 | 理由 |
|---|
| Application | ✅ 提交 | 確保可重現建置 |
| Library | ❌ 不提交 | 讓下游決定依賴版本 |
| Workspace | ✅ 提交 | 統一所有成員版本 |
最小版本策略
bash# 檢查是否能用最低版本編譯（偵測過寬的版本宣告）
cargo +nightly -Z minimal-versions check
# 使用 cargo-msrv 驗證最低支援 Rust 版本
cargo msrv verify
Features 管理
原則：最小啟用
toml[dependencies]
# 關閉預設 features，只啟用需要的
tokio = { version = "1.44", default-features = false, features = ["rt-multi-thread", "macros", "net"] }
reqwest = { version = "0.12", default-features = false, features = ["json", "rustls-tls"] }
sqlx = { version = "0.8", default-features = false, features = ["runtime-tokio", "postgres", "macros"] }
條件編譯搭配 features
toml# 在自己的 crate 定義 features
[features]
default = ["json"]
json = ["dep:serde_json"]
yaml = ["dep:serde_yaml"]
full = ["json", "yaml"]
# 可選依賴
[dependencies]
serde_json = { version = "1.0", optional = true }
serde_yaml = { version = "0.9", optional = true }
程式碼範例
Basic: 常用 Cargo.toml 依賴模板
rust// 參見 examples/basic.rs
// 包含 Web App / CLI App / Library 三種典型依賴配置
Intermediate: Features 管理 + 條件編譯
rust// 參見 examples/intermediate.rs
// 示範 optional dependencies、feature gates、cfg 屬性
Advanced: 多 Crate 整合 API Server
rust// 參見 examples/advanced.rs
// 完整 axum + sqlx + tracing + serde API server 骨架
常見錯誤對照表
| 錯誤訊息 / 現象 | 原因 | 修復方式 |
|---|
error[E0277]: the trait bound ... is not satisfied 且涉及 feature-gated 型別 | 缺少必要的 feature flag，型別未被編譯進來 | 在 Cargo.toml 中為該依賴加上對應 feature，例如 features = ["json"] |
found crate 'foo' compiled by an incompatible version of rustc | MSRV 不符，crate 需要更新版的 Rust 編譯器 | 更新 rustc 版本，或鎖定 crate 到支援當前 MSRV 的舊版本 |
perhaps two different versions of crate 'foo' are being used | 依賴樹中同一 crate 存在多個不相容版本 | 執行 cargo tree -d 找出重複項，統一版本或用 [patch] 覆蓋 |
error: failed to select a version for 'foo': yanked | 使用的 crate 版本已被作者撤回 | 執行 cargo update 升級到未撤回版本，或指定其他版本號 |
| 編譯時間突然暴增（compile time explosion） | 啟用過多 features 或引入依賴鏈過深的 crate | 用 default-features = false 僅啟用必要 features；用 cargo build --timings 分析瓶頸 |
feature 'foo' includes 'bar' which is not a feature of ... | feature 定義錯誤，引用了不存在的 feature 名稱 | 檢查 Cargo.toml 中 [features] 區段，確認 feature 名稱正確且互相一致 |
the package requires a newer version of cargo but cargo --version 顯示舊版 | workspace 的 edition 或 resolver 設定需要更新的 Cargo | 升級 Rust toolchain，或降低 edition / resolver 設定 |
Cargo.toml 依賴模板
Web API Server
toml[dependencies]
axum = "0.8"
tokio = { version = "1.44", features = ["full"] }
serde = { version = "1.0", features = ["derive"] }
serde_json = "1.0"
sqlx = { version = "0.8", features = ["runtime-tokio", "postgres", "macros"] }
tracing = "0.1"
tracing-subscriber = { version = "0.3", features = ["env-filter"] }
thiserror = "2.0"
CLI 工具
toml[dependencies]
clap = { version = "4.5", features = ["derive"] }
serde = { version = "1.0", features = ["derive"] }
toml = "0.8"
anyhow = "1.0"
indicatif = "0.17"
dialoguer = "0.11"
env_logger = "0.11"
log = "0.4"
Library Crate
toml[dependencies]
serde = { version = "1.0", features = ["derive"] }
thiserror = "2.0"
log = "0.4"
[dev-dependencies]
proptest = "1.6"
criterion = { version = "0.5", features = ["html_reports"] }
mockall = "0.13"
tokio = { version = "1.44", features = ["rt", "macros"] }
參考來源
