---
name: rust-crate-selection
description: >
  Rust crate 選擇指南技能。按功能領域推薦經過實戰驗證的 crate：
  HTTP（reqwest/hyper/axum）、序列化（serde/serde_json/toml）、
  CLI（clap/dialoguer/indicatif）、日誌（tracing/log/env_logger）、
  加密（ring/rustls/argon2）、資料庫（sqlx/diesel/sea-orm）、
  GUI（egui/iced/tauri）、測試（proptest/mockall/criterion）、
  非同步（tokio/async-trait/futures）。
  含選擇判斷標準、版本鎖定策略、Cargo.toml features 管理。
  觸發關鍵詞：Rust crate, which crate, recommend crate, crate comparison,
  best Rust library, cargo dependency, version pinning, blessed.rs,
  lib.rs, crates.io, feature flags
---

# 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"] }
```

## 參考來源

- [blessed.rs](https://blessed.rs) — 非官方推薦 crate 精選清單
- [lib.rs](https://lib.rs) — crate 搜尋與分類排名
- [crates.io](https://crates.io) — 官方 crate 注冊中心
- [docs.rs](https://docs.rs) — 自動生成的 crate 文件
- [Rust Cookbook](https://rust-lang-nursery.github.io/rust-cookbook/) — 常見任務的 crate 使用範例
- [Cargo Reference: Specifying Dependencies](https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html) — 官方版本語法文件
- [Are We Web Yet?](https://www.arewewebyet.org/) — Web 生態系追蹤