Rust 宏與進階功能 ── 派生宏（Derive Macros）

簡介

在 Rust 中，宏是擴充語言功能的核心機制，讓開發者可以在編譯期自動產生程式碼，減少樣板（boilerplate）與重複勞動。
其中最常被使用、也是最友善初學者的宏類型是 派生宏（Derive Macro）。它只需要在結構體或列舉上加上 #[derive(...)]，編譯器就會自動為我們產生實作（implementation），如 Debug、Clone、Serialize 等。
掌握派生宏不僅能提升開發效率，還能讓程式碼保持一致性與可讀性，是進階 Rust 開發者必備的工具。

核心概念

1. 什麼是派生宏

派生宏是一種 屬性宏（attribute macro），它在編譯期接收一個資料型別（struct、enum）作為輸入，根據預先定義好的模板產生相對應的 trait 實作。
Rust 標準庫已內建多個常用的派生宏，例如：

#[derive(Debug)]：讓型別可以使用 {:?} 格式化輸出。
#[derive(Clone)]：產生深度複製的實作。
#[derive(PartialEq, Eq)]：提供相等性比較。

除了標準庫，社群也提供許多第三方派生宏（如 serde::Serialize、serde::Deserialize），讓資料序列化、資料庫映射等功能變得輕鬆。

2. 基本語法

在結構體或列舉前加上 #[derive(Trait1, Trait2, ...)] 即可。例如：

#[derive(Debug, Clone, PartialEq)]
struct Point {
    x: i32,
    y: i32,
}

編譯器會自動為 Point 產生 Debug、Clone、PartialEq 三個 trait 的實作。

3. 自訂派生宏的流程（進階）

雖然本篇主要聚焦在使用層面，但了解自訂派生宏的基本步驟有助於更深入的掌握：

建立 proc-macro crate：使用 cargo new my_macros --lib，並在 Cargo.toml 加入 proc-macro = true。
使用 syn 解析語法樹：將輸入的 token stream 轉成 syn::DeriveInput，方便分析結構。
使用 quote 產生程式碼：利用 quote! 巨集把 Rust 程式碼組合成 token stream。
在原始 crate 中引用：在 Cargo.toml 加入 my_macros = { path = "../my_macros" }，然後在需要的型別上使用 #[derive(MyTrait)]。

小提醒：自訂派生宏需要熟悉 proc_macro、syn、quote 三個 crate，建議先從簡單的 #[derive] 使用開始，逐步深入。

4. 常見的內建派生宏

派生宏	功能說明	何時使用
`Debug`	允許 `{:?}` 格式化輸出	除錯或日誌
`Clone`	產生深度複製	需要多次使用相同資料
`Copy`	讓類型在語意上是「位元拷貝」	小型、純值型別
`PartialEq` / `Eq`	相等性比較	容器、測試斷言
`PartialOrd` / `Ord`	排序比較	排序、二分搜尋
`Hash`	產生雜湊值	用於 `HashMap`、`HashSet`
`Default`	提供預設值	建構器簡化
`Serialize` / `Deserialize`（serde）	序列化/反序列化	JSON、YAML、二進位

5. 程式碼範例

以下示範 4 個實用的派生宏應用，並在每段程式碼加上說明註解。

範例 1：`Debug` + `Clone` + `PartialEq`

#[derive(Debug, Clone, PartialEq)]
struct User {
    id: u64,
    name: String,
    active: bool,
}

fn main() {
    // 使用 Debug 輸出
    let u1 = User { id: 1, name: "Alice".into(), active: true };
    println!("{:?}", u1); // => User { id: 1, name: "Alice", active: true }

    // 使用 Clone 複製
    let u2 = u1.clone();
    assert_eq!(u1, u2); // PartialEq 讓 assert_eq! 成立
}

範例 2：`Copy` 與 `Default`（適合小型資料）

#[derive(Copy, Clone, Debug, Default)]
struct Coord {
    x: i32,
    y: i32,
}

fn main() {
    // Default 產生 (0,0)
    let origin = Coord::default();
    println!("{:?}", origin); // Coord { x: 0, y: 0 }

    // Copy 讓變數賦值不會移動所有權
    let p1 = origin;
    let p2 = p1; // 仍然可以使用 p1
    println!("{:?} {:?}", p1, p2);
}

範例 3：`serde` 的 `Serialize` / `Deserialize`

use serde::{Serialize, Deserialize};

