Rust 宏與進階功能 ── 函數宏（Function‑like Macros）

簡介

在 Rust 中，宏是一種在編譯期展開的程式碼生成工具，能夠大幅減少樣板程式 (boilerplate) 並提升抽象層級。除了最常見的 macro_rules! 宣告式宏之外，Rust 也支援 函數宏（又稱 function‑like macro），它的語法與函式相似，但在編譯期就會被展開成任意的 Rust 程式碼。

函數宏的威力在於：

靈活的語法：可以接受任意的 token 樹 (token tree) 作為參數，讓使用者自行定義語法糖。
零成本抽象：展開後的程式碼與手寫的等價，執行效能不會受到額外負擔。
提升可讀性：將重複的模式抽離成宏，讓呼叫端的程式碼更簡潔、更具意圖。

本篇文章將從概念說明、實作範例、常見陷阱與最佳實踐，最後延伸到實務應用，帶你一步步掌握函數宏的使用方法。

核心概念

1. 基本語法

函數宏使用 macro_rules! 定義，但其匹配規則以 ! 為前綴，呼叫時看起來像函式：

macro_rules! my_vec {
    ( $( $x:expr ),* $(,)? ) => {
        {
            let mut v = Vec::new();
            $(
                v.push($x);
            )*
            v
        }
    };
}

$( $x:expr ),*：匹配任意數量的表達式，使用逗號分隔。
$(,)?：允許最後一個逗號是可選的（Trailing comma）。
宏體內部使用 大括號 包住，以確保展開後的程式碼是一個完整的表達式。

呼叫方式：

let numbers = my_vec![1, 2, 3, 4];

2. Token Tree 與重複匹配

函數宏的參數是 token tree，這意味著它可以接受任意合法的 Rust token 組合，而不僅限於表達式或型別。例如：

macro_rules! log {
    ( $lvl:ident, $($arg:tt)+ ) => {
        println!("[{}] {}", stringify!($lvl), format!($($arg)+));
    };
}

$lvl:ident 捕獲一個標識符（如 INFO、WARN）。
$($arg:tt)+ 捕獲 一個或多個 任意 token，常用於轉交給 format!。

使用範例：

log!(INFO, "使用者 {} 登入", user_id);
log!(ERROR, "錯誤碼: {}", err_code);

3. 內建宏與自訂宏的差異

Rust 標準庫提供的 println!、vec! 等都是函數宏。自訂宏的寫法與它們相同，只是規則完全由開發者決定。以下示範一個簡易的 assert_eq! 替代版，加入自訂錯誤訊息：

macro_rules! assert_eq_msg {
    ( $left:expr , $right:expr , $msg:expr ) => {
        if $left != $right {
            panic!("assertion failed: {} != {} ({})", $left, $right, $msg);
        }
    };
}

4. 使用 `macro_export!` 與模組可見性

若要讓宏在 crate 外部可見，需要加上 #[macro_export]，且通常放在根模組或 pub mod 中：

#[macro_export]
macro_rules! json {
    ( $( $key:expr => $value:expr ),* $(,)? ) => {
        {
            let mut map = std::collections::HashMap::new();
            $(
                map.insert($key.to_string(), $value.into());
            )*
            map
        }
    };
}

在其他 crate 中：

use my_crate::json;

let data = json!{
    "name" => "Alice",
    "age"  => 30,
};

5. 逐步展開與除錯

使用 cargo expand（需安裝 cargo-expand）可以觀察宏展開後的結果，對除錯非常有幫助：

cargo expand --lib

程式碼範例

以下提供五個常見且實用的函數宏範例，均附上說明註解。

範例 1：簡易 `vec!` 替代（支援 `push!` 語法）

macro_rules! push_vec {
    ( $elem:expr ; $( $rest:expr ),* ) => {
        {
            let mut v = Vec::new();
            v.push($elem);
            $(
                v.push($rest);
            )*
            v
        }
    };
}

// 使用方式
let v = push_vec![10; 20, 30, 40];
println!("{:?}", v); // [10, 20, 30, 40]

說明：第一個元素使用分號分隔，後續元素使用逗號，展示了如何混合不同的分隔符。

範例 2：條件編譯的 `debug_log!`

macro_rules! debug_log {
    ( $($arg:tt)* ) => {
        #[cfg(debug_assertions)]
        {
            eprintln!("[DEBUG] {}", format!($($arg)*));
        }
    };
}

// 只在 debug 組建時輸出
debug_log!("變數 x = {}", x);

說明：利用 #[cfg(debug_assertions)] 讓宏在 release 版自動消失，避免產生不必要的 I/O 開銷。

範例 3：產生測試案例的 `test_case!`

macro_rules! test_case {
    ( $name:ident, $input:expr, $expected:expr ) => {
        #[test]
        fn $name() {
            let result = $input;
            assert_eq!(result, $expected);
        }
    };
}

