Rust 專業開發：Cargo - 的專案管理核心

– 14 分鐘閱讀

當初接觸Rust時，最令我驚豔的不只是語言本身的優雅設計，更是其專案管理工具Cargo的強大功能。在多年的Rust開發經驗中，我發現Cargo不只是一個簡單的套件管理器，更是整個Rust生態系統的核心樞紐。

Cargo整合了專案初始化、相依性管理編譯建構、測試執行等功能於一身，讓Rust開發流程變得流暢與高效。若你剛開始學習Rust，理解Cargo將為你節省大量時間並避免許多常見陷阱。

Cargo專案結構基礎

當使用Cargo建立新專案時，它會自動生成一個結構完整的專案目錄。以下是使用cargo new命令建立的專案基本結構：

$ cargo new dolphins-are-cool
$ cd dolphins-are-cool/
$ tree
.
├── Cargo.toml
└── src
    └── main.rs
1 directory, 2 files

這個結構顯示Cargo建立了兩個關鍵檔案：

  • Cargo.toml：專案的設定檔案，使用TOML格式描述專案資訊和依賴
  • src/main.rs：應用程式的入口點，包含主函式

TOML（Tom’s Obvious Minimal Language）是Rust生態系統中廣泛使用的設定格式，其設計簡潔易讀。相較於JSON，它支援註解與語法更為直觀；相較於YAML，它的規則更加明確與不依賴縮排。

編譯與執行專案

建立專案後，可以使用cargo run命令一鍵編譯並執行程式：

$ cargo run
Compiling dolphins-are-cool v0.1.0 (/Users/brenden/dev/dolphins-are-cool)
Finished dev [unoptimized + debuginfo] target(s) in 0.59s
Running `target/debug/dolphins-are-cool`
Hello, world!

此輸出說明瞭Cargo的工作流程：

  1. 編譯專案（包括所有依賴）
  2. 生成執行檔（預設為除錯模式，含有除錯資訊）
  3. 執行生成的程式

每次執行cargo run時，Cargo會自動檢查檔案變更，只重新編譯有修改的部分，這大幅提升了開發效率。

建立程式函式庫

除了可執行應用程式外，Cargo也支援建立程式函式庫：

$ cargo new narwhals-are-real --lib
Created library `narwhals-are-real` package
$ cd narwhals-are-real/
$ tree
.
├── Cargo.toml
└── src
    └── lib.rs
1 directory, 2 files

使用--lib引數建立的專案有幾個關鍵差異：

  • 入口點變成src/lib.rs而非main.rs
  • 自動生成單元測試範例，而非主函式
  • 預設設定針對程式函式庫應用程式最佳化 程式函式庫可以使用cargo test執行測試：
$ cargo test
Finished test [unoptimized + debuginfo] target(s) in 0.00s
Running target/debug/deps/narwhals_are_real-3265ca33d2780ea2
running 1 test
test tests::it_works ... ok
test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out;
finished in 0.00s
Doc-tests narwhals-are-real
running 0 tests
test result: ok. 0 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out;
finished in 0.00s

值得注意的是，Cargo不僅執行了單元測試，還自動執行了檔案測試（Doc-tests）—這是Rust特有的功能，可以確保檔案中的程式碼範例正確無誤。

Cargo核心命令與工作流程

在日常Rust開發中，有幾個Cargo命令特別常用。理解這些命令的特性與差異，能讓開發流程更加高效。

核心命令概覽

Cargo命令功能摘要
build編譯並連結專案，生成最終目標檔
check檢查程式碼有效性，但不生成目標檔
test編譯並執行所有測試
run編譯並執行目標執行檔

最佳化發迭代速度

在開發過程中，我發現cargo check是提升迭代速度的秘密武器。它只檢查程式碼的語法和型別正確性，而不實際生成執行檔，這讓檢查速度大幅提升：

