[Rust 공식문서 한국어 정리] 67. Rust 파생 매크로(Derive Macros) 가이드

[Rust 공식문서 한국어 정리] 67. Rust 파생 매크로(Derive Macros) 가이드



원문 제목: Procedural Macros — Derive — The Rust Reference

작성자: Rust Language Team



━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

📌 1. 서론 — 이 문서가 다루는 내용

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━



이 문서는 #[derive(...)]를 통해 구조체와 열거형에 자동으로 트레이트 구현을 생성하는 파생 매크로를 설명합니다.

표준 라이브러리의 기본 파생 트레이트(Debug, Clone, Copy, PartialEq, Eq, Hash 등)와, 커스텀 derive 매크로 작성법을 다룹니다.

파생 매크로의 동작 원리, 조건부 구현, 그리고 derive-helper 속성을 중심으로 설명합니다.

반복적인 보일러플레이트를 줄이고, 타입 안전성을 유지하면서 생산성을 높이는 핵심 메커니즘입니다.

라이브러리 개발자와 메타프로그래밍에 관심 있는 모든 Rust 개발자에게 필수적인 내용입니다.



━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

🔑 2. 핵심 개념 4가지

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━



① Derive Macro: #[derive(TraitName)]으로 구조체/열거형에 트레이트 구현을 자동 생성합니다.

② proc_macro_derive: 커스텀 파생 매크로를 정의하는 절차 매크로 속성입니다.

③ syn/quote: DeriveInput 파싱과 코드 생성을 돕는 대표적인 프로시저 매크로 보조 라이브러리입니다.

④ Helper Attributes: derive 매크로에 추가 정보를 전달하는 사용자 정의 속성입니다.



━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

📖 3. 주요 내용 상세

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━



표준 derive 트레이트는 Rust의 거의 모든 타입에 적용됩니다.

Debug는 디버그 출력, Clone은 깊은 복사, Copy는 비트 단위 복사, PartialEq/Eq는 동등 비교를 구현합니다.

Hash는 해싱, Default는 기본값 생성, Ord/PartialOrd는 정렬 비교를 제공합니다.



커스텀 derive는 proc_macro_derive 속성으로 정의합니다.

#[proc_macro_derive(MyTrait)] pub fn derive_my_trait(input: TokenStream) -> TokenStream { ... } 형태입니다.

syn::parse_macro_input!(input as DeriveInput)로 입력 타입을 파싱하고, quote! 매크로로 구현 코드를 생성합니다.



DeriveInput은 구조체/열거형의 이름, 제네릭, 필드, 변형 정보를 포함합니다.

Data::Struct와 Data::Enum으로 분기하여, 각각의 구조에 맞는 impl 블록을 생성합니다.

제네릭 파라미터와 where 절도 함께 처리하여, 제네릭 타입에 대한 derive도 올바르게 동작해야 합니다.



Helper attributes는 derive 매크로에 추가 설정을 제공합니다.

#[my_trait(skip)]처럼 필드에 붙여 해당 필드를 제외하거나, #[my_trait(rename = "...")]으로 이름을 변경합니다.

helper attributes는 proc_macro_derive 매크로가 TokenStream에서 직접 파싱하여 처리합니다.



파생 매크로는 proc-macro 타입의 크레이트로 분리해야 합니다.

Cargo.toml에서 [lib] crate-type = ["proc-macro"]를 지정하고, proc-macro2, syn, quote에 의존합니다.

proc-macro2는 proc_macro의 안정적인 버전으로, 테스트와 디버깅에 유리합니다.



━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

🛠 4. 실전 활용

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━



serde::Serialize/Deserialize, thiserror::Error, sqlx::FromRow 등의 derive를 사용하여 보일러플레이트를 제거합니다.

커스텀 derive로 도메인 특화 트레이트(예: Protocol, Command)를 자동 구현합니다.

helper attribute로 필드별 옵션을 제공하여, 유연한 매크로 동작을 구현합니다.



━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

✅ 5. 정리

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━



Derive 매크로는 Rust의 메타프로그래밍을 대중화한 가장 성공적인 기능입니다.

표준 derive 트레이트와 커스텀 derive를 조합하면 반복 코드를 극적으로 줄일 수 있습니다.

syn과 quote를 활용하면 복잡한 derive 매크로도 안정적으로 구현할 수 있습니다.



━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

🔗 출처 링크

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━



원문: https://doc.rust-lang.org/reference/procedural-macros.html

syn: https://docs.rs/syn/latest/syn/



#Rust #Derive #ProcMacro #MetaProgramming #syn #quote #번역