Rust手続き型マクロ:synとquoteで作るカスタムDeriveマクロ入門

Programming tutorial - IT technology blog
Programming tutorial - IT technology blog

現実の課題:増え続けるボイラープレートコードの負担

規模が拡大するRustのコードベースにおいて、ほぼ確実に直面するのがトレイト実装の重複問題です。例えば、50個のドメインモデル、データベースエンティティ、APIペイロードが存在するシステムを想像してみてください。監査ログ、テレメトリイベント、コンプライアンスチェックなどのために、各構造体は実行時に自身のフィールド情報を記述する必要があります。多くの場合、これは値をキー・バリューのペアにダンプしたり、構造化されたサマリー辞書を構築したりすることで行われます。

モデルが2つ程度しかない段階であれば、手作業で実装しても特に問題ないように思えます。

pub trait DescribeModel {
    fn describe(&self) -> Vec<(&'static str, String)>;
}

struct UserProfile {
    username: String,
    email: String,
    sign_in_count: u32,
}

impl DescribeModel for UserProfile {
    fn describe(&self) -> Vec<(&'static str, String)> {
        vec![
            ("username", self.username.clone()),
            ("email", self.email.clone()),
            ("sign_in_count", self.sign_in_count.to_string()),
        ]
    }
}

しかし、半年後を考えてみましょう。プロジェクトは80個の構造体を抱え、ビジネスロジックは12,000行に膨れ上がっています。ある開発者がUserProfileにphone_numberフィールドを追加したものの、describe()の更新を忘れ、そのままプルリクエストがコードレビューを通過してしまいました。テストは依然として成功します。手作業で構築された文字列リテラルのリストが構造体の定義と一致しているかどうかを、Rustは追跡してくれないからです。ステージング環境でダウンストリームのテレメトリが静かに停止したとき、エンジニアはリポジトリ全体に散らばる何十ものほぼ同一の実装を調査するために何時間も費やすことになります。

根本原因の分析:手動の抽象化が破綻する理由

Rustは意図的にランタイムリフレクションを排除しています。JavaのClass.getDeclaredFields()やGoのreflectパッケージとは異なり、Rustはゼロコスト抽象化、予測可能なメモリレイアウト、そしてガベージコレクタなしでのメモリリークのない実行を保証するために、コンパイル時にフィールド名や構造体のレイアウト情報を削ぎ落とします。

コンパイルされたバイナリには実行時の型メタデータが一切残らないため、どのようなイントロスペクション(型情報の検査)であっても事前の登録が必要です。手作業によるトレイト実装に頼ると、主に3つのリスクが生じます。

  • 情報の冗長性:構造体で一度フィールド名を定義した上で、トレイトの実装ブロック内でも再度記述する必要があります。
  • サイレントなスキーマ乖離:フィールドの追加、リネーム、削除を行っても、別個に存在するトレイトコード側でコンパイラエラーが発生することはありません。
  • リファクタリングのオーバーヘッド:単純なスキーマ変更であっても、何十ものファイルを対象にした退屈でエラーの起きやすい置換作業に発展します。

ここで必要となるのがコンパイル時メタプログラミングです。コンパイラがコンパイル処理中に構造体のトークンを解析し、必要なトレイトのロジックをその場で動的に生成するべきです。

解決策の比較:最適な自動化戦略の選定

Rustの開発チームがこの重複を解消する際、通常は以下の3つのアプローチが検討されます。

1. 宣言的マクロ(macro_rules!)

宣言的マクロは構文のパターンマッチングに依存します。小さなヘルパーラッパーには適していますが、任意の構造体定義を扱うのは困難です。

  • メリット:rustcに直接組み込まれており、追加の依存関係が不要で、コンパイルが非常に高速。
  • デメリット:コードベースの他の場所で定義された構造体を検査できない。カスタムヘルパー属性との連携が難しい。マッチングが複雑になると急速に可読性が低下する。

2. build.rs によるコード生成

もう1つの選択肢は、カスタムのbuild.rsスクリプトや外部のコード生成ツールを実行する方法です。Protobuf定義やJSON Schemaなどのスキーマ仕様を読み取り、OUT_DIRに.rsソースファイルを出力します。

  • メリット:言語に依存しない。Python、Go、Rustなどの複数サービス間でデータ定義を共有する場合に適している。
  • デメリット:IDEの型ヒントや自動補完が効きにくくなる。外部ツールの依存関係が増加する。日常的なローカル開発サイクルの軽快さが損なわれる。

3. 手続き型Deriveマクロ(syn + quote)

手続き型Deriveマクロを使用すると、任意の構造体に#[derive(DescribeModel)]を付与できるようになります。コンパイル時、rustcは構造体の抽象構文木(AST)をトークンストリームとしてマクロクレートに渡します。マクロはそのトークンを変換し、生成されたトレイト実装をそのままコンパイラのパイプラインへと戻します。