$ cargo clean
$ time cargo build
...
Finished dev [unoptimized + debuginfo] target(s) in 9.26s
cargo build 26.95s user 5.18s system 342% cpu 9.374 total
$ cargo clean
$ time cargo check
...
Finished dev [unoptimized + debuginfo] target(s) in 7.97s
cargo check 23.24s user 3.80s system 334% cpu 8.077 total

雖然在這個小型專案中差異不大（約1.3秒），但在大型專案中，check和build的時間差可能達到數分鐘。當反覆修改程式碼時，這種時間節省會累積成顯著的效率提升。

我的工作流程通常是：

  1. 編寫程式碼後先用cargo check快速驗證
  2. 確認無語法與型別錯誤後再使用cargo test執行測試
  3. 最後才使用cargo build或cargo run生成完整執行檔

這種漸進式的驗證方法能在每個階段及早發現問題，避免在完整編譯時才面對大量錯誤。

工具鏈管理與切換

Rust提供了多個發布管道（channel），包括穩定版（stable）、測試版（beta）和每夜版（nightly）。根據不同專案需求，可能需要在這些版本間靈活切換。

使用不同工具鏈

最簡單的方式是使用Cargo的+channel選項：

# 使用穩定版執行測試
$ cargo +stable test
...
# 使用每夜版執行測試
$ cargo +nightly test
...

這種方法的優點是：

  • 不需要更改全域設定
  • 可以針對特定命令使用特定版本
  • 適合臨時測試或驗證

如果尚未安裝nightly工具鏈，可能需要先執行rustup toolchain install nightly。

專案特定工具鏈設定

對於長期在特定版本開發的專案，可以使用rustup override設定專案專用的工具鏈：

# 僅適用於當前目錄及其子目錄
$ rustup override set nightly

這個命令會在當前目錄建立工具鏈覆寫設定，之後在此目錄執行的所有Cargo命令都會自動使用指定的工具鏈，無需每次增加+nightly引數。

這種方法特別適合：

  • 需要nightly功能的專案
  • 團隊協作時確保所有成員使用相同版本
  • 同時維護多個使用不同Rust版本的專案

設定儲存在$HOME/.rustup/settings.toml中，可以輕鬆移除或修改。

相依性管理統

Rust的套件生態系統是其最強大的特性之一。截至撰寫本文時，crates.io官方套件函式庫超過92,000個不同的crate可用。

Rust的模組化設計哲學

Rust語言核心相對精簡，許多功能透過外部crate提供，而非內建於標準函式庫種設計有幾個關鍵優勢：

  1. 語言核心保持精簡與穩定
  2. 功能可以由社群驅動快速演進
  3. 使用者只需引入實際需要的功能
  4. 避免了"廚房水槽"問題（過度臃腫的標準函式庫 舉例來說，Rust標準函式庫不包含隨機數生成器—這是許多程式設計任務的基本需求。相反，你需要使用rand crate，這是目前下載量最大的套件之一。

在專案中增加依賴

在Rust中增加依賴非常直接，只需在Cargo.toml中列出所需的crate：

[package]
name = "simple-project"
version = "0.1.0"
authors = ["Brenden Matthews <brenden@brndn.io>"]
edition = "2018"

[dependencies]
rand = "0.8"

這個設定指定了專案依賴rand crate的0.8.x版本。Cargo使用語義化版本控制（SemVer）系統，遵循主版本.次版本.修補版本的模式。

當沒有明確指定運算元時，Cargo預設使用脫字元要求（caret requirements），允許使用相容的最新版本。例如，rand = "0.8"將接受從0.8.0到0.9.0之前的任何版本，但不包括0.9.0及更高版本。

這種版本控制方式平衡了穩定性和更新性：

  • 自動接受包含錯誤修復和小功能的次要版本更新
  • 避免可能引入不相容變更的主要版本更新

對於那些需要更精確控制的情況，Cargo還支援其他版本指定方式，如=1.2.3（完全相符）、>=1.2.3（大於等於）等。

