Rust 宏與進階功能：宣告宏（Declarative Macros）

簡介

在 Rust 中，**宏（macro）**是語言提供的強大編譯期程式碼產生工具。相較於函式，宏可以直接操作語法樹（Token Tree），因此能在編譯時產生或改寫程式碼，達到 避免重複、提升可讀性、實作領域特定語言（DSL） 等目的。

本單元聚焦於 宣告宏（Declarative Macros），亦稱為 macro_rules! 宏。它是 Rust 最早、最常使用的宏系統，語法簡潔且易於上手。掌握宣告宏後，你將能在專案中快速抽象出重複的程式碼片段，並為自己的函式庫提供友善的使用者介面。

---

核心概念

1. macro_rules! 基本語法

macro_rules! 以 模式匹配 的方式定義多個規則（rules），每條規則由 左側模式（matcher） 與 右側展開（expander） 組成：

macro_rules! macro_name {
    ( pattern1 ) => { expansion1 };
    ( pattern2 ) => { expansion2 };
    // ...
}

• 模式：使用 $ident:tt、$ident:expr、$ident:ty 等 片段設計子（fragment specifier） 來捕獲不同類型的 token。
• 展開：可以是任意合法的 Rust 程式碼，展開時會把捕獲的 token 替換進去。

2. 片段設計子（Fragment Specifiers）

片段設計子	代表的語法類型	常見使用情境
ident	識別子（變數、函式、型別名稱）	let $name:ident = ...;
expr	表達式	println!("{}", $msg:expr);
ty	型別	fn $func:ident() -> $ret:ty { ... }
pat	模式（match）	match $val:expr { $p:pat => ... }
stmt	陳述式	let $v:ident = $e:expr; $s:stmt
block	程式區塊	if $cond:expr { $b:block }
tt	任意 token tree	用於捕獲不確定類型的 token

3. 可變重複（Repetition）

使用 $( ... )*、$( ... ),+、$( ... );* 等語法可以匹配 任意次數（包括 0 次）或 至少一次 的重複片段，常見於實作 vec!、println! 等宏。

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

4. 延遲展開（Hygiene）與作用域

Rust 宏具備 hygienic（衛生）特性：宏內部產生的變數不會與呼叫端的同名變數衝突，除非使用 macro_export 或 #[macro_use] 明確匯入。這保證了宏的安全性與可預測性。

---

程式碼範例

以下提供 5 個實用範例，展示宣告宏在不同情境下的應用。

範例 1：簡易 println! 包裝

macro_rules! debug_print {
    // 捕獲任意數量的表達式，使用逗號分隔
    ( $( $arg:expr ),* $(,)? ) => {
        println!("[DEBUG] {}", format!($( $arg ),*));
    };
}

// 使用方式
fn main() {
    let x = 42;
    debug_print!("x = {}", x);
}

說明：利用 $( $arg:expr ),* 捕獲任意數量的參數，並透過 format! 產生字串，再交給 println!。這樣的宏在除錯時非常方便。

範例 2：自訂 vec!（可變長度）

macro_rules! my_vec {
    // 支援空向量與尾端可有可無的逗號
    ( $( $elem:expr ),* $(,)? ) => {{
        let mut v = Vec::new();
        $(
            v.push($elem);
        )*
        v
    }};
}

fn main() {
    let a = my_vec![1, 2, 3];
    let b = my_vec![];
    println!("{:?} {:?}", a, b);
}

說明：透過重複展開 $elem:expr，將每個元素依序 push 進向量。此寫法與標準庫的 vec! 行為相同，展示了宏如何抽象出常見模式。

範例 3：產生測試函式的宏

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

// 為多個情境產生測試
generate_test!(test_add_one, 1 + 1, 2);
generate_test!(test_mul, 3 * 4, 12);

說明：利用 ident 捕獲測試函式名稱，expr 捕獲測試內容，讓測試案例的撰寫變得高度可維護。

範例 4：簡易 DSL：SQL SELECT 語句建構

macro_rules! select {
    ( $table:ident $(, $col:ident )* ) => {{
        let cols = vec![$( stringify!($col) ),*].join(", ");
        format!("SELECT {} FROM {}", cols, stringify!($table))
    }};
}

fn main() {
    let q = select!(users, id, name, email);
    println!("{}", q); // SELECT id, name, email FROM users
}

說明：此宏將 Rust 的標識子轉成字串，組合成簡易的 SQL 查詢語句，展示 領域特定語言（DSL） 的基礎建構方式。

範例 5：條件編譯的 cfg! 包裝

macro_rules! if_debug {
    ( $($stmt:stmt)* ) => {
        #[cfg(debug_assertions)]
        {
            $($stmt)*
        }
    };
}

fn main() {
    if_debug! {
        println!("這段程式只在 debug 模式編譯");
    }
}

說明：使用 cfg 屬性搭配宏，讓開發者在程式碼中以簡潔的方式加入條件編譯區塊。

---

常見陷阱與最佳實踐

陷阱	可能的結果	建議的做法
忘記加分號或逗號	編譯錯誤訊息不易定位	使用 $(,)? 或 $(;)? 允許尾端可有可無的分隔符
過度使用 tt 捕獲	失去型別檢查，宏展開後產生不易讀的錯誤	儘量使用具體的 fragment specifier（expr、ident、ty）
宏內部變數與外部衝突	變數遮蔽導致意外行為	依賴 衛生特性，不要手動 use 宏內部變數；若需共享，使用 macro_export
遞迴宏導致無限展開	編譯器報 recursion limit exceeded	為遞迴宏加上明確的終止條件，或使用 macro_rules! 的 @ 標籤分段實作
過度抽象	宏的可讀性下降，除錯困難	只在 重複度高、語意明確 的情況下使用宏；對於較複雜的邏輯，考慮使用 函式 或 procedural macro

最佳實踐

1. 保持簡潔：每條規則盡量只做一件事，讓錯誤訊息更具指向性。
2. 加入文件註解：使用 /// 為宏撰寫說明，並示範常見使用方式。
3. 測試宏：在 tests/ 或 #[cfg(test)] 模組中寫測試，確保宏在不同參數下的正確性。
4. 限制展開深度：若需要大量遞迴，考慮使用 proc-macro 或手動提升遞迴上限 #![recursion_limit = "256"]。
5. 遵守命名慣例：宏名稱通常使用全小寫且帶下劃線，例如 my_vec!、debug_print!，避免與函式混淆。

---

實際應用場景

1. 日誌與除錯：自訂 log!、debug! 系列宏，統一格式與條件編譯。
2. 測試自動化：產生大量相似測試函式（如表格驅動測試），減少樣板程式碼。
3. DSL 建構：如 SQL、HTML、JSON 建構器，讓使用者以類似原生語法的方式撰寫。
4. 資料結構生成：自動產生 enum、struct 的 impl 區塊（例如 serde 的 Serialize/Deserialize）。
5. 條件編譯：根據平台或功能旗標產生不同程式碼，保持單一來源檔案的可讀性。

---

總結

宣告宏（Declarative Macros）是 Rust 生態系中不可或缺的元程式設計工具。透過 模式匹配、片段設計子、可變重複 等概念，我們可以在編譯期自動產生安全且高效的程式碼。本文從語法基礎、實用範例、常見陷阱到最佳實踐，提供了一條 從入門到中階 的完整學習路徑。

掌握這些技巧後，你將能在專案中：

• 減少重複，提升維護性
• 建立領域特定語言，讓 API 更貼近使用者需求
• 安全地進行條件編譯，支援多平台開發

未來若需求更複雜的程式碼產生，亦可探索 Procedural Macro（屬於編譯器插件的宏），但 宣告宏 已足以解決絕大多數日常開發的問題。祝你在 Rust 的宏世界裡玩得開心，寫出更乾淨、更具表達力的程式碼！