Bài 280: derive Macro — Đã Dùng Nhiều

Sau bài học, bạn sẽ:

• Hiểu #[derive(...)] là procedural macro chạy lúc compile để sinh impl block — không phải runtime reflection.
• Liệt kê được 7 trait built-in hay derive (Debug, Clone, Copy, Default, PartialEq, Eq, Hash) và điều kiện áp dụng cho mỗi trait.
• Dùng cargo expand xem chính xác code compiler chèn vào sau khi expand derive.
• Hiểu serde_derive (#[derive(Serialize, Deserialize)]) là proc-macro của bên thứ ba — mô hình giống derive built-in nhưng do crate serde_derive cung cấp.
• Bắt được lỗi compile thường gặp khi println!("{:?}", x) mà quên derive Debug.
• Áp dụng đúng combo #[derive(PartialEq, Eq, Hash)] cho struct làm key của HashMap.
• Biết custom derive macro là gì và tại sao bài này không đi sâu (đã mention ở Bài 279).

#[derive(Trait)] đặt trên struct hoặc enum chỉ thị compiler chạy một procedural macro ứng với Trait. Macro nhận AST của định nghĩa kiểu, sinh ra một impl Trait for KiểuCủaBạn { ... } mới và chèn ngay vào module — kết quả: bạn không phải viết tay impl, không phải bảo trì khi struct đổi field, mà type vẫn có mọi method và behavior của trait.

Khác với reflection ở Java hay Python: derive chạy lúc biên dịch. Code sinh ra là Rust thuần, biên dịch tiếp như mọi code khác, có cùng performance như viết tay. Khi binary chạy, không còn "macro" nào tồn tại — chỉ có impl block đã expand.

Các derive trong stdlib (Debug, Clone, Copy, Default, PartialEq, Eq, Hash, PartialOrd, Ord) được implement nội bộ trong compiler qua một cơ chế built-in để bootstrapping. Còn derive của crate ngoài (serde, thiserror, strum...) đi qua API proc-macro chuẩn — viết bằng Rust trong một crate có proc-macro = true và export hàm có signature fn name(input: TokenStream) -> TokenStream.

7 trait dưới đây gặp gần như mỗi file Rust:

• Debug — format giá trị qua {:?} / {:#?}. Bắt buộc khi println!("{:?}", x), dbg!(x), hay assert macro in giá trị lúc fail. Mọi field phải Debug.
• Clone — sinh method .clone() -> Self để deep-copy. Mọi field phải Clone.
• Copy — marker trait cho bitwise copy ngầm định, không cần gọi .clone(). Yêu cầu đồng thời derive Clone. Mọi field phải Copy (vd primitives, không phải String hay Vec).
• Default — sinh Self::default() trả về instance với mọi field ở giá trị default (0, false, "" cho String, None cho Option). Mọi field phải Default.
• PartialEq — sinh operator == và != bằng cách so sánh từng field. Reflexive không bắt buộc (vd f64::NAN != NAN).
• Eq — marker trait nói "== là quan hệ tương đương đầy đủ" (reflexive + symmetric + transitive). Yêu cầu kèm PartialEq. Cấu trúc chứa f32/f64 không thể derive Eq.
• Hash — sinh method hash() bằng cách feed từng field vào hasher. Bắt buộc kèm Eq theo axiom: a == b ⇒ hash(a) == hash(b). Đây là điều kiện để dùng làm key cho HashMap hay HashSet.

Ngoài 7 trait trên, stdlib còn cho derive PartialOrd và Ord để compare và sort. Cú pháp giống hệt.

Cú pháp đặt attribute ngay trên định nghĩa, kê tên trait trong dấu ngoặc:

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

fn main() {
    let a = Point { x: 1, y: 2 };
    let b = a.clone();
    println!("{:?}", a);          // Point { x: 1, y: 2 }
    println!("{:#?}", b);         // pretty-print multiline
    assert_eq!(a, b);             // PartialEq cho ==
}

Để xem compiler sinh gì, cài cargo expand (xem Bài 273 trong Group Tools) rồi chạy cargo expand:

// Sau cargo expand — code thực sự được compile (rút gọn cho rõ)
struct Point {
    x: i32,
    y: i32,
}

impl ::core::fmt::Debug for Point {
    fn fmt(&self, f: &mut ::core::fmt::Formatter) -> ::core::fmt::Result {
        let mut s = f.debug_struct("Point");
        s.field("x", &self.x);
        s.field("y", &self.y);
        s.finish()
    }
}

impl ::core::clone::Clone for Point {
    fn clone(&self) -> Self {
        Point { x: self.x.clone(), y: self.y.clone() }
    }
}

impl ::core::cmp::PartialEq for Point {
    fn eq(&self, other: &Self) -> bool {
        self.x == other.x && self.y == other.y
    }
}

Đúng như viết tay — không có "magic" runtime nào. Path đầy đủ ::core::... đảm bảo hygiene (tên không clash với type cùng tên trong scope của user).

Pitfall thường gặp: quên derive Debug rồi println!("{:?}", x) sẽ compile error rõ ràng:

error[E0277]: `Point` doesn't implement `Debug`
  --> src/main.rs:10:22
   |
10 |     println!("{:?}", a);
   |                      ^ `Point` cannot be formatted using `{:?}`
   |
   = help: the trait `Debug` is not implemented for `Point`
   = note: add `#[derive(Debug)]` to `Point` or manually `impl Debug for Point`

Fix nhanh: thêm Debug vào danh sách derive. Compiler thậm chí gợi ý chính xác.

serde là crate de facto cho serialization/deserialization. Hai trait Serialize và Deserialize đến từ crate serde, nhưng phần derive được provide bởi crate riêng serde_derive (re-export qua feature derive của serde). Cách dùng:

# Cargo.toml
[dependencies]
serde = { version = "1", features = ["derive"] }
serde_json = "1"

use serde::{Serialize, Deserialize};

#[derive(Serialize, Deserialize, Debug)]
struct User {
    name: String,
    age: u32,
    email: Option<String>,
}

fn main() -> Result<(), serde_json::Error> {
    let u = User {
        name: "An".into(),
        age: 25,
        email: Some("[email protected]".into()),
    };

    let json = serde_json::to_string(&u)?;
    println!("{json}");
    // {"name":"An","age":25,"email":"[email protected]"}

    let back: User = serde_json::from_str(&json)?;
    println!("{:?}", back);
    Ok(())
}

Không có dòng nào tự viết hàm serialize hay parse JSON. #[derive(Serialize)] chạy proc-macro của serde_derive, nhận AST của User, sinh impl Serialize for User với code feed từng field vào Serializer. #[derive(Deserialize)] tương tự với Deserializer. Crate serde_json chỉ cung cấp implementation cụ thể của format JSON — JSON ↔ Rust types tự nhiên ăn khớp nhờ derive.

Đây là minh hoạ rõ nhất cho sức mạnh của derive macro: bạn không cần biết bên trong serde_derive làm gì để dùng nó hằng ngày. Code của bạn vẫn 100% type-safe vì impl được generate tại compile time, mọi mismatch field hay type báo lỗi như mọi code Rust khác.

HashMap<K, V> yêu cầu K: Eq + Hash (và Eq kéo theo PartialEq). Custom struct làm key phải derive đủ ba:

use std::collections::HashMap;

#[derive(Debug, PartialEq, Eq, Hash)]
struct Coord {
    x: i32,
    y: i32,
}

fn main() {
    let mut grid: HashMap<Coord, &str> = HashMap::new();
    grid.insert(Coord { x: 0, y: 0 }, "origin");
    grid.insert(Coord { x: 1, y: 2 }, "target");

    let key = Coord { x: 1, y: 2 };
    println!("{:?}", grid.get(&key)); // Some("target")
}

Nếu thiếu một trait, compile error rất cụ thể:

error[E0277]: the trait bound `Coord: Hash` is not satisfied
  --> src/main.rs:11:14
   |
11 |     grid.insert(Coord { x: 0, y: 0 }, "origin");
   |          ^^^^^^ the trait `Hash` is not implemented for `Coord`
   = help: consider annotating `Coord` with `#[derive(Hash)]`

Pitfall: struct có field f32 hoặc f64 không thể derive Eq (vì NaN != NaN phá axiom reflexivity). Muốn dùng làm key, hoặc đổi sang số nguyên (vd nhân lên rồi cast thành i64), hoặc dùng wrapper như ordered-float::NotNan<f64>.

Một axiom phải tôn trọng khi viết tay (derive tự đảm bảo): a == b ⇒ hash(a) == hash(b). Nếu impl tay Hash mà bỏ qua field nào đó dùng trong PartialEq, hai key "bằng nhau" có thể rơi vào bucket khác → HashMap không tìm thấy entry. Bug rất khó debug — lý do tốt nhất để luôn derive cả ba cùng lúc, để compiler giữ đồng bộ.

Ngoài derive built-in của stdlib và serde, bạn có thể viết derive của riêng bạn để auto-generate impl cho trait do bạn định nghĩa. Ví dụ thực tế: #[derive(Error)] của thiserror (Bài 149), #[derive(Builder)] của derive_builder, #[derive(EnumIter)] của strum. Cách hoạt động giống derive built-in: tạo crate riêng có proc-macro = true trong Cargo.toml, export hàm với signature TokenStream → TokenStream, dùng syn + quote để parse AST và sinh code.

Chủ đề này đã được giới thiệu tổng quan ở Bài 279: Procedural Macros — 3 Loại Overview. Implement chi tiết một custom derive là nội dung nâng cao — đòi hỏi hiểu sâu về parsing token, ergonomics API của syn, và quirks của hygiene xuyên-crate. Series Rust Cơ Bản chỉ dừng ở mức "biết khi nào nên reach for custom derive (rất hiếm) và biết những crate phổ biến đã làm sẵn cho bạn".

Quy tắc thực dụng: dùng derive macro của crate có sẵn trước; chỉ viết custom derive khi pattern code lặp lại nhiều struct trong codebase, và viết tay quá tốn công. 99% project Rust không bao giờ cần custom derive — built-in stdlib + serde + thiserror đủ phủ hầu hết trường hợp.

• #[derive(...)] là procedural macro — chạy lúc compile, sinh impl block, không phải runtime reflection.
• 7 trait built-in hay derive: Debug, Clone, Copy, Default, PartialEq, Eq, Hash (+ PartialOrd, Ord).
• Mỗi trait yêu cầu mọi field đã impl trait đó. Copy yêu cầu kèm Clone; Eq yêu cầu kèm PartialEq; Hash thường đi kèm Eq cho axiom a == b ⇒ hash(a) == hash(b).
• cargo expand cho thấy code thực được sinh — Rust thuần, không magic, có path đầy đủ ::core::... để hygiene.
• serde_derive là proc-macro của bên thứ ba — cùng cơ chế derive built-in, sinh impl Serialize/Deserialize. Cần feature derive của crate serde.
• Quên derive Debug → compile error rõ ràng, kèm gợi ý fix. println!("{:?}", x) yêu cầu Debug.
• HashMap/HashSet key cần đủ PartialEq + Eq + Hash. Struct chứa f32/f64 không derive được Eq.
• Custom derive macro (viết tool riêng): chỉ cần khi pattern lặp nhiều — built-in + serde + thiserror đủ cho hầu hết project.

Tự trả lời, đáp án ở cuối:

1. Vì sao Rust không có runtime reflection như Java/Python nhưng vẫn cho phép println!("{:?}", x) in struct mà bạn không tự viết code format? Cơ chế đằng sau là gì?
2. Struct User { name: String, age: u32 } derive được Copy không? Vì sao? Nếu không, giải pháp để vẫn dễ pass-by-value là gì?
3. Bạn có struct Sample { value: f64 } và muốn dùng làm key trong HashMap. Compiler báo lỗi gì? Có 2 cách workaround — nêu cả 2.
4. Khi nào nên derive Eq mà không cần derive PartialEq kèm? (Trick question.)
5. Bạn impl tay Hash cho struct và "tối ưu" bằng cách chỉ feed 1 trong 3 field vào hasher. PartialEq bạn derive (so sánh cả 3 field). HashMap hoạt động "bình thường" nhưng đôi khi .get(&key) trả None dù key giống hệt entry đã insert. Nguyên nhân và fix?
6. Crate serde_derive được cài như thế nào trong Cargo.toml (chỉ thêm serde hay phải thêm cả serde_derive)? Vì sao thiết kế như vậy?

Bài 281: Macro Hygiene — Namespace Clean — Khám phá tại sao macro của Rust an toàn hơn macro của C/C++: scope identifier không leak ra ngoài macro, không clash với tên biến nơi gọi. Đây là property khiến macro_rules! trở thành công cụ đáng tin cậy, hoàn toàn khác với #define dễ gây bug khó debug trong C. Bài cuối Group 34 trước khi sang Group 35 Unsafe Rust.