Rust的相依性管理統相較於C/C++等傳統語言是一個巨大飛躍。不再需要手動編寫複雜的構建檢查或將第三方程式碼整合到自己的程式碼函式庫Cargo自動處理所有這些複雜性。

當處理有大量依賴的專案時，這種自動化管理的價值更加明顯。它不僅提高了開發效率，還透過確保所有依賴版本的一致性和相容性，降低了潛在的錯誤風險。

Cargo作為Rust的專案管理工具，將所有開發流程無縫整合成一個連貫高效的系統。從專案建立到相依性管理從編譯測試到工具鏈切換，它提供了完整的解決方案。

理解Cargo的工作原理不僅能提升開發效率，更能幫助你更深入地理解Rust生態系統的設計理念—模組化、顯式和高效。隨著專案規模的增長，Cargo的價值會變得更加明顯，它能處理複雜的依賴關係，確保構建過程的一致性和可靠性。

無論是快速原型開發還是大型企業專案，掌握Cargo都是成為高效Rust開發者的必要條件。透過合理運用本文介紹的各種命令和技巧，你將能夠建立更加穩健、可維護的Rust應用程式。

Cargo 相依性管理進階技巧

在開發 Rust 應用時，相依性管理提高效率的關鍵。除了基本的 Cargo.toml 設定外，Cargo 還提供了更靈活的相依性管理式。

命令列增加依賴

除了直接編輯 Cargo.toml，我們也可以使用命令列工具快速增加依賴：

# 將 rand 套件增加為專案依賴
$ cargo add rand

這個指令會自動更新 Cargo.toml 檔案，為專案增加 rand 套件的最新相容版本。這種方式特別適合快速原型開發時使用。

版本規範與語義化版本控制

Cargo 支援多種版本指定方式，理解這些符號的含義對於維護穩定的依賴關係至關重要：

運算元範例最小版本最大版本允許更新？
插入符號 (^)^2.3.4>=2.3.4<3.0.0允許
插入符號 (^)^2.3>=2.3.0<3.0.0允許
插入符號 (^)^0.2.3>=0.2.3<0.3.0允許
插入符號 (^)^2>=2.0.0<3.0.0允許
波浪號 (~)~2.3.4>=2.3.4<2.4.0允許
波浪號 (~)~2.3>=2.3.0<2.4.0允許
波浪號 (~)~0.2>=0.2.0<0.3.0允許
萬用字元2.3.*>=2.3.0<2.4.0允許
萬用字元2.*>=2.0.0<3.0.0允許
萬用字元*無無允許
比較運算=2.3.4=2.3.4=2.3.4不允許
比較運算>=2.3.4>=2.3.4無允許
比較運算>=2.3.4,<3.0.0>=2.3.4<3.0.0允許

這個表格展示了 Cargo 中指定依賴版本的各種語法。最重要的是理解插入符號 (^) 的行為，它是 Cargo 的預設運算元，允許更新到相容版本（根據語義化版本規範）。例如，^2.3.4 允許更新到 2.y.z 的任何版本，但不允許升級到 3.0.0，因為主版本號的變更通常意味著不相容的 API 變更。

Cargo 內部使用 semver 套件來解析這些版本規範。當執行 cargo update 時，Cargo 會根據這些規範更新 Cargo.lock 檔案中的依賴到最新允許版本。

版本指定的最佳實踐

在多年的 Rust 開發經驗中，我發現關於如何指定依賴版本存在許多爭論。雖然沒有絕對的規則，但我認為有些實用的指導原則：

  1. **對於函式庫：避免固定（pinning）依賴版本。固定版本可能導致「依賴地獄」，當下游專案需要不同版本的共用函式庫出現衝突。

  2. 一般用法：使用插入符號（^）指定最低要求版本，允許次要版本和修補版本更新。這是 Rust 的預設做法，舉例來說：

    rand = "0.8.5"  # 等同於 ^0.8.5

  3. 自己發布的套件：嚴格遵循語義化版本規範，這有助於其他開發者根據你的工作構建並保持相容性。

  4. 特殊情況：如果特定版本有已知問題，可以使用更複雜的指定方式：

    some_crate = ">=1.2.3, <1.9.0"