  • メリット:呼び出し側がシンプル(#[derive(...)]を追加するだけ)。完全な型チェックが行われる。型が不一致の場合は正確なソースコード位置を示して即座にコンパイルエラーを発生させる。
  • デメリット:専用のproc-macroクレートが必要。synなどの構文解析依存クレートのコンパイルにより、初回コールドビルドに約2〜4秒の時間が追加される。

推奨アプローチ:synとquoteを用いたカスタムDeriveマクロの構築

拡張性と保守性の観点から、手続き型Deriveマクロは最も優れたエルゴノミクス(使いやすさ)を提供します。ここでは、生のトークンストリームを構造化された構文木に解析するためにsynを使用し、そのノードをRustコードへと再構成するためにquoteを使用します。

ステップ1:ワークスペースのセットアップ

Rustでは、手続き型マクロはproc-macro = trueが有効化された専用のライブラリクレート内に配置する必要があります。マクロ本体とテスト用の利用側クレートを共存させるために、Cargoワークスペースをセットアップします。

mkdir derive_demo && cd derive_demo
cargo new --lib describe_derive
cargo new describe_consumer

ルートのCargo.tomlで、両方のクレートをリンクします。

[workspace]
members = ["describe_derive", "describe_consumer"]

describe_derive/Cargo.tomlを設定して、このクレートを手続き型マクロとして宣言し、構文解析に必要なエコシステムを導入します。

[package]
name = "describe_derive"
version = "0.1.0"
edition = "2021"

[lib]
proc-macro = true

[dependencies]
syn = { version = "2.0", features = ["extra-traits"] }
quote = "1.0"
proc-macro2 = "1.0"

ステップ2:手続き型マクロのエントリポイントの定義

describe_derive/src/lib.rsを開きます。手続き型Deriveマクロには、#[proc_macro_derive(TraitName)]が付与されたエントリポイント関数が必要です。このエントリポイントはコンパイラのトークンストリームを受け取り、生成されたコードを含む新しいトークンストリームを返します。

use proc_macro::TokenStream;
use quote::quote;
use syn::{parse_macro_input, DeriveInput};

#[proc_macro_derive(DescribeModel)]
pub fn describe_model_derive(input: TokenStream) -> TokenStream {
    // コンパイラのトークンをAST表現に解析
    let ast = parse_macro_input!(input as DeriveInput);

    // トレイトの実装を生成
    let expanded = impl_describe_model(&ast);

    // 生成されたトークンをコンパイラに返却
    TokenStream::from(expanded)
}

ステップ3:ASTの走査とquoteによるコードの出力

次に、describe_derive/src/lib.rsでASTの検査処理を実装します。マクロは、対象が名前付きフィールドを持つ構造体であることを検証し、各フィールドの識別子をイテレートして、詳細情報を表すタプルを生成する必要があります。

use syn::{Data, Fields};

fn impl_describe_model(ast: &syn::DeriveInput) -> proc_macro2::TokenStream {
    let name = &ast.ident;

    // 名前付きフィールドを持つ構造体のみに導出を制限
    let fields = match &ast.data {
        Data::Struct(data_struct) => match &data_struct.fields {
            Fields::Named(fields_named) => &fields_named.named,
            _ => {
                return syn::Error::new_spanned(
                    ast,
                    "DescribeModelは名前付きフィールドを持つ構造体のみをサポートしており、タプル構造体やユニット構造体には対応していません",
                )
                .to_compile_error();
            }
        },
        _ => {
            return syn::Error::new_spanned(
                ast,
                "DescribeModelは構造体にのみ導出可能であり、enumやunionには対応していません",
            )
            .to_compile_error();
        }
    };

    // 各フィールドに対するタプル式を生成
    let field_descriptions = fields.iter().map(|f| {
        let field_ident = f.ident.as_ref().unwrap();
        let field_name_str = field_ident.to_string();

        quote! {
            (#field_name_str, format!("{:?}", self.#field_ident))
        }
    });

    // 完全なトレイト実装ブロックを構築
    quote! {
        impl DescribeModel for #name {
            fn describe(&self) -> Vec<(&'static str, String)> {
                vec![
                    #(#field_descriptions),*
                ]
            }
        }
    }
}

式 #(#field_descriptions),* は、quoteに組み込まれている繰り返し構文を使用しています。これはmacro_rules!における繰り返しと非常によく似ており、イテレータを展開してvec![]リテラル内にカンマ区切りのトークンシーケンスを生成します。

ステップ4:作成したカスタムDeriveマクロの利用

describe_consumer/Cargo.tomlに、依存関係としてderiveクレートを追加します。

[package]
name = "describe_consumer"
version = "0.1.0"
edition = "2021"

[dependencies]
describe_derive = { path = "../describe_derive" }

続いて、describe_consumer/src/main.rs内でトレイトを宣言し、カスタムDeriveマクロの動作をテストします。

use describe_derive::DescribeModel;

pub trait DescribeModel {
    fn describe(&self) -> Vec<(&'static str, String)>;
}

#[derive(Debug, DescribeModel)]
struct OrderPayload {
    order_id: u64,
    customer_ref: String,
    is_completed: bool,
}

#[derive(Debug, DescribeModel)]
struct ServerConfig {
    host: String,
    port: u16,
}

fn main() {
    let order = OrderPayload {
        order_id: 94821,
        customer_ref: String::from("ACME-CORP"),
        is_completed: false,
    };

    let config = ServerConfig {
        host: String::from("127.0.0.1"),
        port: 8080,
    };

    println!("--- 注文情報 ---");
    for (field, value) in order.describe() {
        println!("{field}: {value}");
    }

    println!("\n--- 設定情報 ---");
    for (field, value) in config.describe() {
        println!("{field}: {value}");
    }
}

利用側のアプリケーションを実行します。

cargo run -p describe_consumer

バイナリが実行され、フィールドのデータが直接出力されます。

--- 注文情報 ---
order_id: 94821
customer_ref: "ACME-CORP"
is_completed: false

--- 設定情報 ---
host: "127.0.0.1"
port: 8080

OrderPayloadやServerConfigに新しいフィールドを追加しても、次のビルド時には即座にdescribe()へ反映されます。仮に誰かがenumに対してDescribeModelを導出(derive)しようとした場合でも、マクロはそのソースコードの正確な位置を特定し、不正な使用であることを示す明確なコンパイルエラーを出力します。反復的なトレイトコードの実装をsynとquoteに任せることで、ドメインモデルを簡潔かつクリーンに保ち、ビルドごとにスキーマの変更が確実に同期される状態を維持できます。

Share: