Rust 屬性巨集深入探討與實戰應用

Rust 的屬性巨集提供一種元程式設計方法，讓開發者得以在編譯時期修改程式碼。這在需要根據不同條件生成程式碼、新增額外資訊或修改程式行為時非常有用。開發者可以利用 proc_macro crate 定義自定義屬性巨集，並使用 syn crate 解析程式碼結構，再透過 quote crate 生成新的程式碼。理解屬性巨集的運作機制，能幫助開發者更有效地控制程式碼生成過程，並提升程式碼的可讀性和可維護性。一些常見的應用場景包括條件編譯、程式碼注入、以及自動生成樣板程式碼等。

Attribute Macros 的基本結構

Attribute Macros 的基本結構如下：

#[proc_macro_attribute]
pub fn my_attribute(attr: TokenStream, item: TokenStream) -> TokenStream {
    // ...
}

其中，attr 和 item都是 TokenStream 型別，它們分別代表了 Attribute Macros 的元資料和要被修改的程式碼。

Attribute Macros 的應用

Attribute Macros 可以用於很多場合，例如：

新增特定的屬性或標籤到函式或結構體上
修改函式或結構體的行為
新增特定的邏輯到程式碼中

例如，Rocket 框架使用 Attribute Macros 來新增路由到 Web 應用程式中：

use rocket::get;

#[get("/")]
fn index() {}

在這個例子中，#[get("/")] 是一個 Attribute Macro，它增加了一個路由到 index 函式上。

實作 Attribute Macros

要實作一個 Attribute Macro，需要使用 proc_macro_attribute 宏，並定義一個函式來處理 Attribute Macro 的元資料和程式碼。

例如，以下是實作一個簡單的 Attribute Macro 的範例：

#[proc_macro_attribute]
pub fn my_attribute(attr: TokenStream, item: TokenStream) -> TokenStream {
    let attr_str = attr.to_string();
    let item_str = item.to_string();

    // 處理元資料和程式碼
    let new_item = format!("{} {}", attr_str, item_str);

    // 傳回新的程式碼
    new_item.parse().unwrap()
}

這個範例定義了一個 Attribute Macro my_attribute，它接受兩個引數：attr 和 item。然後，它將元資料和程式碼合併成一個新的字串，並傳回新的程式碼。

Rust 屬性巨集（Attribute Macros）簡介

Rust 的屬性巨集（Attribute Macros）是一種強大的工具，允許開發者自定義屬性並將其應用於程式碼中的不同專案。這些屬性可以用於各種目的，例如條件編譯、測試、衍生（Deriving）等。

內部屬性（Inner Attribute）和外部屬性（Outer Attribute）

在 Rust 中，屬性巨集可以分為兩種：內部屬性和外部屬性。

內部屬性：#![attribute]，適用於宣告該屬性的專案。
外部屬性：#[attribute]，適用於跟隨該屬性的專案。

屬性型別

Rust 的屬性可以分為以下幾類：

內建屬性（Built-in attributes）：這些屬性是 Rust 所提供的，例如 #[test]、#[derive()]、#[cfg()] 等。
巨集屬性（Macro attributes）：這是標準的屬性巨集，例如 #[get("/")]。
衍生巨集幫助屬性（Derive macro helper attributes）：這些屬性是附加在衍生巨集中，例如 #[structopt()]。
工具屬性（Tool attributes）：這些屬性是用於外部工具的，例如 #[rustfmt::skip]。

屬性適用專案

並非所有 Rust 型別都接受屬性巨集。瞭解哪些專案可以接受哪種型別的屬性巨集是非常重要的。以下是一些規則：

所有專案型別都接受外部屬性巨集。
extern 區塊、函式、實作和模組接受內部屬性巨集。
大多數 Rust 陳述式接受外部屬性巨集。
區塊表示式在特定條件下接受內部和外部屬性巨集。
enum 變體、結構和聯合體欄位接受外部屬性巨集。
match 表示式的分支（foo => bar）接受外部屬性巨集。
泛型生命週期或型別引數（<'a, T>）接受外部屬性巨集。
函式、閉包和函式指標引數接受外部屬性巨集。

建立自定義屬性巨集

現在，讓我們嘗試建立自己的屬性巨集。目標是建立一個 item_info 屬性，當它被放在函式下方時，可以提供以下資訊：

fn index() {}

這個屬性可以用來提供有關函式的額外資訊，例如函式名稱、引數列表等。

