Rust 入門與環境設置 — 理解 `main` 函數

簡介

在任何程式語言中，入口點（entry point）都是程式執行的起點，Rust 也不例外。main 函數就是 Rust 程式的入口，它負責初始化執行環境、呼叫其他模組、以及最後返回執行結果。對初學者而言，正確掌握 main 的語法與行為，是建立穩固程式基礎的第一步；對中階開發者來說，則是設計 CLI 工具、服務端程式或嵌入式應用時不可或缺的概念。

本篇文章將從 語法結構、回傳值、參數傳遞、以及 錯誤處理 四個面向，深入探討 main 函數的運作方式，並提供實作範例、常見陷阱與最佳實踐，幫助讀者在實務開發中快速上手。

核心概念

1. `main` 的最基本形式

在 Rust 中，最簡單的程式只需要一個 main 函數：

fn main() {
    println!("Hello, world!");
}

fn 表示「函式」的關鍵字。
main 為固定名稱，編譯器會自動把它當作 入口點。
() 表示 main 不接受參數。
大括號 {} 包含函式本體。
println! 是宏（macro），用來輸出文字到標準輸出。

注意：main 必須是 fn，且不可標記為 pub，因為它只在 crate 的根模組可見。

2. `main` 的回傳型別

預設情況下，main 的回傳型別是 ()（單位型別），等同於 void。然而，Rust 允許 main 回傳 Result<(), E>，讓錯誤可以自動轉換為程式的退出碼（exit code）：

use std::error::Error;

fn main() -> Result<(), Box<dyn Error>> {
    // 假設執行一些可能失敗的操作
    let content = std::fs::read_to_string("config.toml")?;
    println!("設定檔內容:\n{}", content);
    Ok(())
}

Result<(), Box<dyn Error>> 表示「若成功回傳 ()，若失敗回傳任意實作 Error 的型別」。
? 操作符會在錯誤時提前返回，等同於 match 的 Err(e) => return Err(e.into())。
若 main 回傳 Err，Rust 會將退出碼設為 1，並把錯誤訊息印到標準錯誤（stderr）。

3. 取得命令列參數

std::env::args() 可取得執行時傳入的參數。以下範例示範如何解析簡單的 --name 參數：

use std::env;

fn main() {
    // 產生一個迭代器，第一個元素是程式本身的路徑
    let mut args = env::args().skip(1); // 跳過程式名稱

    // 期待 `--name <value>` 的形式
    while let Some(arg) = args.next() {
        if arg == "--name" {
            if let Some(name) = args.next() {
                println!("Hello, {}!", name);
            } else {
                eprintln!("錯誤: `--name` 後面缺少參數");
                std::process::exit(1);
            }
        } else {
            eprintln!("未知參數: {}", arg);
        }
    }
}

skip(1) 讓我們忽略第一個元素（程式路徑）。
while let Some(arg) = args.next() 逐一取出參數。
eprintln! 會把訊息寫入 stderr，適合錯誤或警告訊息。
std::process::exit(1) 主動設定退出碼。

4. 多執行緒與 `main` 的關係

在需要同時執行多項任務時，我們常在 main 中建立執行緒（thread）或使用 async 執行環境。以下示範使用 std::thread 建立兩個子執行緒，並在 main 中等待它們完成：

use std::thread;
use std::time::Duration;

fn main() {
    let handle1 = thread::spawn(|| {
        for i in 1..=5 {
            println!("子執行緒 1 - 計數 {}", i);
            thread::sleep(Duration::from_millis(200));
        }
    });

    let handle2 = thread::spawn(|| {
        for i in 1..=5 {
            println!("子執行緒 2 - 計數 {}", i);
            thread::sleep(Duration::from_millis(150));
        }
    });

    // 等待兩個子執行緒結束
    handle1.join().expect("子執行緒 1 panicked");
    handle2.join().expect("子執行緒 2 panicked");

    println!("所有執行緒已完成");
}

thread::spawn 會返回一個 JoinHandle<T>，join() 用來等待執行緒結束。
若子執行緒發生 panic，join() 會回傳 Err，此時使用 expect 讓程式直接退出並印出錯誤資訊。

5. 使用 async/await 的 `main`（需要 `tokio` 或 `async-std`）