Cargo.lock 檔案管理

Cargo.lock 是 Cargo 自動生成的檔案，記錄了專案的所有依賴（直接和間接）的確切版本和校驗和。對於這個檔案的處理需要特別考慮。

函式庫用程式的不同處理方式

Cargo.lock 的處理方式取決於你的專案類別：

  1. 函式庫：不應將 Cargo.lock 納入版本控制系統。如果使用 Git，應該將 Cargo.lock 加入到 .gitignore 中。這讓下游套件能夠根據需要更新間接依賴。

  2. 應用程式專案：應該將 Cargo.lock 與 Cargo.toml 一起納入版本控制。這確保了發布版本的行為一致性，即使第三方函式庫來發生變化。

這種區分是 Rust 社群的共識，也符合其他語言生態系統的做法（如 npm 的 package-lock.json、Ruby 的 Gemfile.lock 和 Python Poetry 的 poetry.lock）。

Cargo.lock 的作用

Cargo.lock 檔案的主要用途是：

  • 確保專案在不同環境中的構建結果一致
  • 防止因依賴更新導致的意外行為變更
  • 提供依賴完整性校驗

在團隊協作環境中，這個檔案尤為重要，它確保所有開發者使用完全相同的依賴版本。

特性標記（Feature Flags）的有效使用

特性標記（Feature flags）是 Rust 生態系統中的一個強大機制，允許開發者提供可選功能和依賴。這一機制在釋出軟體（特別是函式庫非常見。

特性標記的主要用途

特性標記主要用於：

  • 保持編譯時間短
  • 減小二進位檔案大小
  • 提供效能改進選項
  • 允許使用者選擇所需功能

但這些好處是以增加編譯時的複雜性為代價的。

特性標記的限制

特性標記有一些限制需要注意：

  • 只支援布林表示式（啟用或停用）
  • 會傳遞到依賴列表中的套件，因此可以透過頂層特性標記啟用底層套件的特性

實際案例分析：dryoc 套件

讓我們看一個實際案例，以 dryoc 套件為例：

[dependencies]
base64 = {version = "0.13", optional = true}
curve25519-dalek = "3.0"
generic-array = "0.14"
poly1305 = "0.6"
rand_core = {version = "0.5", features = ["getrandom"]}
salsa20 = {version = "0.7", features = ["hsalsa20"]}
serde = {version = "1.0", optional = true, features = ["derive"]}
sha2 = "0.9"
subtle = "2.4"
x25519-dalek = "1.1"
zeroize = "1.2"

[dev-dependencies]
base64 = "0.13"
serde_json = "1.0"
sodiumoxide = "0.2"

[features]
default = [
  "u64_backend",
]
simd_backend = ["curve25519-dalek/simd_backend", "sha2/asm"]
u32_backend = ["x25519-dalek/u32_backend"]
u64_backend = ["x25519-dalek/u64_backend"]

這個 Cargo.toml 展示了特性標記的實際使用方式。注意以下幾點：

  1. base64 和 serde 被標記為可選依賴 (optional = true)
  2. [features] 區塊定義了四個特性標記
  3. default = ["u64_backend"] 指定了預設啟用的特性
  4. 特性標記可以啟用依賴中的特性，如 simd_backend = ["curve25519-dalek/simd_backend", "sha2/asm"]

在程式碼中使用特性標記

特性標記如何影響程式碼？讓我們看 dryoc 套件中的一個實際例子：

#[cfg(feature = "serde")]
use serde::{Deserialize, Serialize};
use zeroize::Zeroize;