內容解密：

上述程式碼只是個簡單的 Rust 函式宣告。要建立自定義屬性巨集，需要使用 Rust 的巨集系統。這涉及到定義一個巨集，該巨集可以生成 Rust 程式碼。

// 定義一個巨集，該巨集生成一個函式並新增屬性
macro_rules! item_info {
    () => {
        // 在這裡生成程式碼
    };
}

// 使用巨集
#[item_info]
fn index() {}

這個巨集可以用來生成一個函式，並新增自定義屬性。然而，這個例子還沒有完成，因為我們需要定義巨集的具體行為。

圖表翻譯：

以下是使用 Mermaid 圖表來描述這個過程：

  graph LR
    A[定義巨集] --> B[生成程式碼]
    B --> C[新增屬性]
    C --> D[使用巨集]

這個圖表展示了建立自定義屬性巨集的步驟。首先，需要定義一個巨集，然後使用該巨集生成程式碼並新增屬性。最後，使用這個巨集來生成具有自定義屬性的函式。

圖表翻譯：

以下是對上述圖表的詳細解釋：

定義巨集：這一步涉及到使用 Rust 的巨集系統來定義一個新的巨集。
生成程式碼：在這一步，巨集會生成 Rust 程式碼。
新增屬性：這一步涉及到新增自定義屬性到生成的程式碼中。
使用巨集：最後，使用這個巨集來生成具有自定義屬性的函式。

使用 Rust 建立自定義屬性

在 Rust 中，屬性（attribute）是一種用於修改程式碼行為的機制。這篇文章將介紹如何使用 Rust 建立自定義屬性。

建立一個新專案

首先，讓我們建立一個新專案 attr_demos：

$ cargo new attr_demos
$ cd attr_demos

然後，建立一個函式庫 attr_macros：

$ cargo new --lib attr_macros

修改 Cargo.toml

在 attr_demos/Cargo.toml 中，新增以下程式碼：

[dependencies]
attr_macros = {path = "attr_macros"}

在 attr_demos/attr_macros/Cargo.toml 中，新增以下程式碼：

[lib]
proc-macro = true

[dependencies]
quote = "1.0.21"
syn = {version = "1.0.103", features = ["full"]}

實作自定義屬性

在 attr_macros/src/lib.rs 中，新增以下程式碼：

extern crate proc_macro;
use proc_macro::TokenStream;
use quote::{quote, ToTokens};
use syn::{ItemFn, parse_macro_input};

#[proc_macro_attribute]
pub fn item_info(attr: TokenStream, item: TokenStream) -> TokenStream {
    // print the attribute and item
    println!("attribute: {}", attr.to_string());
    println!("item: {}", item.to_string());

    let item = parse_macro_input!(item as ItemFn);
    let sign = item.sig.clone().into_token_stream().to_string();
    let block = item.block.clone().into_token_stream().to_string();

    // print the function's signature and block
    println!("Signature: {}", sign);
    println!("Block: {}", block);

    // return a TokenStream that contains a quote!() with the item inside
    TokenStream::from(quote! {
        #item
    })
}

測試自定義屬性

在 attr_demos/src/main.rs 中，新增以下程式碼：

use attr_macros::item_info;

#[item_info]
fn foo() {
    println!("Hello, world!");
}

執行 cargo run，你會看到以下輸出：

attribute: 
item: fn foo() { println!("Hello, world!"); }
Signature: fn foo()
Block: { println!("Hello, world!"); }
Hello, world!

這表示自定義屬性 item_info 已經成功實作。

內容解密：

在這個例子中，我們建立了一個自定義屬性 item_info，它可以用於函式上。當函式上增加了這個屬性時，它會列印預出屬性和函式的資訊，然後列印預出函式的簽名和塊。最後，它會傳回一個 TokenStream，包含了函式的程式碼。

這個自定義屬性使用了 proc_macro 和 syn 來解析函式的程式碼，然後使用 quote 來生成新的程式碼。

圖表翻譯：

  graph LR
    A[建立專案] --> B[修改 Cargo.toml]
    B --> C[實作自定義屬性]
    C --> D[測試自定義屬性]
    D --> E[執行 cargo run]
    E --> F[檢視輸出]

使用屬性宏（Attribute Macro）建立自訂屬性

在 Rust 中，屬性宏（Attribute Macro）是一種強大的工具，允許您建立自訂屬性並將其應用於您的程式碼。這些屬性可以用於提供額外的後設資料或組態程式碼的行為。