Rust 原生的 main 仍是同步函式，但許多 async 執行時提供宏讓我們以 async 方式撰寫入口點：

// Cargo.toml 必須加入
// tokio = { version = "1", features = ["full"] }

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let url = "https://httpbin.org/ip";
    let body = reqwest::get(url).await?.text().await?;
    println!("遠端 IP: {}", body);
    Ok(())
}

#[tokio::main] 會自動建立一個 Tokio 執行時，並把 main 轉換為 async。
這樣的寫法讓 非阻塞 I/O 成為可能，適合網路服務或 CLI 工具。

常見陷阱與最佳實踐

陷阱	說明	解決方式
忘記 `main` 必須在 crate 根模組	若把 `main` 放在子模組，編譯會失敗。	確保 `fn main()` 位於 `src/main.rs`（binary crate）或 `src/lib.rs` 內的根層。
直接使用 `unwrap()` 產生 panic	在 `main` 中過度使用 `unwrap()` 會在錯誤時直接崩潰，使用者體驗不佳。	改用 `?` 搭配 `Result`，或自行印出錯誤訊息後 `std::process::exit(1)`。
忽略命令列參數的錯誤處理	未檢查參數長度或格式會導致 `None.unwrap()`。	使用 `match` 或 `clap`/`structopt` 等套件做參數驗證。
子執行緒未 `join()`	主執行緒結束前子執行緒仍在跑，可能被強制終止。	必須在 `main` 結尾呼叫 `join()`，或使用 `thread::scope`（Rust 1.63+）管理生命週期。
async `main` 忘記加執行時宏	直接寫 `async fn main()` 會編譯錯誤。	加上 `#[tokio::main]`、`#[async_std::main]` 或自行建立執行時。

最佳實踐

使用 Result 回傳錯誤：讓 cargo run --quiet 能自動顯示錯誤訊息。
將參數解析抽離：建立 fn parse_args() -> Config，保持 main 簡潔。
避免全域 mutable：若需要共享狀態，使用 Arc<Mutex<T>> 或 channel。
使用測試：在 tests/ 中為 parse_args、錯誤處理寫單元測試，提升可靠度。

實際應用場景

場景	為何需要自訂 `main`	範例簡述
CLI 工具	需要解析多個子指令、提供說明文件、回傳不同退出碼。	使用 `clap` 建立 `myapp init
資料轉換腳本	讀取檔案、處理錯誤、輸出結果，需在錯誤時返回非 0 退出碼。	`main -> read_csv() -> transform() -> write_json()`，每一步回傳 `Result`.
微服務入口	啟動 HTTP 伺服器、設定 logger、處理 graceful shutdown。	`#[tokio::main] async fn main() { init_logger(); run_server().await?; }`
嵌入式開發	`no_std` 環境下仍需要 `#[entry]`（類似 `main`）作為啟動點。	使用 `cortex-m-rt` 的 `#[entry] fn main() -> ! { loop { … } }`。
測試基礎設施	在 CI 中執行自訂腳本，根據返回值決定是否通過。	`cargo run --bin build-tool && echo "Success"`。

總結

main 函數是 Rust 程式的唯一入口點，它的設計雖然簡潔，卻蘊含了錯誤處理、參數解析、執行緒管理與 async 支援等多項關鍵概念。掌握以下要點，即可寫出 可讀、可維護且符合使用者期待 的程式：

遵守語法：fn main() 必須在根模組，回傳型別可為 Result。
善用 ? 讓錯誤自動傳遞，避免 unwrap() 帶來的 panic。
正確處理命令列參數，必要時使用成熟的參數解析庫。
在多執行緒或 async 情境下，確保資源正確釋放與程式正確結束。
遵循最佳實踐：保持 main 簡潔、將業務邏輯抽離、寫測試。

透過本篇的說明與範例，你已經能夠在自己的 Rust 專案中自信地撰寫 main，並根據需求擴展成完整的 CLI、服務或嵌入式應用。祝你在 Rust 的旅程中寫出更多安全、快速且好用的程式！

Rust 入門與環境設置 — 理解 main 函數

簡介

核心概念

1. main 的最基本形式

2. main 的回傳型別