#[cfg_attr(
    feature = "serde",
    derive(Serialize, Deserialize, Zeroize, Debug, PartialEq)
)]
#[cfg_attr(not(feature = "serde"), derive(Zeroize, Debug, PartialEq))]
#[zeroize(drop)]
/// Message container, for use with unencrypted messages
pub struct Message(pub Box<InputBase>);

這段程式碼展示瞭如何使用條件編譯屬性來根據特性標記調整程式碼行為：

  1. #[cfg(feature = "serde")] - 僅當 “serde” 特性啟用時，才包含該 use 陳述式
  2. #[cfg_attr(feature = "serde", ...)] - 僅當 “serde” 特性啟用時，才啟用指定的屬性
  3. #[cfg_attr(not(feature = "serde"), ...)] - 僅當 “serde” 特性停用時，才啟用指定的屬性

這種方式允許根據特性標記的啟用狀態來改變型別的行為和能力，而不需要維護多個版本的程式碼。

條件編譯屬性詳解

Rust 提供了多種條件編譯屬性，用於特性標記相關的程式碼控制：

  • cfg(predicate) - 只有當條件為真時，才編譯它所附加的內容
  • cfg_attr(predicate, attribute) - 只有當條件為真時，才啟用指定的屬性
  • not(predicate) - 當條件為假時回傳真，反之亦然
  • all(predicate) - 當所有條件都為真時回傳真
  • any(predicate) - 當任一條件為真時回傳真

這些屬性可以組合使用，形成複雜的條件邏輯。例如：

#[cfg(all(feature = "advanced_features", not(feature = "legacy_mode")))]
fn advanced_function() {
    // 只有當啟用了 advanced_features 與沒有啟用 legacy_mode 時才編譯
}

特性標記的最佳實踐

在多個專案的開發經驗中，我歸納出一些關於特性標記使用的建議：

避免過度使用特性標記

雖然特性標記很強大，但不應過度依賴它們。如果發現自己在建立具有大量特性標記的「超級套件」，可能應該考慮將套件拆分為更小的獨立子套件。

這種模式在 Rust 生態系統中很常見，例如 serde、rand 和 rocket 套件都採用了這種方法。這些套件通常有一個核心套件和多個功能特定的附屬套件。

何時必須使用特性標記

有些情況下必須使用特性標記，例如：

  • 在頂層套件中提供可選的 trait 實作
  • 提供不同後端實作的選項（如上例中的 u32_backend 和 u64_backend）
  • 啟用可選的序列化支援（如 serde）

特性標記命名慣例

特性標記的命名應該清晰表達其功能，常見的命名模式包括：

  • 以功能命名：如 async、logging、metrics
  • 以依賴命名：如 serde、tokio
  • 以後端或實作方式命名：如 simd_backend、u64_backend

特性標記的互斥性處理

有時需要實作互斥的特性標記（如 u32_backend 和 u64_backend），處理方式通常是：

  1. 在 default 區塊中指定一個預設選項
  2. 在檔案中明確說明特性標記的互斥性
  3. 在程式碼中使用 #[cfg(...)] 和 #[cfg_attr(...)] 確保正確行為

依賴補丁（Patching

Rust 依賴套件修補：從問題到解決方案

在 Rust 開發過程中，有時會遇到需要修改依賴套件的情況。這通常發生在發現上游套件存在錯誤，但又不想完全重寫其功能時。透過 Cargo 的修補機制，我們可以暫時解決這些問題，同時等待上游套件的更新。

上游套件修補的常見流程

當發現依賴套件中的問題需要修補時，傳統做法通常包括以下步驟：

  1. 在 GitHub 上建立一個分支（fork）
  2. 在你的分支中修補該套件
  3. 向上遊專案提交提取請求（pull request）
  4. 在等待提取請求被合併和發布的同時，調整你的 Cargo.toml 指向你的分支

這個流程雖然可行，但存在一些潛在問題：一是需要追蹤上游套件的變更並視需要整合；二是你的修補可能永遠不會被上游接受，導致你被困在自己的分支上。因此，在處理上游套件時，應盡可能避免分支。