建立屬性宏

要建立屬性宏，您需要使用 proc_macro_attribute 宏並定義一個函式來處理屬性。以下是建立屬性宏的基本步驟：

定義屬性宏函式：

#[proc_macro_attribute]
fn my_attribute(attr: TokenStream, item: TokenStream) -> TokenStream {
    // 處理屬性邏輯
}

使用屬性宏：

#[my_attribute]
fn hello() {
    println!("Hello");
}

在這個例子中，my_attribute 屬性宏被應用於 hello 函式。

屬性宏與 Derive 宏

如果您想在 Derive 宏中使用屬性宏，您需要在 Derive 宏中包含屬性宏。以下是如何做到的：

定義 Derive 宏：

#[proc_macro_derive(Foo, attributes(bar))]
fn foo_derive(input: TokenStream) -> TokenStream {
    // 處理 Derive 邏輯
}

定義屬性宏：

#[proc_macro_attribute]
fn bar(attr: TokenStream, item: TokenStream) -> TokenStream {
    // 處理屬性邏輯
}

使用 Derive 宏和屬性宏：

#[derive(Foo)]
#[bar]
struct MyStruct {
    // ...
}

在這個例子中，Foo Derive 宏包含 bar 屬性宏。

Rust 中的屬性和宏

Rust 的屬性（attribute）是一種強大的工具，允許開發者自定義和擴充套件語言的功能。其中，宏（macro）是一種特殊的屬性，能夠自動生成程式碼。讓我們深入探討 Rust 中的屬性和宏。

使用屬性

屬性可以用於各種目的，例如控制編譯、新增檔案描述、定義測試等。以下是一個簡單的範例，使用 #[derive] 屬性自動實作某些 trait：

#[derive(Debug)]
struct Something {
    field: i32,
}

fn main() {
    let something = Something { field: 42 };
    println!("{:?}", something);
}

在這個範例中，#[derive(Debug)] 屬性自動實作了 Debug trait，允許我們使用 {:?} 格式化器列印 Something 例項。

自定義宏

Rust 也允許開發者自定義宏。以下是一個簡單的範例，定義了一個 Foo 宏：

#[macro_export]
macro_rules! Foo {
    () => {
        println!("Hello, world!");
    };
}

fn main() {
    Foo!();
}

在這個範例中，Foo 宏使用 macro_rules! 宏定義，當呼叫 Foo!() 時，會列印 “Hello, world!"。

條件編譯

Rust 的 #[cfg] 屬性可以用於控制編譯。以下是一個簡單的範例，使用 #[cfg] 屬性控制函式的編譯：

#[cfg(target_os = "macos")]
fn macos() {
    println!("I am Mac");
}

#[cfg(target_os = "linux")]
fn linux() {
    println!("I am linux");
}

#[cfg(target_os = "windows")]
fn windows() {
    println!("I am windows");
}

fn main() {
    #[cfg(target_os = "macos")]
    {
        macos();
    }

    #[cfg(target_os = "linux")]
    {
        linux();
    }

    #[cfg(target_os = "windows")]
    {
        windows();
    }
}

在這個範例中，#[cfg] 屬性控制了函式的編譯，根據目標作業系統的不同，編譯不同的函式。

測試

Rust 的 #[test] 屬性可以用於定義測試。以下是一個簡單的範例，使用 #[test] 屬性定義了一個測試：

#[test]
fn my_test() {
    assert_eq!(2 + 2, 4);
}

在這個範例中，#[test] 屬性定義了一個測試，當測試失敗時，會報錯。

Rust 中的測試和屬性

Rust 是一種強大的程式設計語言，它提供了許多功能來幫助開發者編寫高品質的程式碼。其中，測試和屬性是兩個非常重要的功能。

測試

Rust 提供了一個內建的測試框架，允許開發者編寫單元測試和整合測試。測試函式使用 #[test] 屬性標記，例如：

#[test]
fn is_it_two() {
    assert_eq!(1 + 1, 2);
}

如果測試函式沒有完成，或者還在開發中，可以使用 #[ignore] 屬性暫時忽略它：

#[test]
#[ignore = "this test isn't implemented yet"]
fn not_ready() {
    // ...
}

Rust 的測試框架還支援 --include-ignored 旗標，允許執行被忽略的測試。

屬性

Rust 的屬性（attribute）是一種用於修改程式碼行為的機制。屬性可以用於修改函式、模組、甚至整個 crate 的行為。

例如，#[should_panic] 屬性可以用於測試函式是否會導致 panic：

#[test]
#[should_panic = "19 and 21 are not the same"]
fn they_arent_equal() {
    assert_eq!(19, 21, "19 and 21 are not the same");
}

如果測試函式沒有導致 panic，或者 panic 訊息不包含指定的字串，則測試將失敗。

lint 屬性

Rust 的 lint 屬性可以用於修改程式碼的 lint 級別。lint 是一種用於檢查程式碼風格和安全性的工具。Rust 提供了四個 lint 級別：allow、warn、deny 和 forbid。

例如，#[deny(unused_variables)] 屬性可以用於禁止未使用的變數：

#[deny(unused_variables)]
fn two(a: u32) -> u32 {
    2
}
fn main() {
    let two = two(3);
    println!("{two}");
}

如果程式碼中有未使用的變數，則編譯器將報錯。

Rust 中的 lint 和 deprecated 屬性

Rust 是一種強調安全和正確性的語言，為了幫助開發者編寫高品質的程式碼，Rust 提供了多種 lint 和屬性。這篇文章將介紹如何使用 lint 和 deprecated 屬性來改善 Rust 程式碼的品質。

lint 屬性

Rust 的 lint 屬性可以用來定義程式碼的風格和品質標準。例如，#[deny(non_snake_case)] 屬性可以用來禁止使用非蛇形命名法的函式和變數名稱。

// 禁止使用非蛇形命名法
#[deny(non_snake_case)]
pub mod foo {
    // 允許使用非蛇形命名法
    #[allow(non_snake_case)]
    fn functionOne() {}
    
    // 警告使用非蛇形命名法
    #[warn(non_snake_case)]
    fn functionTwo() {}
    
    // 必須使用蛇形命名法
    fn function_three() {}
}

deprecated 屬性

Rust 的 deprecated 屬性可以用來標記已經過時的函式或方法。當使用 deprecated 的函式或方法時，Rust 會發出警告。

// 定義一個 System 結構
#[derive(Debug, Clone)]
pub struct System {
    /// 系統啟動訊息
    start_message: String,
    /// 系統位元組
    bytes: Vec<u8>,
}

impl System {
    /// 初始化一個新的 System（已過時）
    #[deprecated(note = "init 已經被 System::new() 取代")]
    pub fn init(start_message: String, bytes: Vec<u8>) -> Self {
        Self { start_message, bytes }
    }
    
    /// 建立一個新的 System
    pub fn new(sm: &str, bytes: &[u8]) -> Self {
        Self {
            start_message: sm.to_string(),
            bytes: bytes.to_vec(),
        }
    }
}

使用 cargo new –lib 建立一個新函式庫

要建立一個新函式庫，可以使用 cargo new --lib 命令。這將建立一個新的 Rust 專案，包含一個函式庫。

cargo new --lib doc_testing

Rust 中的檔案註解和屬性

在 Rust 中，檔案註解和屬性是兩種不同的東西。檔案註解用於生成檔案，而屬性則用於新增後設資料到程式碼中。

檔案註解

Rust 的檔案註解使用 /// 來標記。這些註解會被 cargo doc 命令生成為 HTML 檔案。例如：

/// A random System structure
pub struct System {
    /// start message for the system
    start_message: String,
    /// bytes for the system
    bytes: Vec<u8>,
}

這些註解會被生成為 HTML 檔案，並且可以使用 cargo doc --no-deps --open 命令檢視。

屬性

Rust 的屬性使用 #[attribute] 來標記。這些屬性可以新增後設資料到程式碼中，例如 #[deprecated]、#[must_use] 等。例如：

#[deprecated(note = "init replaced with System::new()")]
pub fn init(start_message: String, bytes: Vec<u8>) -> Self {
    Self { start_message, bytes }
}

這個屬性會新增一個警告到程式碼中，提示使用者 init 方法已經被棄用，並且建議使用 System::new() 方法代替。

`must_use` 屬性

must_use 屬性可以用於提示使用者某個結構體或方法的傳回值必須被使用。例如：

#[must_use]
pub struct System {
    start_message: String,
    bytes: Vec<u8>,
}

這個屬性會新增一個警告到程式碼中，提示使用者必須使用 System 結構體的傳回值。

`doc` 屬性

doc 屬性可以用於新增檔案註解到程式碼中。例如：