#[derive(Debug, Serialize, Deserialize)]
struct Config {
    version: String,
    debug: bool,
    max_connections: u32,
}

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // 序列化成 JSON
    let cfg = Config { version: "1.0".into(), debug: true, max_connections: 100 };
    let json = serde_json::to_string_pretty(&cfg)?;
    println!("{}", json);
    // 反序列化回結構體
    let decoded: Config = serde_json::from_str(&json)?;
    assert_eq!(cfg.version, decoded.version);
    Ok(())
}

範例 4：自訂派生宏的簡易示範（`HelloMacro`）

此範例僅示意概念，實作需在 proc-macro crate 中完成。

// 在 proc-macro crate 中
use proc_macro::TokenStream;
use quote::quote;
use syn;

#[proc_macro_derive(HelloMacro)]
pub fn hello_macro_derive(input: TokenStream) -> TokenStream {
    // 解析輸入的型別
    let ast = syn::parse(input).unwrap();
    impl_hello_macro(&ast)
}

fn impl_hello_macro(ast: &syn::DeriveInput) -> TokenStream {
    let name = &ast.ident;
    let gen = quote! {
        impl #name {
            pub fn hello() {
                println!("Hello, {}!", stringify!(#name));
            }
        }
    };
    gen.into()
}

// 在使用者 crate 中
use my_macros::HelloMacro;

#[derive(HelloMacro)]
struct MyStruct;

fn main() {
    MyStruct::hello(); // 輸出: Hello, MyStruct!
}

常見陷阱與最佳實踐

陷阱	說明	解決方案
忘記加 `#[derive(...)]`	編譯時會出現「cannot find trait `X` in this scope」錯誤。	確認 trait 已在 `use` 路徑中，且 `derive` 標註正確。
衝突的 trait 實作	同一型別同時手動實作與 `derive` 同一 trait，會產生重複定義錯誤。	若需要自訂行為，移除 `derive`，自行實作。
`Copy` 必須同時 `Clone`	`Copy` 只能套用在已實作 `Clone` 的型別。	同時加上 `#[derive(Copy, Clone)]`。
`serde` 需要 `#[serde(...)]` 設定	某些欄位的名稱或型別不符合 JSON 規範時會失敗。	使用 `#[serde(rename = "...")]`、`#[serde(skip)]` 等屬性調整。
自訂派生宏的相依版本	`syn`、`quote`、`proc-macro2` 版本不一致會導致編譯錯誤。	盡量使用同一個 `edition = "2021"` 並鎖定相容版本。

最佳實踐

只在需要時才手動實作：盡量依賴 derive，保持程式碼簡潔。
保持 trait 的單一職責：例如 Debug 只用於除錯，避免在 Debug 實作中加入業務邏輯。
使用 #[serde(default)]：在反序列化時避免缺少欄位導致錯誤。
測試自訂派生宏：在 proc-macro crate 中加入單元測試，確保產生的程式碼符合預期。
文件化：對於自訂的派生宏，提供範例與說明，降低其他開發者的學習成本。

實際應用場景

場景	典型使用的派生宏	為什麼需要
API 回傳資料	`Serialize`、`Deserialize`（serde）	JSON/XML 互轉，減少手寫序列化程式碼。
資料庫 ORM	`Deserialize`、`Debug`、`Clone`（diesel、sqlx）	讀寫資料庫時自動映射至結構體。
遊戲開發	`Copy`、`Clone`、`PartialEq`	大量小型向量、座標資料的快速拷貝與比較。
測試斷言	`PartialEq`、`Debug`	`assert_eq!` 需要 `PartialEq`，失敗時顯示 `Debug`。
自訂 DSL / 編譯器	自訂派生宏（如 `HelloMacro`）	為語法樹自動產生訪問者（visitor）或轉換器。

總結

派生宏是 Rust 提供的 編譯期程式碼生成工具，讓開發者可以在不寫冗長樣板的情況下，快速為資料型別實作常用的 trait。

透過 #[derive(...)]，即可取得 Debug、Clone、PartialEq 等基礎功能。
serde 系列的派生宏更是讓序列化/反序列化變得毫不費力。
進階開發者亦可自行建立 proc-macro crate，設計符合專案需求的自訂派生宏。

掌握這些概念與最佳實踐後，你將能在 除錯、測試、資料交換、甚至自訂語言層面 大幅提升開發效率與程式碼品質。祝你在 Rust 的宏世界裡玩得開心，寫出更乾淨、更強大的程式！