實際操作範例：修補 num_cpus 套件

讓我們透過一個實際例子來說明如何修補依賴套件。以下將修改 num_cpus 套件，用我們自己的修補版本替代它。

首先建立一個空專案：

$ cargo new patch-num-cpus
$ cd patch-num-cpus

接著在 Cargo.toml 中加入 num_cpus 依賴：

[dependencies]
num_cpus = "1.0"

更新 src/main.rs 以顯示 CPU 數量：

fn main() {
    println!("There are {} CPUs", num_cpus::get());
}

執行程式會顯示實際的 CPU 數量：

$ cargo run
Finished dev [unoptimized + debuginfo] target(s) in 0.00s
Running `target/debug/patch-num-cpus`
There are 4 CPUs

建立修補版本

現在，讓我們在同一工作目錄建立一個新的函式庫作相同的 API：

$ cargo new num_cpus --lib

修改 num_cpus/src/lib.rs 以實作我們自己的 num_cpus::get() 版本：

pub fn get() -> usize {
    100  // 回傳一個硬編碼的值，僅供測試
}

使用修補版本

回到原始 patch-num-cpus 專案，修改 Cargo.toml 使用我們的替代套件：

[dependencies]
num_cpus = { path = "num_cpus" }

執行程式會顯示我們的修補版本結果：

$ cargo run
Compiling patch-num-cpus v0.1.0
Finished dev [unoptimized + debuginfo] target(s) in 0.33s
Running `target/debug/patch-num-cpus`
There are 100 CPUs

這個修補範例雖然簡單，但清楚地展示了替換依賴套件的過程。我們建立了一個與原套件同名的本地套件，並實作了相同的 API，然後在 Cargo.toml 中指定使用我們的本地版本。這種方法讓我們能夠在不修改原始程式碼的情況下更改依賴套件的行為。

使用 GitHub 分支修補

如果想使用 GitHub 分支而非本地修補，可以在 Cargo.toml 中直接指向 GitHub 倉函式庫

[dependencies]
num_cpus = { git = "https://github.com/brndnmtthws/num_cpus", 
             rev = "b423db0a698b035914ae1fd6b7ce5d2a4e727b46" }

在這個例子中，rev 引數指定了撰寫時的最新提交的 Git 雜湊值。編譯專案時，Cargo 會從 GitHub 倉函式庫程式碼，簽出指定的修訂版本（可以是提交、分支或標籤），並將其編譯為依賴項。

間接依賴修補技術

有時候，我們需要修補依賴的依賴。例如，你可能依賴的套件又依賴於另一個需要修補的套件。使用 num_cpus 作為例子，該套件在非 Windows 平台上依賴 libc = "0.2.26"。我們可以透過更新 Cargo.toml 來修補為較新的版本：

[patch.crates-io]
libc = { git = "https://github.com/rust-lang/libc", tag = "0.2.88" }

在這個例子中，我們指向 libc 的 Git 倉函式庫確指定 0.2.88 標籤。Cargo.toml 中的 patch 區段用於修補 crates.io 登入檔本身，而不是直接修補套件。實際上，你是將所有上游 libc 依賴替換為你自己的版本。

[patch.crates-io] 區段是 Cargo 提供的一個強大功能，它允許我們替換來自 crates.io 的任何依賴，甚至包括間接依賴。這在處理多層依賴關係中的問題時特別有用。需要注意的是，這種修補隻影響你的專案，不會影響依賴你專案的下游套件。

請謹慎使用此功能，與僅在特殊情況下使用。它不會影響下游依賴，這意味著依賴你的套件的任何套件都不會繼承此修補。這是 Cargo 目前的一個限制，沒有合理的解決方法。如果需要對二階和三階依賴有更多控制，則需要分支所有相關專案或使用工作區（workspaces）將它們直接作為子專案包含在自己的專案中。

玄貓

玄貓

技術愛好者，專注於分享程式開發、雲端技術與 AI 應用的心得體會。