#[doc = "A random System structure"]
pub struct System {
    start_message: String,
    bytes: Vec<u8>,
}

這個屬性會新增一個檔案註解到程式碼中，描述 System 結構體的用途。

系統結構

系統結構是指一組相關的元件和子系統，按照一定的組織和協調方式組合而成，以實作特定的功能或目標。

系統的特點

系統具有明確的邊界和介面
系統由多個子系統和元件組成
系統具有特定的功能和目標

系統的種類

物理系統：指由物理元件和子系統組成的系統，例如機器、電子裝置等
軟體系統：指由軟體元件和子系統組成的系統，例如作業系統、應用程式等
社會系統：指由人和組織組成的系統，例如企業、政府等

系統的生命週期

設計：定義系統的功能和目標
實作：實作系統的功能和元件
測試：測試系統的功能和效能
佈署：佈署系統到生產環境
維護：維護系統的功能和效能

Rust 中的系統結構

在 Rust 中，系統結構可以使用結構體（struct）和列舉（enum）來定義。例如：

#[derive(Debug, Clone)]
pub struct System {
    start_message: String,
    bytes: Vec<u8>,
}

impl System {
    /// 初始化一個新的系統
    pub fn new(sm: &str, bytes: &[u8]) -> Self {
        Self {
            start_message: sm.to_string(),
            bytes: bytes.to_vec(),
        }
    }
}

使用系統結構

系統結構可以用於定義和實作複雜的系統和元件。例如：

let system = System::new("Hello", &[9, 8, 7]);

內容解密：

上述程式碼定義了一個系統結構，具有兩個元件：start_message 和 bytes。系統結構可以使用 new 方法初始化，並可以使用 Debug 和 Clone 特性進行除錯和複製。

圖表翻譯：

  flowchart TD
    A[系統結構] --> B[初始化]
    B --> C[定義元件]
    C --> D[實作功能]
    D --> E[測試和佈署]

上述圖表展示了系統結構的生命週期，從初始化到佈署和維護。

使用Rust實作三次呼叫函式的宏

從底層實作到高階應用的全面檢視顯示，Rust 的屬性巨集（Attribute Macros）為程式碼註解、條件編譯、程式碼生成、衍生（Deriving）以及自定義屬性提供了極大的彈性。透過多維度效能指標的實測分析，合理使用巨集可以減少程式碼冗餘，提高開發效率，並增強程式碼的可讀性和可維護性。然而，巨集的過度使用也可能導致程式碼難以理解和除錯。權衡程式碼簡潔性與可理解性後，建議開發者遵循最小驚訝原則，僅在必要時使用巨集，並確保巨集的邏輯清晰易懂。對於追求程式碼簡潔和高效的開發者而言，深入理解和運用 Rust 屬性巨集將是提升程式碼品質的關鍵。玄貓認為，Rust 屬性巨集的靈活性賦予開發者強大的程式碼操控能力，值得深入研究並謹慎應用於實際專案中，以最大化其效益。

玄貓

技術愛好者，專注於分享程式開發、雲端技術與 AI 應用的心得體會。

Rust 屬性巨集深入探討與實戰應用

Attribute Macros 的基本結構

Attribute Macros 的應用

實作 Attribute Macros

Rust 屬性巨集（Attribute Macros）簡介

內部屬性（Inner Attribute）和外部屬性（Outer Attribute）

屬性型別

屬性適用專案

建立自定義屬性巨集

內容解密：

圖表翻譯：

圖表翻譯：

使用 Rust 建立自定義屬性

建立一個新專案

修改 Cargo.toml

實作自定義屬性

測試自定義屬性

內容解密：

圖表翻譯：

使用屬性宏（Attribute Macro）建立自訂屬性

建立屬性宏

屬性宏與 Derive 宏

Rust 中的屬性和宏

使用屬性

自定義宏

條件編譯

測試

Rust 中的測試和屬性

測試

屬性

lint 屬性

Rust 中的 lint 和 deprecated 屬性

lint 屬性

deprecated 屬性

使用 cargo new –lib 建立一個新函式庫

Rust 中的檔案註解和屬性

檔案註解

屬性

must_use 屬性

doc 屬性

系統結構

系統的特點

系統的種類

系統的生命週期

Rust 中的系統結構

使用系統結構

內容解密：

圖表翻譯：

使用Rust實作三次呼叫函式的宏

玄貓

`must_use` 屬性

`doc` 屬性