// 自動產生多個測試
test_case!(case_add, 2 + 3, 5);
test_case!(case_mul, 4 * 5, 20);

說明：將測試樣板抽象化，讓新增測試只需要一行宏呼叫。

範例 4：簡易 `json!`（前面已示範）

#[macro_export]
macro_rules! json {
    ( $( $key:expr => $value:expr ),* $(,)? ) => {
        {
            let mut map = std::collections::HashMap::new();
            $(
                map.insert($key.to_string(), $value.into());
            )*
            map
        }
    };
}

// 呼叫
let obj = json!{
    "id"   => 42,
    "name" => "Bob",
    "active" => true,
};

說明：利用 into() 讓值自動轉換成 serde_json::Value（若加入 serde_json 的 From 實作），示範了宏與外部 crate 的結合。

範例 5：可變參數的 `select!`（類似 `match` 的簡化版）

macro_rules! select {
    ( $( $pat:pat => $expr:expr ),* $(,)? ) => {
        match std::env::var("SELECT").as_deref() {
            $(
                Some($pat) => $expr,
            )*
            _ => panic!("未知的 SELECT 值"),
        }
    };
}

// 假設環境變數 SELECT 為 "A"
select!{
    "A" => println!("選擇 A"),
    "B" => println!("選擇 B"),
}

說明：把環境變數的分支判斷抽成宏，讓主程式碼更聚焦於業務邏輯。

常見陷阱與最佳實踐

陷阱	可能的後果	解決方案 / 最佳實踐
宏展開後產生多餘的分號	編譯錯誤或語意不符	在宏體外層加上大括號 `{ ... }`，或使用 `;` 由呼叫端自行決定
變數遮蔽 (shadowing)	產生意外的行為，尤其在迴圈內	在宏內部使用 `let __tmp = ...;` 之類的私有名稱，避免與使用者變數衝突
過度使用 `tt` 捕獲	失去型別檢查，錯誤訊息不友好	儘可能使用更具體的 fragment specifier (`expr`, `ident`, `ty` 等)
宏遞迴導致無窮展開	編譯器報錯 `macro expansion limit exceeded`	為遞迴宏加入終止條件，或使用 `macro_rules!` 的 `@` 標記區分遞迴階段
跨 crate 使用時忘記 `#[macro_export]`	使用者無法看到宏，編譯失敗	在公開宏時一定加上 `#[macro_export]`，並在 `Cargo.toml` 中設定 `crate-type = ["lib"]`

其他最佳實踐

保持宏的單一職責：每個宏只負責一件事，避免過度複雜的匹配規則。
提供文件與範例：使用 /// 註解說明宏的語法與限制，讓 cargo doc 能自動生成說明。
使用 cargo expand 觀察結果：在開發過程中經常檢查展開後的程式碼，確保沒有意外的 move 或所有權問題。
避免在宏內部使用 unsafe：若必須使用，務必在文件中明確說明安全前提。
考慮 proc_macro 替代方案：當宏的需求超出 macro_rules! 能力（如需要語法樹分析）時，改用 procedural macro。

實際應用場景

場景	為什麼適合使用函數宏
日誌與追蹤	需要在 debug 與 release 之間自動切換、加入檔案與行號等資訊，宏能在編譯期插入 `file!()`、`line!()` 等內建宏。
測試資料生成	大量測試案例的資料結構相似，使用宏一次定義即可產生多筆測試資料，減少手動錯誤。
Domain‑Specific Language (DSL)	例如 SQL、HTML、正則表達式的嵌入式 DSL，宏可以把類似文字的語法直接轉成 Rust 結構。
條件編譯的功能切換	透過 `cfg!` 與宏結合，實作「開關」式功能（Feature flag）而不產生額外執行成本。
資源管理	如自動產生 `Vec`、`HashMap`、`BTreeSet` 等集合的初始化程式碼，讓程式碼更具宣告式風格。

案例：在一個微服務專案中，我們使用 log_event! 宏自動攜帶請求 ID、時間戳與服務名稱，所有日誌呼叫只需要 log_event!(INFO, "收到請求");，而宏內部會把這些上下文資訊注入，讓日誌統一且不易遺漏。

總結

函數宏是 Rust 中 編譯期程式碼生成 的利器，結合 macro_rules! 的模式匹配與 token tree 的彈性，我們可以：

減少樣板程式，提升程式可讀性。
在不犧牲效能 的前提下，提供類似語法糖的功能。
根據需求 建立 DSL、測試生成器、條件編譯工具等多樣化應用。

在使用時，務必遵守 清晰的匹配規則、避免變數遮蔽、適度使用 #[macro_export]，並善用 cargo expand 觀察展開結果。掌握這些要點後，你就能在專案中自信地引入函數宏，寫出更簡潔、可維護且高效的 Rust 程式碼。祝開發順利！ 🚀