Rust 디자인 패턴 및 엔지니어링 가이드 🟢

강사 소개

• Microsoft SCHIE (Silicon and Cloud Hardware Infrastructure Engineering) 팀의 수석 펌웨어 아키텍트입니다.
• 보안, 시스템 프로그래밍(펌웨어, 운영 체제, 하이퍼바이저), CPU 및 플랫폼 아키텍처, C++ 시스템 분야의 업계 베테랑입니다.
• 2017년(AWS EC2 재직 당시)부터 Rust 프로그래밍을 시작했으며, 지금까지 이 언어의 매력에 깊이 빠져 있습니다.

이 책은 실제 코드베이스에서 발생하는 중급 이상의 Rust 패턴들에 대한 실전 가이드입니다. 단순한 언어 튜토리얼이 아니라, 기초적인 Rust를 작성할 줄 아는 개발자가 한 단계 더 도약할 수 있도록 돕는 것을 목표로 합니다. 각 장은 하나의 핵심 개념을 분리하여 설명하고, 언제 왜 해당 패턴을 사용해야 하는지 명확히 하며, 즉시 실행 가능한 코드 예제와 연습 문제를 제공합니다.

대상 독자

• The Rust Programming Language (공식 입문서)를 마쳤지만 "실제로 어떻게 설계해야 할까?"라는 고민이 있는 개발자
• 실무 시스템을 Rust로 전환하려는 C++ 또는 C# 엔지니어
• 제네릭, 트레이트 경계, 수명(Lifetime) 오류로 인해 벽에 부딪혀 체계적인 툴킷이 필요한 분

선수 지식

시작하기 전에 다음 개념들에 익숙해야 합니다:

• 소유권, 빌림, 수명(기초 수준)
• 열거형(Enum), 패턴 매칭, Option/Result
• 구조체, 메서드, 기본 트레이트(Display, Debug, Clone)
• Cargo 기초: cargo build, cargo test, cargo run

책의 구성 및 활용법

난이도 범례

각 장은 난이도 수준에 따라 다음과 같이 표시됩니다:

학습 로드맵 및 체크포인트

연습 문제 활용하기

모든 장의 끝에는 직접 실습할 수 있는 연습 문제가 포함되어 있습니다. 학습 효과를 극대화하려면:

1. 먼저 스스로 풀어보세요: 정답을 보기 전에 최소 15분은 고민해 보세요.
2. 직접 코드를 타이핑하세요: 복사-붙여넣기보다 직접 입력하는 것이 근육 기억(Muscle Memory) 형성에 큰 도움이 됩니다.
3. 해결책을 변형해 보세요: 기능을 추가하거나 제약을 바꿔보며 코드를 의도적으로 망가뜨려 보세요.

부록에 포함된 캡스톤 프로젝트는 책 전체에서 배운 패턴들을 하나의 완성된 운영 수준 시스템으로 통합하는 과정입니다.

요약 메뉴

1. 제네릭의 모든 것 🟢: 단형성화, 코드 팽창 트레이드오프, 제네릭 vs 열거형 vs 트레이트 객체.
2. 트레이트 심층 분석 🟡: 연관 타입, GAT, 담요 구현(Blanket impl), vtable, HRTB.
3. 뉴타입과 타입 상태 패턴 🟡: 제로 비용 타입 안전성, 컴파일 타임 상태 머신, 빌더 패턴.
4. PhantomData 🔴: 수명 브랜딩(Lifetime branding), 공변성(Variance), 드롭 체크.
5. 채널과 메시지 패싱 🟢: mpsc, select!, 백프레셔, 액터 패턴.
6. 동시성 vs 병렬성 vs 스레드 🟡: Rayon, Mutex/RwLock, 원자(Atomics), 무잠금(Lock-free) 패턴.
7. 클로저와 고계 함수 🟢: Fn 계열 트레이트, 클로저 캡처, 함수형 콤비네이터.
8. 함수형 vs 명령형 🟡: 이터레이터 체인 vs 루프, 상향식 데이터 파이프라인 설계.
9. 스마트 포인터와 내부 가변성 🟡: Box, Rc, Arc, RefCell, Cow, Pin.
10. 에러 처리 패턴 🟢: thiserror vs anyhow, 에러 계층 설계.
11. 직렬화 및 제로 카피 🟡: Serde 기초, 열거형 표현식, 제로 카피 역직렬화.
12. Unsafe Rust 🔴: 5가지 슈퍼파워, FFI, UB 함정 피하기.
13. 매크로: 코드를 짜는 코드 🟡: macro_rules!, 절차적 매크로(syn/quote).
14. 테스트 및 벤치마킹 🟢: 유닛/통합/문서 테스트, 속성 기반 테스트(Proptest).
15. 크레이트 아키텍처 및 API 설계 🟡: 모듈 레이아웃, 인체공학적 API 설계 가이드.
16. 비동기/Await 핵심 🔴: Future, Tokio 기초, 비동기 안티 패턴.

1. 제네릭의 모든 것 🟢

학습 목표:

• **단형성화(Monomorphization)**가 어떻게 제로 비용 제네릭을 구현하는지, 그리고 언제 **코드 팽창(Code Bloat)**을 일으키는지 이해합니다.
• 의사 결정 프레임워크: 제네릭 vs 열거형 vs 트레이트 객체의 선택 기준을 익힙니다.
• 컴파일 타임 배열 크기를 위한 **상수 제네릭(Const Generics)**과 컴파일 타임 연산을 위한 **const fn**을 배웁니다.
• 성능이 중요하지 않은 경로(Cold path)에서 정적 디스패치 대신 동적 디스패치를 선택하는 시점을 파악합니다.

단형성화와 제로 비용 (Monomorphization and Zero Cost)

Rust의 제네릭은 단형성화 방식으로 동작합니다. 즉, 컴파일러가 해당 제네릭 함수가 사용된 구체적인 타입마다 별도의 특화된 코드를 생성합니다. 이는 런타임에 제네릭 정보가 사라지는 Java나 C#의 방식과는 정반대입니다.

fn max_of<T: PartialOrd>(a: T, b: T) -> T {
    if a >= b { a } else { b }
}

fn main() {
    max_of(3_i32, 5_i32);     // 컴파일러가 max_of_i32 생성
    max_of(2.0_f64, 7.0_f64); // 컴파일러가 max_of_f64 생성
    max_of("a", "z");         // 컴파일러가 max_of_str 생성
}

컴파일러가 실제로 생성하는 코드 (개념적):

#![allow(unused)]
fn main() {
// 세 개의 별도 함수 — 런타임 디스패치나 vtable이 없음:
fn max_of_i32(a: i32, b: i32) -> i32 { if a >= b { a } else { b } }
fn max_of_f64(a: f64, b: f64) -> f64 { if a >= b { a } else { b } }
fn max_of_str<'a>(a: &'a str, b: &'a str) -> &'a str { if a >= b { a } else { b } }
}

왜 max_of_str에는 <'a>가 필요한가요? i32와 f64는 Copy 타입이므로 값이 소유권과 함께 반환됩니다. 하지만 &str은 참조자이므로, 컴파일러는 반환될 참조자의 수명을 알아야 합니다. <'a> 주석은 "반환되는 &str은 입력된 두 참조자 모두보다 짧거나 같게 유지된다"는 것을 보장합니다.

장점: 런타임 비용이 전혀 없습니다. 수동으로 작성된 특화 코드와 성능이 동일하며, 최적화 도구(Optimizer)가 각 복사본에 대해 개별적인 인라이닝과 벡터화 최적화를 수행할 수 있습니다.

제네릭이 독이 될 때: 코드 팽창 (Code Bloat)

단형성화의 대가는 바이너리 크기입니다. 각 고유한 타입 인스턴스마다 함수 본문이 복제되기 때문입니다.

#![allow(unused)]
fn main() {
// 이 평범해 보이는 함수가...
fn serialize<T: serde::Serialize>(value: &T) -> Vec<u8> {
    serde_json::to_vec(value).unwrap()
}

// ...50개의 서로 다른 타입과 함께 사용되면 → 바이너리에 50개의 복사본이 생깁니다.
}

완화 전략:

1. 비제네릭 핵심 로직 추출 (Outline 패턴):

   #![allow(unused)]
   fn main() {
   fn serialize<T: serde::Serialize>(value: &T) -> Result<Vec<u8>, serde_json::Error> {
       // 제네릭 부분: 직렬화 호출만 수행
       let json_value = serde_json::to_value(value)?;
       // 비제네릭 부분: 별도 함수로 추출
       serialize_value(json_value)
   }
   
   fn serialize_value(value: serde_json::Value) -> Result<Vec<u8>, serde_json::Error> {
       // 이 함수는 바이너리에 단 '하나'만 존재합니다.
       serde_json::to_vec(&value)
   }
   }

2. 트레이트 객체(동적 디스패치) 사용: 인라이닝이 코드 성능에 결정적이지 않은 경우(예: 로깅, 에러 처리) dyn Trait를 고려하세요.

제네릭 vs 열거형 vs 트레이트 객체 결정 가이드

의사 결정 흐름도:

flowchart TD
    A["컴파일 타임에 모든<br>가능한 타입을 알고 있는가?"]
    A -->|"네, 작고<br>닫힌 타입 군"| B["열거형 (Enum)"]
    A -->|"네, 하지만<br>열거형은 열려 있음"| C["제네릭<br>(단형성화)"]
    A -->|"아니요 — 타입을<br>런타임에 결정해야 함"| D["트레이트 객체 (dyn Trait)"]

    C --> E{"성능이 중요한<br>경로(Hot path)인가?"}
    E -->|네| F["제네릭<br>(인라이닝 가능)"]
    E -->|아니요| G["dyn Trait 이<br>바이너리 크기에 유리함"]

    D --> H{"하나의 컬렉션에<br>여러 타입을 섞어야 하는가?"}
    H -->|네| I["Vec&lt;Box&lt;dyn Trait&gt;&gt;"]
    H -->|아니요| C

상수 제네릭 (Const Generics)

Rust 1.51부터는 타입뿐만 아니라 상수 값을 제네릭 파라미터로 사용할 수 있습니다.

#![allow(unused)]
fn main() {
struct Matrix<const ROWS: usize, const COLS: usize> {
    data: [[f64; COLS]; ROWS],
}

impl<const ROWS: usize, const COLS: usize> Matrix<ROWS, COLS> {
    fn transpose(&self) -> Matrix<COLS, ROWS> {
        let mut result = Matrix::<COLS, ROWS>::new();
        // ... 전치 로직
        result
    }
}

// 컴파일러가 차원(Dimension)의 일치 여부를 검사합니다:
fn multiply<const M: usize, const N: usize, const P: usize>(
    a: &Matrix<M, N>,
    b: &Matrix<N, P>, // N이 반드시 일치해야 함!
) -> Matrix<M, P> { /* ... */ }
}

상수 함수 (const fn)

const fn은 컴파일 타임에 평가될 수 있는 함수를 의미합니다. 결과값은 const나 static 문취에서 바로 사용할 수 있습니다. (C++의 constexpr과 유사)

#![allow(unused)]
fn main() {
const fn celsius_to_fahrenheit(c: f64) -> f64 {
    c * 9.0 / 5.0 + 32.0
}

const BOILING_F: f64 = celsius_to_fahrenheit(100.0); // 컴파일 타임에 계산됨

// 상수 생성자 — lazy_static! 없이도 정적 변수 생성이 가능함
impl BitMask {
    const fn new(bit: u32) -> Self { BitMask(1 << bit) }
}
}

📝 연습 문제: 만료 정책이 있는 제네릭 캐시 ★★ (~30분)

설정된 최대 용량을 가진 제네릭 Cache<K, V> 구조체를 작성하세요. 용량이 가득 차면 가장 오래된 항목이 제거됩니다(FIFO).

• 요구 사항:
  • fn new(capacity: usize) -> Self
  • fn insert(&mut self, key: K, value: V) — 용량 초과 시 가장 오래된 항목 제거
  • fn get(&self, key: &K) -> Option<&V>
  • 제약 조건: K: Eq + Hash + Clone

#![allow(unused)]
fn main() {
use std::collections::{HashMap, VecDeque};
use std::hash::Hash;

struct Cache<K, V> {
    map: HashMap<K, V>,
    order: VecDeque<K>,
    capacity: usize,
}

impl<K: Eq + Hash + Clone, V> Cache<K, V> {
    fn new(capacity: usize) -> Self {
        Cache {
            map: HashMap::with_capacity(capacity),
            order: VecDeque::with_capacity(capacity),
            capacity,
        }
    }

    fn insert(&mut self, key: K, value: V) {
        if self.map.contains_key(&key) {
            self.map.insert(key, value);
            return;
        }
        if self.map.len() >= self.capacity {
            if let Some(oldest) = self.order.pop_front() {
                self.map.remove(&oldest);
            }
        }
        self.order.push_back(key.clone());
        self.map.insert(key, value);
    }

    fn get(&self, key: &K) -> Option<&V> {
        self.map.get(key)
    }
}
}

📌 요약

• 단형성화는 제로 비용 추상화를 제공하지만 코드 팽창을 야기할 수 있으므로, Cold path에서는 dyn Trait를 고려하세요.
• 상수 제네릭은 배열 크기 등을 컴파일 타임에 안전하게 검사하게 해줍니다.
• **const fn**은 lazy_static!과 같은 런타임 비용을 줄여 컴파일 타임 계산으로 대체해 줍니다.

2. 트레이트 심층 분석 🟡

학습 목표:

• 연관 타입(Associated Types)과 제네릭 파라미터의 차이점 및 각각의 사용 시점을 이해합니다.
• GAT(Generic Associated Types), 담요 구현(Blanket impl), 마커 트레이트, 트레이트 객체 안전성 규칙을 마스터합니다.
• vtable과 뚱뚱한 포인터(Fat Pointer)가 하부 구조에서 어떻게 작동하는지 배웁니다.
• 확장 트레이트(Extension traits), 열거형 디스패치(Enum dispatch), 타입화된 커맨드 패턴 등 실전 기술을 익힙니다.

연관 타입 vs 제네릭 파라미터

두 방식 모두 트레이트가 여러 타입과 함께 작동하도록 해주지만, 그 목적은 완전히 다릅니다.

#![allow(unused)]
fn main() {
// --- 연관 타입: 타입당 하나의 구현만 허용 ---
trait Iterator {
    type Item; // 각 반복자는 정확히 한 종류의 아이템만 생성함

    fn next(&mut self) -> Option<Self::Item>;
}

// Counter는 오직 i32만 생성할 수 있습니다. 선택의 여지가 없습니다.
struct Counter { max: i32, current: i32 }

impl Iterator for Counter {
    type Item = i32; // 구현 시점에 Item 타입이 고정됨
    fn next(&mut self) -> Option<i32> {
        if self.current < self.max {
            self.current += 1;
            Some(self.current)
        } else {
            None
        }
    }
}

// --- 제네릭 파라미터: 타입당 여러 구현을 허용 ---
trait Convert<T> {
    fn convert(&self) -> T;
}

// 하나의 타입(i32)이 여러 대상 타입에 대해 Convert를 구현할 수 있습니다.
impl Convert<f64> for i32 {
    fn convert(&self) -> f64 { *self as f64 }
}
impl Convert<String> for i32 {
    fn convert(&self) -> String { self.to_string() }
}
}

언제 무엇을 사용할까요?

직관적인 구분: "이 반복자의 Item이 무엇인가?"라고 묻는 것이 자연스러우면 연관 타입을 쓰세요. "이 타입이 f64로 변환될 수 있는가? String으로는? bool로는?"와 같이 여러 가능성을 묻는다면 제네릭 파라미터가 정답입니다.

제네릭 연관 타입 (GAT, Generic Associated Types)

Rust 1.65부터 연관 타입 자체가 제네릭 파라미터를 가질 수 있게 되었습니다. 이는 빌려주는 반복자(Lending Iterator) 구현을 가능하게 하는 핵심 기능입니다. 이는 반복자가 반환하는 참조자의 수명을 컬렉션이 아닌 반복자 자신에게 묶을 수 있게 해줍니다.

#![allow(unused)]
fn main() {
// GAT가 없으면 빌려주는 반복자를 표현할 수 없었습니다.
// LendingIterator 구현 예시 (Rust 1.65+)
trait LendingIterator {
    type Item<'a> where Self: 'a;

    fn next(&mut self) -> Option<Self::Item<'_>>;
}

// 예: 겹치는 윈도우(Window)를 반환하는 반복자
struct WindowIter<'data> {
    data: &'data [u8],
    pos: usize,
    window_size: usize,
}

impl<'data> LendingIterator for WindowIter<'data> {
    type Item<'a> = &'a [u8] where Self: 'a;

    fn next(&mut self) -> Option<&[u8]> {
        if self.pos + self.window_size <= self.data.len() {
            let window = &self.data[self.pos..self.pos + self.window_size];
            self.pos += 1;
            Some(window)
        } else {
            None
        }
    }
}
}

슈퍼트레이트와 트레이트 계층 구조

트레이트는 다른 트레이트를 전제 조건으로 요구할 수 있습니다. 이를 통해 강력한 타입 계층을 형성합니다.

graph BT
    Display["Display"]
    Debug["Debug"]
    Error["Error"]
    Clone["Clone"]
    Copy["Copy"]
    PartialEq["PartialEq"]
    Eq["Eq"]
    PartialOrd["PartialOrd"]
    Ord["Ord"]

    Error --> Display
    Error --> Debug
    Copy --> Clone
    Eq --> PartialEq
    Ord --> Eq
    Ord --> PartialOrd
    PartialOrd --> PartialEq

화살표는 서브트레이트에서 슈퍼트레이트를 가리킵니다: Error를 구현하려면 Display와 Debug가 필수입니다.

담요 구현 (Blanket Implementations)

특정 조건을 만족하는 전 세계의 모든 타입에 대해 트레이트를 일괄적으로 구현하는 강력한 기능입니다.

#![allow(unused)]
fn main() {
// 표준 라이브러리의 예: Display를 구현한 모든 타입은 자동으로 ToString을 얻습니다.
impl<T: fmt::Display> ToString for T {
    fn to_string(&self) -> String {
        format!("{self}")
    }
}
}

주의: 담요 구현은 매우 강력하지만 한 번 정의하면 되돌리기 어렵습니다 (고아 규칙 및 일관성 문제). 설계 시 신중해야 합니다.

마커 트레이트 (Marker Traits)

메서드가 하나도 없고, 단순히 타입이 특정 속성을 가지고 있음을 컴파일러에게 알리는 역할을 합니다.

• Send: 스레드 간에 데이터 소유권을 넘겨도 안전함.
• Sync: 여러 스레드에서 참조(&T)를 공유해도 안전함.
• Copy: 단순 비트 복사(memcpy)로 복제 가능함.
• Sized: 컴파일 타임에 크기를 알 수 있음.

트레이트 객체 안전성 (Trait Object Safety)

모든 트레이트가 dyn Trait로 사용될 수 있는 것은 아닙니다. 다음 규칙을 지켜야 객체 안전한 트레이트가 됩니다.

1. 트레이트 자체에 Self: Sized 제약이 없어야 합니다.
2. 메서드에 제네릭 파라미터가 없어야 합니다.
3. Self를 반환 타입으로 직접 사용하지 않아야 합니다 (간접 참조 가능).
4. 모든 메서드가 self/&self/&mut self를 인자로 받아야 합니다 (연관 함수 불가).

vtable과 뚱뚱한 포인터 (Fat Pointers)

&dyn Trait (또는 Box<dyn Trait>)는 내부적으로 두 개의 포인터로 구성됩니다.

1. 데이터 포인터: 실제 데이터의 메모리 주소.
2. vtable 포인터: 해당 타입의 트레이트 메서드 주소들이 담긴 표(vtable)의 주소.

확장 트레이트 (Extension Traits)

내가 소유하지 않은 외부 타입에 새로운 메서드를 추가할 때 사용하는 패턴입니다 (itertools, tokio 등에서 널리 쓰임).

#![allow(unused)]
fn main() {
pub trait IteratorExt: Iterator {
    fn mean(self) -> Option<f64>
    where
        Self: Sized,
        Self::Item: Into<f64>;
}

// 모든 Iterator에 .mean() 메서드를 주입합니다.
impl<I: Iterator> IteratorExt for I {
    fn mean(self) -> Option<f64>
    where
        Self: Sized,
        Self::Item: Into<f64>,
    {
        // ... (평균 계산 로직)
        None
    }
}
}

열거형 디스패치 (Enum Dispatch)

타입의 종류가 고정되어 있다면 dyn Trait 대신 열거형을 쓰세요. 힙 할당이 없고, 컴파일러가 분기 예측 최적화와 인라이닝을 수행할 수 있어 훨씬 빠릅니다.

능력 믹스인 (Capability Mixins)

연관 타입과 담요 구현을 조합하여, 복잡한 하드웨어 버스나 기능을 부품처럼 조합(Mixin)하는 기법입니다. 상속이 없는 Rust에서 유연하게 기능을 확장하는 핵심 패턴입니다.

타입화된 커맨드 (Typed Commands)

Haskell의 GADT와 유사하게, 각 명령(Command) 타입이 특정 응답(Response) 타입을 결정하도록 설계하는 패턴입니다. Vec<u8> 같은 불투명한 데이터 대신, 강한 타입 안전성을 보장합니다.

#![allow(unused)]
fn main() {
trait IpmiCmd {
    type Response; // 명령마다 다른 응답 타입을 정의
    fn parse_response(&self, raw: &[u8]) -> io::Result<Self::Response>;
}
}

📝 연습 문제: 연관 타입을 활용한 저장소 패턴 ★★★

Item, Id, Error 연관 타입을 가진 Repository 트레이트를 설계하고, 사용자(User) 정보를 관리하는 인메모리 저장소를 구현해 보세요.

📌 요약

• 연관 타입은 하나로 고정된 출력을, 제네릭은 열린 가능성을 의미합니다.
• GAT는 수명에 의존적인 복잡한 타입을 설계할 때 필수입니다.
• 성능이 중요하다면 열거형 디스패치를, 확장성이 중요하다면 트레이트 객체를 선택하세요.
• 확장 트레이트와 믹스인은 Rust의 구성(Composition) 철학을 실현하는 도구입니다.

3. 뉴타입과 타입 상태 패턴 🟡

학습 목표:

• 제로 비용 컴파일 타임 타입 안전성을 위한 뉴타입(Newtype) 패턴을 익힙니다.
• 타입 상태(Type-state) 패턴을 통해 잘못된 상태 전이를 아예 표현 불가능하게 만드는 법을 배웁니다.
• 컴파일 타임에 필수 필드 입력을 강제하는 타입 상태 빌더 패턴을 학습합니다.
• 제네릭 파라미터 폭발 문제를 해결하는 설정 트레이트(Config trait) 패턴을 이해합니다.

뉴타입: 제로 비용 타입 안전성 (Newtype Pattern)

뉴타입 패턴은 기존 타입을 단일 필드 튜플 구조체로 감싸서, 런타임 오버헤드 없이 고유한 타입을 만드는 기술입니다.

#![allow(unused)]
fn main() {
// 뉴타입 미사용 — 인자 순서를 섞기 쉽고 찾아내기 어렵습니다.
fn create_user(name: String, email: String, age: u32, id: u32) { }
// create_user(name, email, id, age); // ❌ 버그: age와 id가 바뀌었지만 컴파일은 성공함

// 뉴타입 사용 — 컴파일러가 실수를 즉시 잡아냅니다.
struct Age(u32);
struct EmployeeId(u32);

fn create_user(name: String, email: String, age: Age, id: EmployeeId) { }
// create_user(name, email, EmployeeId(42), Age(30)); // ❌ 컴파일 에러: 타입을 잘못 전달함
}

impl Deref의 양날의 검

뉴타입에 Deref를 구현하면 내부 타입의 모든 메서드를 "공짜"로 쓸 수 있지만, 캡슐화 경계에 구멍을 뚫는 위험이 있습니다.

• 권장 시점: Box<T>, Arc<T> 같은 스마트 포인터나 String → str 처럼 래퍼가 내부 타입의 완벽한 상위 집합일 때.
• 비권장 시점: 불변식(Invariant)을 보호해야 하는 도메인 타입(예: Email은 항상 @를 포함해야 함). Deref를 통해 내부 String의 메서드를 멋대로 호출하면 불변식이 깨질 수 있습니다.

철칙: 뉴타입의 목적이 타입 안전성 추가나 API 제한이라면 Deref를 구현하지 마세요. 대신 필요한 메서드만 명시적으로 위임(Delegation)하세요.

타입 상태 패턴: 불가능한 상태를 표현 불가능하게 만들기

타입 시스템을 사용하여 작업이 반드시 올바른 순서대로 일어나도록 강제하는 패턴입니다.

상태 전이도 설계

stateDiagram-v2
    [*] --> Disconnected: new()
    Disconnected --> Connected: connect()
    Connected --> Authenticated: authenticate()
    Authenticated --> Authenticated: request()
    Authenticated --> [*]: drop

    Disconnected --> Disconnected: ❌ request() 호출 불가 (컴파일 에러)

각 상태 전이는 기존 상태 객체를 **소비(Consume)**하고 새로운 타입의 객체를 반환합니다.

#![allow(unused)]
fn main() {
struct Disconnected;
struct Connected;
struct Authenticated;

struct Connection<State> {
    address: String,
    _state: std::marker::PhantomData<State>, // 런타임 비용 없는 마커
}

impl Connection<Disconnected> {
    fn connect(self) -> Connection<Connected> { /* ... */ }
}

impl Connection<Authenticated> {
    fn request(&self, path: &str) -> String { /* ... */ }
}
}

핵심 통찰: Option이나 match로 런타임에 상태를 체크하는 대신, 타입 시스템이 컴파일 타임에 순서를 보장합니다.

실전 사례: 타입 안전한 커넥션 풀 (Connection Pool)

운영 환경에서 트랜잭션 도중에 커넥션을 풀에 반환하면 데이터베이스 락(Lock)이 무한히 유지될 위험이 있습니다.

stateDiagram-v2
    [*] --> Idle: pool.acquire()
    Idle --> InTransaction: conn.begin()
    InTransaction --> InTransaction: conn.execute()
    InTransaction --> Idle: conn.commit() / rollback()
    Idle --> [*]: pool.release(conn)

    InTransaction --> [*]: ❌ 트랜잭션 중에는 반환 불가

Rust에서는 release(conn: PooledConnection<Idle>)와 같이 유휴(Idle) 상태의 커넥션만 인자로 받도록 설계함으로써, 트랜잭션 중인 커넥션을 실수로 반환하는 버그를 원천 봉쇄할 수 있습니다.

설정 트레이트(Config Trait) 패턴: 제네릭 파라미터 폭발 방지

구조체가 관리하는 하드웨어 버스나 컴포넌트가 늘어날수록 제네릭 파라미터 리스트가 걷잡을 수 없이 길어집니다.

#![allow(unused)]
fn main() {
// ❌ 제네릭 파라미터 지옥
struct Controller<S: Spi, I: I2c, U: Uart, G: Gpio, E: Eth> { ... }
}

이를 해결하기 위해 모든 연관 타입을 하나의 설정 트레이트로 묶습니다.

#![allow(unused)]
fn main() {
trait BoardConfig {
    type Spi: SpiBus;
    type I2c: I2cBus;
    type Uart: UartBus;
    // ...
}

// ✅ 이제 제네릭 파라미터는 단 하나입니다.
struct Controller<Cfg: BoardConfig> {
    spi: Cfg::Spi,
    i2c: Cfg::I2c,
    // ...
}
}

이 패턴을 쓰면 새로운 부품을 추가하더라도 함수 시그니처나 테스트 코드를 일일이 수정할 필요가 없습니다.

📝 연습 문제: 타입 상태를 활용한 교통 신호등 ★★ (~30분)

타입 상태 패턴을 사용하여 Red → Green → Yellow → Red 순서로만 전이되는 신호등 시스템을 구현해 보세요. 순서를 어기는 코드가 컴파일되지 않음을 확인하세요.

📌 요약

• 뉴타입은 런타임 비용 없이 도메인 타입을 명확히 구분해 줍니다.
• 타입 상태는 비즈니스 로직의 논리적 버그를 컴파일 타임 에러로 바꿔 줍니다.
• 설정 트레이트는 대규모 시스템 아키텍처에서 제네릭 복잡성을 관리하는 표준 패턴입니다.

4. PhantomData: 데이터를 갖지 않는 타입 🔴

학습 목표:

• PhantomData<T>가 왜 존재하는지, 그리고 이것이 해결하는 세 가지 문제를 이해합니다.
• 컴파일 타임에 스코프를 강제하기 위한 **수명 브랜딩(Lifetime branding)**을 익힙니다.
• 차원이 안전한 연산을 위한 단위 시스템(Unit-of-measure) 패턴을 배웁니다.
• **변형성(Variance: 공변, 반공변, 불변)**의 개념과 PhantomData를 통한 제어 방법을 마스터합니다.

PhantomData가 해결하는 것

PhantomData<T>는 크기가 0인 타입(ZST)으로, 컴파일러에게 "이 구조체는 실제로 T를 포함하지는 않지만, 논리적으로는 T와 연관되어 있다"라고 알려주는 역할을 합니다. 이는 메모리를 전혀 사용하지 않으면서 변형성(Variance), 드롭 체크(Drop check), 자동 트레이트 추론에 영향을 미칩니다.

#![allow(unused)]
fn main() {
use std::marker::PhantomData;

// PhantomData가 없는 경우:
struct Slice<'a, T> {
    ptr: *const T,
    len: usize,
    // 문제: 컴파일러는 이 구조체가 'a 수명 동안 데이터를 빌려오고 있는지,
    // 또는 드롭 체크 시 T를 고려해야 하는지 알 수 없습니다.
}

// PhantomData를 사용하는 경우:
struct Slice<'a, T> {
    ptr: *const T,
    len: usize,
    _marker: PhantomData<&'a T>,
    // 이제 컴파일러는 다음을 알게 됩니다:
    // 1. 이 구조체는 'a 수명의 데이터를 빌려온다.
    // 2. 'a에 대해 공변(Covariant)이다 (수명이 줄어들 수 있음).
    // 3. 드롭 체크 시 T 타입을 고려한다.
}
}

PhantomData의 세 가지 역할:

단위 시스템 (Unit-of-Measure) 패턴

서로 호환되지 않는 단위(미터, 초 등)를 섞어서 연산하는 실수를 컴파일 타임에 방지할 수 있습니다. 런타임 비용은 제로입니다.

use std::marker::PhantomData;

struct Meters;
struct Seconds;

#[derive(Debug, Clone, Copy)]
struct Quantity<Unit> {
    value: f64,
    _unit: PhantomData<Unit>,
}

fn main() {
    let dist = Quantity::<Meters>::new(100.0);
    let time = Quantity::<Seconds>::new(9.58);
    
    // let nonsense = dist + time; // ❌ 컴파일 에러: Meters와 Seconds는 더할 수 없음
}

타입 시스템의 마법: PhantomData<Meters>는 크기가 0이므로, Quantity<Meters>는 메모리 상에서 f64와 동일한 레이아웃을 가집니다. 성능 저하 없이 완벽한 타입 안전성을 제공합니다.

변형성(Variance) — 왜 PhantomData의 타입 파라미터가 중요한가?

변형성은 제네릭 타입이 하위 타입이나 상위 타입으로 대체될 수 있는지를 결정합니다. Rust에서 하위 타입은 보통 "더 긴 수명을 가진 타입"을 의미합니다.

세 가지 변형성 요약:

PhantomData 변형성 치트 시트:

📝 연습 문제: PhantomData를 활용한 단위 시스템 확장 ★★ (~30분)

단위 시스템 패턴을 확장하여 다음을 지원해 보세요:

• Meters, Seconds, Kilograms 단위 정의
• 동일 단위 간의 덧셈 지원
• 곱셈 지원: Meters * Meters = SquareMeters
• 나눗셈 지원: Meters / Seconds = MetersPerSecond

📌 요약

• PhantomData<T>는 런타임 비용 없이 타입/수명 정보를 전달합니다.
• 수명 브랜딩, 변형성 제어, 단위 시스템 패턴 등에 사용됩니다.
• 드롭 체크: PhantomData<T>는 해당 타입이 논리적으로 T를 소유하고 있음을 컴파일러에게 알려줍니다.

5. 채널과 메시지 패싱 🟢

학습 목표:

• std::sync::mpsc의 기초와 crossbeam-channel로 전환해야 하는 시점을 이해합니다.
• 여러 소스의 메시지를 대기하는 select! 매크로 사용법을 익힙니다.
• 유한(Bounded) vs 무한(Unbounded) 채널의 차이와 백프레셔(Backpressure) 전략을 배웁니다.
• 가변 상태를 안전하게 캡슐화하는 액터(Actor) 패턴을 학습합니다.

std::sync::mpsc — 표준 라이브러리 채널

Rust 표준 라이브러리는 여러 생산자(Multi-producer), 단일 소비자(Single-consumer) 구조의 채널을 제공합니다.

use std::sync::mpsc;
use std::thread;

fn main() {
    // 송신기(tx)와 수신기(rx) 쌍 생성
    let (tx, rx) = mpsc::channel();

    // 두 개의 생산자 스레드 스폰
    for i in 0..2 {
        let tx = tx.clone(); // 송신기를 복제로 여러 스레드에 전달
        thread::spawn(move || {
            tx.send(format!("생산자 {}의 메시지", i)).unwrap();
        });
    }

    // 소비자: 모든 송신기가 드롭될 때까지 메시지 수신
    for msg in rx {
        println!("수신: {msg}");
    }
}

주요 특징:

• 기본적으로 무한(Unbounded): 소비자가 느리면 메모리가 계속 차오를 위험이 있습니다.
• 백프레셔 지원: mpsc::sync_channel(N)은 크기가 고정된 채널을 만들어, 채널이 가득 차면 생산자를 블록(Block)시킵니다.

crossbeam-channel — 실무용 워크호스

실제 운영 환경에서는 표준 라이브러리보다 더 빠르고 기능이 많은 crossbeam-channel이 사실상의 표준으로 쓰입니다. 특히 여러 소비자(MPMC)를 지원하는 것이 큰 장점입니다.

#![allow(unused)]
fn main() {
// Bounded MPMC 채널 (용량 100)
let (tx, rx) = crossbeam_channel::bounded::<String>(100);

// 송신기와 수신기를 모두 .clone() 하여 여러 스레드에서 공유 가능
let tx2 = tx.clone();
let rx2 = rx.clone();
}

채널 선택 (select!)

Go 언어의 select와 유사하게, 여러 채널 중 하나라도 메시지가 준비되면 즉시 처리하도록 로직을 짤 수 있습니다.

#![allow(unused)]
fn main() {
loop {
    select! {
        recv(worker_rx) -> msg => println!("작업 처리 중: {:?}", msg),
        recv(ticker) -> _ => println!("1초 경과 (하트비트)"),
        recv(deadline) -> _ => {
            println!("타임아웃 — 종료");
            break;
        }
    }
}
}

Go 언어와의 비교: crossbeam의 select! 매크로는 특정 채널의 기아 상태(Starvation)를 방지하기 위해 Go처럼 무작위 순서로 채널을 검사합니다.

유한(Bounded) vs 무한(Unbounded) 채널

채널을 활용한 액터(Actor) 패턴

액터 패턴은 공유되는 가변 상태를 뮤텍스 없이 관리하는 훌륭한 방법입니다. 메시지 전송을 통해 순차적으로 상태를 변경하므로 경쟁 조건(Race condition)이 발생하지 않습니다.

#![allow(unused)]
fn main() {
// Counter에 대한 접근을 메시지로 직렬화(Serialize)
enum CounterMsg {
    Increment,
    Get(mpsc::Sender<i64>), // 결과를 돌려받을 채널 포함
}

// 스레드 여러 개가 하나의 Counter 핸들에 메시지를 보내면, 
// 액터 내부 루프가 하나씩 차례로 처리합니다.
}

뮤텍스 vs 액터: 작업 시간이 길거나 잠금 순서(Lock ordering)를 고민하기 싫을 때 액터 패턴이 빛을 발합니다. 단순한 상태 변경은 뮤텍스가 더 효율적일 수 있습니다.

📝 연습 문제: 채널 기반 워크 풀(Worker Pool) ★★★ (~45분)

채널을 사용하여 다음 기능을 구현해 보세요:

• 디스패처가 작업을 채널로 보냅니다.
• N개의 워커(Worker) 스레드가 작업을 수신하여 처리하고 결과를 별도 채널로 보냅니다.
• Arc<Mutex<Receiver>>를 사용하여 워커 간의 작업 훔치기(Work-stealing)를 구현해 보세요.

📌 요약

• **crossbeam-channel**은 표준 라이브러리보다 강력하며 멀티 소비자(MPMC)를 지원합니다.
• select! 매크로를 통해 복잡한 폴링 로직을 선언적인 채널 선택으로 바꿀 수 있습니다.
• 운영 서버에서는 메모리 안전을 위해 항상 유한(Bounded) 채널을 먼저 고려하세요.

6. 동시성 vs 병렬성 vs 스레드 🟡

학습 목표:

• **동시성(Concurrency)**과 **병렬성(Parallelism)**의 정확한 차이를 이해합니다.
• OS 스레드, 스코프 스레드, 데이터 병렬 처리를 위한 Rayon을 익힙니다.
• 공유 상태를 위한 프리미티브: Arc, Mutex, RwLock, Atomics, Condvar를 배웁니다.
• OnceLock/LazyLock을 이용한 지연 초기화와 무잠금(Lock-free) 패턴을 학습합니다.

용어 정리: 동시성 ≠ 병렬성

이 두 용어는 자주 혼용되지만, 기술적으로는 명확히 구분됩니다.

스코프 스레드 (std::thread::scope)

Rust 1.63부터 도입된 스코프 스레드는 부모 스레드의 스택 데이터를 Arc 없이도 안전하게 빌려올 수 있게 해줍니다.

#![allow(unused)]
fn main() {
let mut data = vec![1, 2, 3];

thread::scope(|s| {
    // 부모의 data를 직접 빌려올 수 있음!
    s.spawn(|| println!("합계: {}", data.iter().sum::<i32>()));
    s.spawn(|| println!("최대값: {:?}", data.iter().max()));
});

// 스택을 벗어나기 전에 모든 스레드가 종료됨을 컴파일러가 보장함
data.push(4); 
}

Rayon: 데이터 병렬 처리

rayon은 표준 반복자를 병렬 반복자로 바꾸는 아주 간단한 방법을 제공합니다.

#![allow(unused)]
fn main() {
use rayon::prelude::*;

let data: Vec<u64> = (0..1_000_000).collect();

// 순차 처리:
let sum = data.iter().map(|x| x * x).sum();

// 병렬 처리: .iter()를 .par_iter()로 바꾸면 끝!
let sum = data.par_iter().map(|x| x * x).sum();
}

공유 상태: Arc, Mutex, RwLock, Atomics

스레드 간에 가변 상태를 공유해야 할 때 Rust는 안전한 추상화를 제공합니다.

지연 초기화: OnceLock과 LazyLock

글로벌 설정이나 정규표현식처럼 런타임에 단 한 번만 초기화가 필요한 경우, 이제 표준 라이브러리의 기능을 직접 사용하세요.

use std::sync::LazyLock;

// 1.80부터 지원: 전역 정규표현식을 매크로 없이 선언
static RE: LazyLock<regex::Regex> = LazyLock::new(|| {
    regex::Regex::new(r"^[a-z]+$").unwrap()
});

fn main() {
    // 처음 접근할 때 초기화되고 이후엔 재사용됨
    if RE.is_match("rust") { /* ... */ }
}

팁: 기존 코드의 lazy_static!을 LazyLock으로 교체하면 외부 의존성을 줄일 수 있습니다.

📝 연습 문제: 스코프 스레드를 활용한 병렬 맵(Map) ★★ (~25분)

rayon을 사용하지 않고 std::thread::scope만을 사용하여, 데이터를 N개의 청크로 나누어 각 스레드에서 처리하는 parallel_map 함수를 작성해 보세요.

📌 요약

• 스코프 스레드를 쓰면 Arc 없이도 로컬 데이터를 스레드에 넘길 수 있습니다.
• 컬렉션 처리는 **rayon::par_iter()**가 가장 간편하고 강력한 도구입니다.
• 운영 환경에서는 OnceLock/LazyLock을 적극 활용하고, 복잡한 무잠금(Lock-free) 로직은 검증된 크레이트(crossbeam, dashmap 등)를 사용하세요.

7. 클로저와 고계 함수 🟢

학습 목표:

• 세 가지 클로저 트레이트(Fn, FnMut, FnOnce)와 캡처 메커니즘을 이해합니다.
• 클로저를 인자로 전달하거나 함수에서 반환하는 법을 익힙니다.
• 함수형 프로그래밍 스타일의 핵심인 콤비네이터 체인과 반복자 어댑터를 배웁니다.
• 적절한 트레이트 경계를 가진 나만의 고계 API(Higher-order API)를 설계합니다.

클로저 트레이트: Fn, FnMut, FnOnce

모든 클로저는 변수를 캡처하는 방식에 따라 다음 세 가지 트레이트 중 하나 이상을 구현합니다.

#![allow(unused)]
fn main() {
// FnOnce — 캡처한 값을 소비함 (딱 한 번만 호출 가능)
let name = String::from("Alice");
let greet = move || {
    drop(name); // name의 소유권을 가져와 소비함
};
greet(); // ✅ 성공
// greet(); // ❌ 에러: 이미 소비된 값을 또 쓸 수 없음

// FnMut — 캡처한 값을 가변으로 빌림 (여러 번 호출 가능)
let mut count = 0;
let mut increment = || {
    count += 1; // count를 가변으로 빌려서 수정함
};
increment(); // count == 1

// Fn — 캡처한 값을 불변으로 빌림 (여러 번, 동시에 호출 가능)
let display = |x: i32| println!("{x}");
display(1);
display(2);
}

트레이트 계층 구조:

Fn : FnMut : FnOnce 순서로 상속 관계를 가집니다. 즉, Fn을 구현한 클로저는 자동으로 FnMut와 FnOnce도 만족합니다.

클로저를 인자로 전달하고 반환하기

#![allow(unused)]
fn main() {
// 정적 디스패치 (인라이닝 가능, 가장 빠름)
fn apply<F: Fn(i32) -> i32>(f: F, x: i32) -> i32 { f(x) }

// 동적 디스패치 (유연함, 약간의 오버헤드)
fn apply_dyn(f: &dyn Fn(i32) -> i32, x: i32) -> i32 { f(x) }

// 클로저 반환 (이름이 없는 타입이므로 impl Trait이나 Box 사용 필수)
fn make_adder(n: i32) -> impl Fn(i32) -> i32 {
    move |x| x + n
}
}

반복자 콤비네이터: Rust의 백미

명령형 루프를 함수형 스타일의 체인으로 바꾸면 가독성이 높아지고 버그가 줄어듭니다. LLVM 최적화 덕분에 성능 손실도 거의 없습니다.

#![allow(unused)]
fn main() {
let data = vec![1, 2, 3, 4, 5];

// 이디오마틱한 Rust 스타일:
let result: Vec<i32> = data.iter()
    .filter(|&&x| x % 2 == 0) // 필터링
    .map(|&x| x * x)          // 변환
    .collect();               // 수집
}

With 패턴: 안전한 리소스 접근 가이드

일부 리소스(예: GPIO 핀, DB 트랜잭션)는 특정 작업 전후에 반드시 설정과 해제가 필요합니다. 사용자가 이를 깜빡하는 실수를 막기 위해 클로저를 통해 리소스를 잠시 빌려주는 with 패턴을 사용합니다.

#![allow(unused)]
fn main() {
impl GpioController {
    /// 핀을 입력 모드로 설정하고 클로저 실행 후, 원래 상태로 복구함
    pub fn with_pin_input<R>(&self, pin: u8, mut f: impl FnMut(&GpioPin) -> R) -> R {
        self.set_direction(pin, Direction::In);
        let result = f(&GpioPin { pin });
        self.restore_direction(pin);
        result
    }
}

// 사용자는 설정/해제 로직을 고민할 필요가 없습니다.
gpio.with_pin_input(4, |pin| {
    pin.read()
});
}

With 패턴 vs RAII(Drop): 두 방식 모두 정리를 보장하지만, with 패턴은 특정 작업 블록 안에서만 리소스가 존재하도록 강제할 때 더 강력합니다.

📝 연습 문제: 고계 콤비네이터 파이프라인 ★★ (~25분)

여러 변환 과정을 체인으로 엮을 수 있는 Pipeline 구조체를 설계해 보세요. .pipe(f)로 변환을 추가하고 .execute(input)으로 전체 과정을 실행하는 구조입니다.

📌 요약

• **FnMut**를 기본 제약 조건으로 사용하세요. 가장 유연하게 호출될 수 있습니다.
• 콤비네이터 체인(map, filter 등)은 코드의 의도를 명확히 드러내며 성능 면에서도 우수합니다.
• with 패턴을 활용해 사용자가 리소스를 오용할 가능성을 컴파일 타임에 차단하세요.

8. 함수형 vs 명령형: 우아함이 승리할 때 (그리고 아닐 때) 🟡

학습 목표:

• 데이터 변환 파이프라인과 부수 효과 중심의 상태 관리 사이에서 최적의 스타일을 선택하는 안목을 기릅니다.
• Option과 Result의 콤비네이터를 활용해 중복되는 if let 코드를 제거합니다.
• 반복자 체인과 루프 중 무엇이 더 읽기 쉽고 효율적인지 판단하는 기준을 배웁니다.
• 함수형 에러 처리와 명령형 가독성을 결합하는 ? 연산자의 가치를 이해합니다.

함수형 vs 명령형: 선택의 핵심 원칙

Rust는 함수형 언어(Haskell 등)와 명령형 언어(C 등)의 장점을 모두 갖추고 있습니다.

• 함수형 스타일: 데이터를 파이프라인을 통해 **변환(Transforming)**할 때 빛을 발합니다.
• 명령형 스타일: 부수 효과가 있는 **상태 전이(State transitions)**를 관리할 때 더 명학합니다.

Option과 Result 콤비네이터 가족

if let이나 match로 도배된 코드를 콤비네이터로 바꾸면 의도가 더 명확해집니다.

반복자 체인 vs 루프: 결정 가이드

반복자 체인이 이기는 경우 (데이터 파이프라인)

• 여러 단계의 필터링, 매핑, 수집이 일어날 때.
• 가변 변수(mut)를 없애고 데이터의 흐름을 일방통행으로 만들고 싶을 때.
• 중간 결과물을 보관할 필요가 없을 때.

루프가 이기는 경우 (복잡한 상태 및 부수 효과)

• 한 번의 순회로 여러 종류의 컬렉션을 동시에 구축해야 할 때.
• 루프 중간에 DB 저장, 로그 출력 등 복잡한 부수 효과가 섞여 있을 때.
• 상태 머신 로직이 포함되어 match state가 핵심일 때.

결정 순서도

flowchart TB
    START{무엇을 하시나요?}

    START -->|"컬렉션을 다른 컬렉션으로 변환"| PIPE[반복자 체인 권장]
    START -->|"단일 값으로 요약 (합계 등)"| AGG{복잡도?}
    START -->|"한 번에 여러 출력 생성"| LOOP[for 루프 권장]
    START -->|"I/O 또는 부수 효과 중심"| LOOP
    START -->|"Option/Result 변환"| COMB[콤비네이터 권장]

    AGG -->|"합계, 개수, 최소/최대"| BUILTIN["전용 메서드 사용\n(.sum, .count 등)"]
    AGG -->|"커스텀 요약"| FOLD{가변 상태가 필요한가?}
    FOLD -->|"아니오"| FOLDF[".fold() 사용"]
    FOLD -->|"예"| LOOP

스코프 가변성 (Scoped Mutability)

"내부는 명령형으로, 외부는 함수형으로" 처리하는 Rust의 강력한 패턴입니다. 블록({}) 자체가 식(Expression)이 될 수 있음을 활용합니다.

#![allow(unused)]
fn main() {
let samples = {
    let mut buf = Vec::new(); // 이 가변 변수는 블록 안에서만 존재
    while buf.len() < 10 {
        buf.push(generate_data());
    }
    buf // 결과물 반환
};
// 이제 samples는 불변(immutable)입니다!
}

? 연산자: 함수형과 명령형의 우아한 결합

? 연산자는 내부적으로는 .and_then()과 같지만, 가독성은 명령형 코드와 같습니다.

#![allow(unused)]
fn main() {
// 함수형 체이닝 (가끔 읽기 힘듦)
read_file()?.and_then(parse)?.and_then(validate)

// ? 연산자 활용 (변수 이름을 지을 수 있어 명확함)
let contents = read_file()?;
let config = parse(contents)?;
validate(config)
}

팁: 중간 변수 이름이 로직의 이해에 도움을 준다면 ? 연산자를, 단순한 변환의 연속이라면 콤비네이터를 선택하세요.

📝 연습 문제: 명령형 코드를 함수형으로 리팩토링 ★★ (~30분)

서버 목록을 받아 상태별로 분류하고 평균 전력 소비량과 최고 온도를 계산하는 명령형 함수를 리팩토링해 보세요. 어떤 부분이 함수형으로 고쳤을 때 더 나빠지는지(혹은 좋아지는지) 분석해 보세요.

📌 요약

• Option과 Result를 컬렉션처럼 취급하여 콤비네이터를 활용하세요.
• 데이터 변환은 반복자 체인이, 상태 관리는 루프가 적합합니다.
• 제로 비용 추상화: 함수형으로 짜더라도 릴리즈 빌드에서는 루프와 동일한 기계어로 최적화됩니다. 성능 걱정 말고 가독성을 우선하세요.
• 안티 패턴: 5단계 이상의 너무 긴 체인은 가독성을 해칩니다. 중간 변수로 끊어 가세요.

9. 스마트 포인터와 내부 가변성 🟡

학습 목표:

• 힙 할당과 소유권 공유를 위한 Box, Rc, Arc의 차이점을 마스터합니다.
• 순환 참조를 끊기 위한 약한 참조(Weak reference) 활용법을 배웁니다.
• Cell, RefCell, Cow를 통한 내부 가변성 패턴을 익힙니다.
• 자기 참조 타입을 위한 Pin과 생명주기 제어를 위한 ManuallyDrop을 이해합니다.

Box, Rc, Arc: 힙 할당과 공유

#![allow(unused)]
fn main() {
// --- Box<T>: 단일 소유자, 힙 할당 ---
// 용도: 재귀적 타입, 큰 데이터 전송, 트레이트 객체
let boxed = Box::new(42);

// --- Rc<T>: 다중 소유자, 싱글 스레드 전용 ---
// 용도: 같은 데이터를 여러 곳에서 읽어야 할 때 (참조 카운팅)
let a = Rc::new(vec![1, 2, 3]);
let b = Rc::clone(&a); // 카운트만 증가 (깊은 복사 아님)

// --- Arc<T>: 다중 소유자, 스레드 안전 ---
// 용도: 여러 스레드 간에 데이터를 공유할 때
let shared = Arc::new(String::from("공유 데이터"));
}

약한 참조 (Weak Reference): 순환 참조 끊기

Rc와 Arc는 참조 카운트가 0이 되어야 메모리를 해제합니다. 두 객체가 서로를 강하게 참조하면 절대 해제되지 않는 메모리 누수가 발생합니다. 이때 약한 참조를 사용하여 소유권을 주장하지 않고 데이터에 접근할 수 있습니다.

#![allow(unused)]
fn main() {
struct Node {
    parent: RefCell<Weak<Node>>, // 부모는 자식을 소유하지만, 자식은 부모를 소유하지 않음
    children: RefCell<Vec<Rc<Node>>>,
}
}

Cell과 RefCell: 내부 가변성 (Interior Mutability)

불변 참조(&T) 뒤에 있는 데이터를 수정해야 할 때 사용하는 '탈출구'입니다.

• Cell<T>: Copy 타입에 적합하며 런타임 오버헤드가 거의 없습니다. 값을 복사하거나 교체하는 방식으로 작동합니다.
• RefCell<T>: 모든 타입에 사용 가능하며, 런타임에 대여 규칙을 검사합니다. 규칙 위반 시 패닉(Panic)이 발생합니다.

Cow: 쓰기 시 복사 (Clone on Write)

불필요한 할당을 줄이는 영리한 열거형입니다. 대부분의 경우 데이터를 빌려 쓰다가, 수정이 필요할 때만 비로소 복제를 수행합니다.

#![allow(unused)]
fn main() {
fn normalize(input: &str) -> Cow<'_, str> {
    if input.contains('\t') {
        // 탭이 있을 때만 새로운 String 할당
        Cow::Owned(input.replace('\t', "    "))
    } else {
        // 탭이 없으면 입력받은 참조를 그대로 반환 (할당 제로)
        Cow::Borrowed(input)
    }
}
}

Pin과 자기 참조 타입

Pin은 특정 값이 메모리 상에서 이동하지 못하도록 고정합니다. 이는 구조체 내부의 필드가 자기 자신의 다른 필드를 가리키는 자기 참조 구조체나, .await 지점을 넘나드는 Future 객체에 필수적입니다.

드롭 순서 (Drop Order)와 ManuallyDrop

Rust의 객체 소멸 순서는 예측 가능합니다.

• 지역 변수: 선언된 역순으로 해제됩니다.
• 구조체 필드: 선언된 순서(위에서 아래로)대로 해제됩니다.

복잡한 리소스 관리 시 소멸 순서를 직접 제어해야 한다면 ManuallyDrop을 사용하여 컴파일러의 자동 드롭을 막고 수동으로 drop()을 호출할 수 있습니다.

📝 연습 문제: 참조 카운팅 그래프 제작 ★★ (~30분)

Rc<RefCell<Node>>를 사용하여 A → B → C → A 형태의 순환 그래프를 만들어 보세요. Weak를 사용하여 메모리 누수 없이 모든 노드가 정상적으로 드롭되는지 확인해 보세요.

📌 요약

• 단일 소유권은 Box, 다중 소유권은 Rc/Arc를 선택하세요.
• 내부 가변성은 컴파일 타임 대여 규칙을 런타임으로 미루는 도구입니다. 신중히 사용하세요.
• **Cow**는 읽기 위주의 API에서 성능 최적화의 핵심입니다.
• 드롭 순서가 중요하다면 필드 선언 순서에 유의하세요.

10. 에러 처리 패턴 🟢

학습 목표:

• 라이브러리용 thiserror와 애플리케이션용 anyhow를 구분하여 사용하는 법을 배웁니다.
• #[from]과 .context()를 이용해 에러 변환 체인을 구축하는 기술을 익힙니다.
• ? 연산자의 내부 작동 방식과 main() 함수에서의 활용법을 이해합니다.
• 예상된 에러(Result)와 프로그래밍 버그(panic)를 명확히 구분합니다.

thiserror vs anyhow: 라이브러리냐 애플리케이션이냐

Rust의 에러 처리는 Result<T, E>를 중심으로 돌아갑니다. 상황에 따라 다음 두 크레이트 중 하나를 선택하세요.

• thiserror (라이브러리용): 구체적인 에러 열거형을 정의할 때 사용합니다. 호출자가 에러 종류를 match로 구분해야 하는 라이브러리에 적합합니다.
• anyhow (애플리케이션용): 에러의 구체적인 종류보다 "실패했다"는 사실과 원인 파악이 더 중요한 최종 실행 파일에 적합합니다. .context() 기능이 아주 강력합니다.

에러 변환 체인 (#[from])

thiserror의 #[from] 속성을 사용하면 ? 연산자가 하위 에러를 상위 에러로 자동 변환해 줍니다.

#![allow(unused)]
fn main() {
#[derive(Error, Debug)]
pub enum AppError {
    #[error("I/O 에러: {0}")]
    Io(#[from] std::io::Error), // io::Error를 AppError::Io로 자동 변환

    #[error("JSON 에러: {0}")]
    Json(#[from] serde_json::Error),
}
}

컨텍스트과 에러 래핑 (anyhow)

anyhow는 에러가 발생한 지점의 상황을 설명하는 문구(Context)를 겹겹이 쌓아 올릴 수 있게 해줍니다.

#![allow(unused)]
fn main() {
let content = std::fs::read_to_string(path)
    .with_context(|| format!("{path} 파일을 읽는 데 실패했습니다"))?;
}

출력 결과: "파일 읽기 실패" -> "원인: 권한 없음(OS Error)" 순서로 에러 원인들이 체인처럼 출력되어 디버깅이 매우 쉬워집니다.

? 연산자의 깊은 이해

?는 단순히 에러를 반환하는 것 이상의 일을 합니다. 내부적으로 From 트레이트를 호출하여 정의된 에러 타입으로 자동 변환까지 수행합니다.

#![allow(unused)]
fn main() {
// 이 코드는...
let value = operation()?;

// 내부적으로 다음과 같습니다:
let value = match operation() {
    Ok(v) => v,
    Err(e) => return Err(From::from(e)), // 자동으로 에러 타입을 변환하여 반환
};
}

패닉(Panic) vs 에러(Result)

• Result<T, E>: 파일 없음, 네트워크 타임아웃 등 충분히 발생할 수 있는 실패 상황에 사용하세요.
• panic!(): 인덱스 범위를 벗어남, 절대 일어나면 안 되는 논리적 모순 등 프로그래밍 버그를 나타낼 때만 사용하세요.
• catch_unwind: C/C++ 라이브러리와 통신(FFI)하거나 스레드 풀 경계에서 패닉이 프로그램 전체를 죽이지 않도록 격리할 때 사용합니다.

📝 연습 문제: thiserror를 활용한 에러 계층 설계 ★★ (~30분)

파일 처리 앱을 위한 에러 구조를 설계해 보세요. I/O 에러, 파싱 에러(JSON), 그리고 사용자 비즈니스 검증 에러가 포함되어야 합니다. ? 연산자가 어떻게 각 에러를 AppError로 변환하는지 코드로 구현해 보세요.

📌 요약

• 라이브러리는 thiserror, 애플리케이션은 **anyhow**를 쓰세요.
• **.context()**를 활용해 에러 발생 상황을 구체적으로 기록하세요.
• **?**는 에러 전파뿐 아니라 자동 타입 변환기이기도 합니다.
• 패닉은 대처 가능한 에러 처리에 쓰는 도구가 아닙니다.

11. 직렬화, 제로 카피, 바이너리 데이터 🟡

학습 목표:

• serde의 핵심: 파생 매크로, 속성(Attribute), 열거형 표현 방식을 익힙니다.
• 고성능 읽기 작업을 위한 제로 카피(Zero-copy) 역직렬화 기술을 배웁니다.
• 다양한 직렬화 포맷(JSON, TOML, bincode, MessagePack)의 생태계를 이해합니다.
• repr(C), zerocopy, bytes::Bytes를 이용한 바이너리 데이터 처리 기법을 마스터합니다.

Serde 기초: 직렬화와 역직렬화의 표준

serde는 Rust에서 데이터를 다양한 포맷으로 변환하는 유니버설 프레임워크입니다. 데이터 모델(구조체)과 포맷(JSON, binary 등)을 완벽히 분리합니다.

#![allow(unused)]
fn main() {
use serde::{Serialize, Deserialize};

#[derive(Serialize, Deserialize)]
struct Config {
    name: String,
    port: u16,
    #[serde(default)] // 필드가 없으면 기본값(0) 사용
    max_conn: usize,
}
}

핵심 통찰: 구조체에 Serialize와 Deserialize를 한 번만 구현해 두면, 코드 수정 없이 JSON, TOML, YAML, bincode 등 수십 가지 포맷과 호환됩니다.

일반적인 Serde 속성 (Attributes)

제로 카피(Zero-copy) 역직렬화

새로운 메모리를 할당하지 않고, 입력 버퍼의 데이터를 직접 참조하는 고성능 기법입니다.

#![allow(unused)]
fn main() {
#[derive(Deserialize)]
struct BorrowedRecord<'a> {
    name: &'a str,  // 입력 문자열 버퍼를 직접 가리킴 (복사 제로)
    value: &'a str,
}
}

사용 시점: 대용량 로그 파일 파싱처럼 속도가 중요하고 입력 버퍼가 메모리에 계속 유지될 때 사용하세요. 입력 버퍼가 일시적이라면 String을 사용하는 일반적인 역직렬화를 써야 합니다.

바이너리 데이터 처리와 repr(C)

하드웨어 레지스터나 네트워크 프로토콜 헤더를 정밀하게 다뤄야 할 때 사용합니다.

• #[repr(C)]: 필드 배치 순서를 C 언어 규칙과 일치시켜 예측 가능한 메모리 레이아웃을 보장합니다.
• zerocopy / bytemuck: unsafe한 transmute 대신, 컴파일 타임에 안전성이 검증된 제로 카피 변환을 제공합니다.
• bytes::Bytes: 참조 카운팅이 적용된 바이트 버퍼입니다. 대규모 이진 데이터를 여러 스레드나 컴포넌트 간에 복사 없이 공유할 때 필수적입니다.

📝 연습 문제: 커스텀 Serde 역직렬화 ★★★ (~45분)

"30s", "5m", "2h"와 같은 사람이 읽기 쉬운 문자열을 std::time::Duration으로 변환하는 커스텀 역직렬화기(Deserializer)를 구현해 보세요. 반대로 직렬화할 때도 원래의 형식으로 돌아가야 합니다.

📌 요약

• serde 속성을 잘 활용하면 외부 API의 복잡한 명세도 깔끔하게 매핑할 수 있습니다.
• 성능이 극한으로 중요하다면 제로 카피와 **Cow**를 조합하세요.
• 바이너리 통신에는 **repr(C)**와 zerocopy 크레이트를 사용하는 것이 안전합니다.
• 참조 카운팅 바이트 버퍼가 필요하다면 bytes 크레이트를 고려하세요.

12. Unsafe Rust: 통제된 위험 🔴

학습 목표:

• 컴파일러가 검증할 수 없는 다섯 가지 Unsafe 초능력과 그 사용 시점을 이해합니다.
• 건전한 추상화(Sound Abstraction): 안전한 API로 비안전한 내부 로직을 감싸는 법을 배웁니다.
• C 언어와 통신하기 위한 FFI 패턴을 익힙니다.
• 흔히 발생하는 **미정의 동작(UB)**의 함정과 아레나/슬래브 할당자 패턴을 학습합니다.

Unsafe의 다섯 가지 초능력

unsafe 키워드는 컴파일러가 안전성을 보장할 수 없는 다섯 가지 특수 작업을 허용합니다.

#![allow(unused)]
fn main() {
unsafe {
    // 1. RAW 포인터 역참조
    let value = *raw_ptr;

    // 2. Unsafe 함수 또는 메서드 호출
    let mem = std::alloc::alloc(layout);

    // 3. 가변 정적 변수(static mut) 접근 및 수정
    COUNTER += 1;

    // 4. Unsafe 트레이트 구현
    unsafe impl Send for MyType {}

    // 5. 유니온(Union) 필드 접근
    let f = u.f;
}
}

핵심 원칙: unsafe가 빌림 검사기(Borrow checker)를 끄는 것은 아닙니다. 오직 위 다섯 가지 능력만 해제하며, 나머지 모든 Rust 규칙은 여전히 적용됩니다.

건전한 추상화 (Sound Abstraction) 작성

unsafe의 진정한 목적은 위험한 로직을 내부에 숨기고, 외부 사용자에게는 절대 오용할 수 없는 안전한 인터페이스를 제공하는 것입니다.

건전한 Unsafe 코드의 3계명:

1. 불변성(Invariant) 문서화: 모든 unsafe 블록 위에 // SAFETY: 주석을 달아 왜 이 작업이 안전한지 논리적으로 설명하세요.
2. 캡슐화: 사용자가 안전한 API만 사용해도 내부에서 미정의 동작(UB)이 발생하지 않도록 설계하세요.
3. 최소화: unsafe 블록은 필요한 최소한의 범위로 유지하세요.

커스텀 할당자: 아레나(Arena)와 슬래브(Slab)

대규모 시스템에서는 표준 할당자(malloc)의 오버헤드를 줄이기 위해 특화된 할당 패턴을 사용합니다.

• 아레나(Arena): 포인터를 앞으로 밀기만 하는 매우 빠른 할당 방식입니다. 개별 해제는 불가능하며, 아레나 전체를 한꺼번에 해제하여 메모리 파편화를 방지합니다. 프레임 단위 처리나 요청 단위 작업에 최적입니다.
• 슬래브(Slab): 고정된 크기의 슬롯들을 미리 확보해 두고 재사용합니다. 메모리 파편화가 전혀 없으며, 고정 크기 객체(예: 커넥션 풀)를 빈번하게 생성하고 삭제할 때 최고의 성능을 냅니다.

미정의 동작(UB)의 일반적인 함정

📝 연습 문제: Unsafe를 활용한 안전한 래퍼 제작 ★★★ (~45분)

고정 크기 스택 할당 벡터인 FixedVec<T, N>을 구현해 보세요.

• push, pop, as_slice 기능을 구현하되, 내부적으로는 MaybeUninit을 사용하세요.
• 모든 공개 API는 안전해야 하며, 내부의 모든 unsafe에는 상세한 // SAFETY: 주석을 달아야 합니다.
• Drop 구현을 통해 초기화된 요소들이 정상적으로 소멸되도록 하세요.

📌 요약

• FFI 경계나 성능 병목 구간 외에는 unsafe 사용을 지양하세요.
• 모든 비안전한 연산 뒤에는 이를 안전하게 만드는 논리적 증거가 있어야 합니다.
• 아레나와 슬래브 할당자는 일반적인 힙 할당보다 수십 배 빠를 수 있습니다.
• 복잡한 메모리 레이아웃이 필요하다면 **repr(C)**를 사용하여 C 언어와의 호환성을 확보하세요.

13. 매크로: 코드를 짜는 코드 🟡

학습 목표:

• 패턴 매칭과 반복을 이용한 **선언적 매크로(macro_rules!)**를 작성합니다.
• 매크로를 사용해야 할 때와 제네릭/트레이트로 충분할 때를 구분합니다.
• 절차적 매크로(Procedural Macros): derive, attribute, function-like 세 가지 유형을 이해합니다.
• syn과 quote 크레이트를 활용해 커스텀 Derive 매크로를 구현해 봅니다.

선언적 매크로 (macro_rules!)

선언적 매크로는 코드의 구문 패턴을 매칭하여 컴파일 타임에 코드를 확장합니다.

#![allow(unused)]
fn main() {
// 간단한 HashMap 생성 매크로
macro_rules! hashmap {
    ( $( $key:expr => $value:expr ),* $(,)? ) => {
        {
            let mut map = std::collections::HashMap::new();
            $( map.insert($key, $value); )*
            map
        }
    };
}

let scores = hashmap! {
    "Alice" => 95,
    "Bob" => 87,
};
}

매크로 프래그먼트 (Fragment) 종류

매크로에서 매칭할 수 있는 코드 조각의 타입들입니다.

매크로 사용 시 주의사항

• 권장 상황: 트레이트/제네릭으로 해결하기 힘든 보일러플레이트 제거(테스트 케이스 자동 생성 등), DSL 구축(html!, sql!).
• 지양 상황: 단순한 함수나 제네릭으로 해결 가능한 경우. 매크로는 디버깅이 어렵고 자동 완성이 잘 작동하지 않습니다.

절차적 매크로 (Procedural Macros)

절차적 매크로는 토큰 스트림을 입력받아 Rust 함수처럼 조작하여 새로운 토큰 스트림을 반환합니다.

• Derive 매크로: #[derive(MyTrait)] 처럼 구조체나 열거형에 트레이트 구현을 자동으로 추가합니다.
• Attribute 매크로: #[route(GET, "/")] 처럼 아이템 자체를 변형합니다.
• Function-like 매크로: sql!(SELECT * FROM ...) 처럼 커스텀 구문을 정의합니다.

매크로 위생(Hygiene)과 $crate

매크로 내부에서 정의한 변수 이름이 매크로를 호출한 곳의 변수 이름과 충돌하지 않도록 보장하는 것을 위생이라고 합니다. 또한 라이브러리에서 매크로를 정의할 때는 사용자가 크레이트를 어떤 이름으로 임포트했든 상관없이 작동하도록 항상 $crate 키워드를 사용하여 자신을 참조해야 합니다.

📝 연습 문제: 선언적 매크로 map! 제작 ★ (~15분)

키-값 쌍을 인자로 받아 HashMap을 생성하는 map! 매크로를 작성해 보세요. 쉼표가 마지막에 있거나 아예 인자가 없는 상황(map!{})도 지원해야 합니다.

📌 요약

• 단순 반복 코드는 **macro_rules!**로 해결하세요.
• 복잡한 구조체 분석이나 코드 생성에는 **syn**과 **quote**를 활용한 절차적 매크로가 적합합니다.
• 매크로를 설계할 때는 항상 함수나 트레이트로 더 나은 해결책이 있는지 먼저 고민하세요.
• 라이브러리용 매크로에서는 호환성을 위해 반드시 **$crate**를 사용하세요.

14. 테스트 및 벤치마킹 패턴 🟢

학습 목표:

• Rust의 세 가지 테스트 계층: 단위(Unit), 통합(Integration), 문서(Doc) 테스트를 마스터합니다.
• **속성 기반 테스트(Property-based testing)**인 proptest로 예상치 못한 엣지 케이스를 찾아냅니다.
• Criterion 라이브러리를 사용해 통계적으로 신뢰할 수 있는 성능 벤치마킹을 수행합니다.
• 무거운 프레임워크 없이 트레이트 기반의 모킹(Mocking) 전략을 구축합니다.

세 가지 테스트 계층

Rust는 언어 차원에서 강력한 테스트 도구를 제공합니다.

1. 단위 테스트(Unit Tests): 비즈니스 로직과 같은 파일에 작성하며, mod tests와 #[cfg(test)]를 사용합니다. 비공개 함수도 테스트할 수 있습니다.
2. 통합 테스트(Integration Tests): tests/ 디렉토리에 위치하며, 라이브러리의 공개 API만 테스트합니다. 외부 사용자의 관점에서 테스트를 진행합니다.
3. 문서 테스트(Doc Tests): 문서 주석(///) 내의 코드 예제를 실제로 실행합니다. 문서와 실제 코드가 일치함을 보장합니다.

속성 기반 테스트 (Proptest)

특정 입력값 하나하나를 테스트하는 대신, "임의의 입력에 대해 항상 만족해야 하는 성질(Property)"을 테스트합니다.

#![allow(unused)]
fn main() {
proptest! {
    #[test]
    fn test_reverse_twice_is_identity(v in prop::collection::vec(any::<i32>(), 0..100)) {
        // 성질: 두 번 뒤집으면 원래와 같아야 함
        assert_eq!(reverse(&reverse(&v)), v);
    }
}
}

장점: 수백 개의 랜덤한 입력을 자동으로 생성하며, 실패 시 최소한의 재현 케이스로 데이터를 축소(Shrink)해 줍니다.

Criterion을 이용한 정밀 벤치마킹

cargo bench보다 훨씬 정밀한 성능 측정이 가능합니다. 통계적 유의미함을 검사하고 HTML 리포트를 생성해 줍니다.

#![allow(unused)]
fn main() {
fn bench_fibonacci(c: &mut Criterion) {
    c.bench_function("fibonacci 20", |b| b.iter(|| fibonacci(black_box(20))));
}
}

팁: black_box를 사용하여 컴파일러가 벤치마크 함수를 아예 생략하거나 상수화해 버리는 과도한 최적화를 방지하세요.

프레임워크 없는 모킹(Mocking) 전략

Rust에서는 복잡한 모킹 프레임워크 대신 트레이트 기반의 의존성 주입을 권장합니다.

#![allow(unused)]
fn main() {
trait Clock { fn now(&self) -> Instant; }

// 실무용 구현체
struct RealClock;
// 테스트용 가짜 구현체
struct MockClock { fixed_time: Instant }
}

이러면 테스트할 구조체에 Clock 트레이트만 요구하면 실제 환경과 테스트 환경에서 각각 다른 객체를 넣어줄 수 있습니다.

📝 연습 문제: 속성 기반 테스트 실습 ★★ (~25분)

SortedVec<T>라는 항상 정렬 상태를 유지하는 래퍼를 만드세요. proptest를 사용하여 다음 성질들을 검증해 보세요:

1. 어떤 값을 넣어도 내부 벡터는 항상 정렬되어 있는가?
2. contains() 결과가 표준 Vec::contains()와 일치하는가?
3. 삽입한 만큼 길이가 늘어났는가?

📌 요약

• 문서 테스트를 적극 활용해 살아있는 문서를 만드세요.
• 복잡한 엣지 케이스가 걱정된다면 속성 기반 테스트가 정답입니다.
• Criterion 리포트를 통해 성능 변화를 시각적으로 추적하세요.
• 모킹보다는 트레이트 설계를 통해 테스트 가능한 구조를 만드세요.

15. 크레이트 아키텍처 및 API 설계 🟡

학습 목표:

• 모듈 구조의 표준 관례와 **재내보내기(Re-export)**를 이용한 API 정제법을 익힙니다.
• 세련된 크레이트 제작을 위한 공개 API 체크리스트를 학습합니다.
• impl Into, AsRef, Cow를 활용한 편리한(Ergonomic) 인자 전달 패턴을 배웁니다.
• "검증하지 말고 파싱하라(Parse, don't validate)" 원칙과 TryFrom의 가치를 이해합니다.
• 피처 플래그(Feature flags), 조건부 컴파일, 워크스페이스 구조를 마스터합니다.

모듈 구조와 가시성 가이드

성공적인 크레이트는 내부 구조가 복잡하더라도 외부에는 깔끔한 인터페이스를 노출합니다.

• lib.rs: 크레이트의 뿌리입니다. 내부 모듈들을 선언하고, 사용자가 필요한 타입들만 pub use로 재내보내어 API를 큐레이션합니다.
• 가시성 제어: pub(crate)를 활용해 크레이트 내부에서는 자유롭게 접근하되, 외부에는 노출되지 않도록 경계를 설정하세요.

공개 API 설계 체크리스트

1. 빌림(Reference)으로 받고 소유권(Owned)으로 반환: fn process(s: &str) -> String
2. impl Trait 활용: 인자 타입이 명확할 때는 제네릭보다 impl Read처럼 표현하는 것이 가독성에 좋습니다.
3. 패닉 대신 Result: 실패 가능성이 있는 모든 API는 호출자가 처리 방식을 결정할 수 있게 하세요.
4. 표준 트레이트 구현: Debug, Clone, Default 등을 기본적으로 제공하세요.
5. 불가능한 상태를 타입으로 방지: 타입 상태(Type-state) 패턴을 적극 활용하세요.
6. #[must_use] 사용: 반환값이 무시되면 안 되는 중요한 함수나 객체에 표시하세요.
7. #[non_exhaustive] 사용: 공개 열거형에 사용해 나중에 항목이 추가되어도 하위 호환성이 깨지지 않게 하세요.

편리한 인자 패턴: impl Into, AsRef, Cow

사용자가 호출할 때 .to_string()이나 .as_ref()를 남발하지 않도록 설계하세요.

#![allow(unused)]
fn main() {
// ❌ 불편한 방식: 사용자가 직접 String으로 변환해야 함
fn connect(host: String) { ... }

// ✅ 편리한 방식: &str, String 모두 그대로 전달 가능
fn connect(host: impl Into<String>) {
    let host = host.into(); // 내부에서 변환
}
}

• AsRef<T>: 데이터를 읽기만 할 때 사용하세요.
• Cow<'a, T>: 평소에는 빌려 쓰다가 수정이 필요할 때만 비로소 복제(Clone)하고 싶을 때 사용하세요.

검증하지 말고 파싱하라 (Parse, don't validate)

데이터가 유효한지 체크만 하고 다시 원시 타입(String, i32 등)으로 들고 다니지 마세요. 유효성 검사가 완료된 정보만 담을 수 있는 **전용 타입(Newtype)**으로 파싱하세요. 일단 해당 타입의 객체가 생성되었다면, 이후 코드에서는 다시 검증할 필요 없이 안전하게 사용할 수 있습니다.

피처 플래그와 조건부 컴파일

사용자가 필요한 기능만 선택해서 빌드할 수 있게 하여 바이너리 크기와 의존성을 줄이세요. Cargo.toml의 [features] 섹션과 #[cfg(feature = "...")] 속성을 활용합니다.

📝 연습 문제: 크레이트 API 리팩토링 ★★ (~30분)

원시 타입 사용이 남발된(Stringly-typed) API를 TryFrom, 뉴타입, 빌더 패턴을 사용하여 리팩토링해 보세요. 특히 호스트 이름, 포트(1~65535) 등이 파싱 단계에서 완벽히 검증되도록 설계해 보세요.

📌 요약

• API는 유연하게 받고(Into/AsRef), 구체적으로 반환하세요.
• **#[non_exhaustive]**는 라이브러리 유지보수성을 위한 필수 도구입니다.
• 타입 시스템 자체가 보증서가 되도록 설계하세요(Parse, don't validate).
• 공급망 보안: cargo audit과 cargo deny를 정기적으로 실행하여 안전한 의존성을 관리하세요.

16. 비동기/Await 핵심 🔴

학습 목표:

• Rust의 Future와 Go의 고루틴, Python의 asyncio가 어떻게 다른지 이해합니다.
• Tokio 런타임 기초: 태스크 스폰(Spawn), join!, 런타임 설정을 배웁니다.
• 비동기 프로그래밍의 흔한 실수를 방지하는 법을 익힙니다.
• CPU 집약적인 작업을 spawn_blocking으로 분리하는 시점을 결정합니다.

퓨처(Future)와 런타임의 관계

Rust의 비동기 모델은 다른 언어와 근본적으로 다릅니다.

1. Future는 게으른(Lazy) 상태 머신: async fn을 호출해도 아무 일도 일어나지 않습니다. 실행을 위해서는 이를 폴(Poll)해 줄 누군가가 필요합니다.
2. 런타임이 필요함: 표준 라이브러리는 Future 트레이트만 정의할 뿐, 실행기는 제공하지 않습니다. tokio가 가장 널리 쓰이는 실행기입니다.
3. async fn은 문법적 설탕(Sugar): 컴파일러가 이를 Future 트레이트를 구현하는 복잡한 상태 머신 구조체로 변환합니다.

비동기 프로그램의 흔한 실수와 해결법

#![allow(unused)]
fn main() {
// ❌ 비동기 실행기를 멈추게 하는 나쁜 코드
async fn bad() {
    std::thread::sleep(Duration::from_secs(5)); // 스레드 전체가 멈춤!
}

// ✅ 블로킹 작업을 별도 풀로 보내는 좋은 코드
async fn good() {
    tokio::task::spawn_blocking(|| {
        std::thread::sleep(Duration::from_secs(5)); // 전용 스레드에서 실행
    }).await.unwrap();
}
}

태스크 스폰과 구조적 동시성

tokio::spawn은 OS 스레드보다 훨씬 가벼운 비동기 태스크를 생성합니다. 여러 태스크를 효율적으로 관리하기 위한 매크로들을 활용하세요.

• join!: 모든 퓨처가 완료될 때까지 기다립니다.
• try_join!: 하나라도 에러가 발생하면 즉시 중단하고 에러를 반환합니다.
• select!: 가장 먼저 완료되는 퓨처의 결과를 반환합니다(타임아웃이나 취소 로직에 유용).

📝 연습 문제: 타임아웃이 있는 동시 페처 ★ (~25분)

세 개의 비동기 태스크를 tokio::spawn으로 실행하고, 이를 tokio::try_join!으로 묶어 보세요. 전체 작업에 tokio::time::timeout을 걸어 5초 안에 완료되지 않으면 에러를 반환해야 합니다.

📌 요약

• .await가 없으면 아무 일도 일어나지 않습니다. 퓨처는 능동적으로 실행되지 않는 게으른 객체입니다.
• 비동기 코드에서 std::thread::sleep을 절대 사용하지 마세요. 반드시 tokio::time::sleep을 써야 합니다.
• 무거운 CPU 연산은 **spawn_blocking**으로 격리하여 실행기 스레드가 멈추지 않게 하세요.
• Send 제약 조건은 퓨처가 스레드 간에 이동할 수 있음을 보장하는 Rust 특유의 안전 장치입니다.

17. 연습 문제 🟢

이 장은 앞서 배운 디자인 패턴과 실무 기법들을 직접 코드로 구현해보는 종합 연습장입니다.

연습 1: 타입 안전한 상태 머신 ★★ (~30분)

목표: 타입 상태 패턴(Type-state pattern)을 사용해 신호등 상태 머신을 만드세요.

• 상태 순서는 반드시 빨강 → 초록 → 노랑 → 빨강이어야 합니다.
• 정해진 순서 외의 전환은 컴파일 타임에 차단되어야 합니다.

연습 2: PhantomData를 이용한 단위 시스템 ★★ (~30분)

목표: PhantomData를 활용해 물리량 단위를 구분하는 시스템을 구축하세요.

• Meters, Seconds, Kilograms 타입을 정의하세요.
• 같은 단위끼리의 덧셈을 지원하세요.
• 곱셈(Meters * Meters = SquareMeters)과 나눗셈(Meters / Seconds = MetersPerSecond)을 구현하세요.

연습 3: 채널 기반 워크 풀(Worker Pool) ★★★ (~45 min)

목표: 채널을 이용해 작업을 분배하고 처리 결과를 취합하는 워커 풀을 만듭니다.

• 디스패처가 Job 구조체를 채널A로 보냅니다.
• N개의 워커가 채널A에서 작업을 가져와 처리한 뒤, 결과를 채널B로 보냅니다.
• 메인 함수에서 모든 결과가 올바르게 취합되었는지 확인합니다.

연습 4: 고계 함수 콤비네이터 파이프라인 ★★ (~25분)

목표: 데이터 전처리 과정을 체인으로 엮을 수 있는 Pipeline 구조체를 만듭니다.

• .pipe(f)를 호출해 변환 과정을 추가합니다.
• .execute(input)를 호출해 누적된 모든 변환을 순차적으로 실행합니다.

연습 5: thiserror를 활용한 에러 관리 ★★ (~30분)

목표: 라이브러리 개발 시 사용되는 에러 계층 구조를 설계합니다.

• I/O, JSON 파싱, 비즈니스 검증 실패를 모두 포함하는 AppError를 만드세요.
• #[from]을 이용해 ? 연산자로 에러가 자동 변환되는지 확인하세요.

연습 6: 연관 타입을 활용한 리포지토리 패턴 ★★★ (~40분)

목표: 데이터 저장소 작업을 위한 Repository 트레이트를 설계합니다.

• Item, Id, Error를 연관 타입으로 정의하세요.
• 메모리 기반 저장소(InMemoryRepo)를 구현하여 타입 안전성을 확인하세요.

연습 7: Unsafe를 이용한 고성능 고정 크기 벡터 ★★★ (~45분)

목표: 힙 할당 없이 스택에 데이터를 쌓는 FixedVec<T, N>을 만듭니다.

• MaybeUninit을 사용하여 초기화되지 않은 메모리를 관리하세요.
• push, pop, as_slice를 구현하고, 모든 unsafe 블록에 상세한 안전성 주석을 다세요.

연습 8: 선언적 매크로 map! 제작 ★ (~15분)

목표: 표준 vec![] 매크로처럼 HashMap을 생성하는 map!{} 매크로를 만듭니다.

• key => value 쌍을 쉼표로 구분하여 입력받습니다.
• 마지막 쉼표 허용 및 빈 매크로 호출을 지원해야 합니다.

연습 9: 커스텀 Serde 역직렬화기 구현 ★★★ (~45분)

목표: "30s", "1h" 같은 문자열을 std::time::Duration으로 바꾸는 필드를 포함한 설정을 파싱합니다.

• HumanDuration 타입을 만들고 커스텀 직렬화/역직렬화 로직을 작성하세요.

연습 10: 비동기 타임아웃 페처 ★★ (~25분)

목표: 여러 네트워크 요청을 비동기로 동시에 처리하고, 전체 작업에 타임아웃을 겁니다.

• tokio::spawn으로 태스크를 던지고 tokio::try_join!으로 취합하세요.
• tokio::time::timeout을 넘기면 에러를 반환해야 합니다.

연습 11: 비동기 채널 파이프라인 ★★★ (~40분)

목표: 생산자 → 변환기 → 소비자 구조의 비동기 파이프라인을 구축합니다.

• tokio::sync::mpsc 채널을 사용하세요.
• 유한한 버퍼 크기(Bounded channel)를 설정하여 백프레셔(Back-pressure)가 어떻게 작동하는지 관찰하세요.

18. 요약 및 참조 카드 🟢

패턴 결정 가이드

• 원시 타입의 타입 안전성이 필요한가? → 뉴타입(Newtype) 패턴 (3장)
• 컴파일 타임에 상태 전이를 강제해야 하는가? → 타입 상태(Type-state) 패턴 (3장)
• 런타임 데이터는 없지만 타입 정보가 필요한가? → PhantomData (4장)
• Rc/Arc의 순환 참조를 끊어야 하는가? → Weak (9장)
• 여러 타입 중 하나를 다뤄야 하는가?
  • 닫힌 집합(종류가 정해짐) → 열거형(Enum)
  • 열린 집합(추가 가능), 성능 중요 → 제네릭(Generics)
  • 열린 집합, 유연함 중요 → dyn Trait (2장)
• 스레드 간 상태 공유가 필요한가?
  • 단순 카운터/플래그 → 원자적(Atomics) 타입
  • 짧은 임계 구역 → Mutex
  • 읽기 위주 작업 → RwLock
  • 지연 초기화 → OnceLock / LazyLock (6장)
  • 복잡한 상태 관리 → 액터(Actor) + 채널 (5장)
• 계산을 병렬화해야 하는가?
  • 컬렉션 처리 → rayon::par_iter
  • 백그라운드 태스크 → thread::spawn
  • 지역 데이터 대여 → thread::scope
• 비동기 I/O나 네트워킹이 필요한가? → tokio + async/await (16장)
• 에러 처리가 필요한가?
  • 라이브러리 → thiserror (#[derive(Error)])
  • 애플리케이션 → anyhow (Result<T>) (10장)
• 값의 메모리 이동을 막아야 하는가? → Pin (9장)

트레이트 경계 치트 시트

수명 생략(Lifetime Elision) 규칙

컴파일러는 다음 세 가지 경우에 수명을 자동으로 삽입합니다.

1. 각 참조 인자는 자신만의 수명을 가집니다. (fn foo<'a, 'b>(x: &'a str, y: &'b str))
2. 입력 인자가 정확히 하나라면, 그 수명이 모든 출력에 적용됩니다.
3. &self나 &mut self가 있다면, 그 수명이 모든 출력에 적용됩니다.

추가 학습 리소스

Rust 디자인 패턴 및 엔지니어링 가이드 종료

19. 캡스톤 프로젝트: 타입 안전한 태스크 스케줄러 🟢

이 프로젝트는 본서에서 배운 다양한 패턴들을 하나의 완성된 시스템으로 통합하는 과정입니다. 제네릭, 트레이트, 타입 상태(Type-state), 채널, 에러 처리, 테스트 기법을 모두 동원하여 타입 안전하고 동시성을 지원하는 태스크 스케줄러를 구축해 봅니다.

예상 소요 시간: 4~6시간 | 난이도: ★★★

실무 연습 포인트:

• 제네릭과 트레이트 경계 (1~2장)
• 태스크 생명주기를 위한 타입 상태 패턴 (3장)
• 제로 비용 상태 마커를 위한 PhantomData (4장)
• 워커 통신을 위한 채널 (5장)
• 스코프 스레드를 이용한 동시성 (6장)
• thiserror를 활용한 에러 처리 (10장)
• 속성 기반 테스트를 포함한 검증 (14장)
• TryFrom과 유효성 검사 타입 설계 (15장)

프로젝트 개요: 해결해야 할 문제

다음 요구사항을 충족하는 태스크 스케줄러를 만드세요.

1. **태스크(Task)**는 엄격한 생명주기를 가집니다: 대기(Pending) → 실행 중(Running) → 완료(Completed) 혹은 실패(Failed).
2. **워커(Worker)**는 채널에서 태스크를 가져와 실행하고 결과를 보고합니다.
3. **스케줄러(Scheduler)**는 태스크 제출, 워커 관리, 결과 수집을 총괄합니다.
4. 잘못된 상태 전이는 런타임 패닉이 아닌 컴파일 타임 에러로 차단되어야 합니다.

단계별 가이드

1단계: 태스크 타입 정의

PhantomData와 타입 상태 마커를 사용해 Task 구조체를 설계하세요. Pending 상태의 태스크만 start() 메서드를 가질 수 있으며, 호출 시 Running 상태의 태스크를 반환해야 합니다.

2단계: 작업 함구(Work Function) 정의

태스크가 실제로 수행할 로직을 담을 박스형 클로저(Box<dyn FnOnce(...)>)를 포함하는 WorkItem을 만드세요.

3단계: 에러 처리 시스템 구축

thiserror를 사용하여 스케줄러 폐쇄, 태스크 실패, 채널 통신 에러, 워커 패닉 등을 구분하는 에러 열거형을 정의하세요.

4단계: 스케줄러 구현

채널과 스코프 스레드를 사용하여 여러 워커가 병렬로 작업을 처리하고 결과를 수집하는 전체 로직을 완성하세요.

5단계: 통합 테스트 및 검증

• 모든 태스크가 정상 처리되는 케이스(Happy path)
• 특정 태스크가 실패할 때의 에러 핸들링
• 빈 스케줄러가 정상적으로 소멸되는지 확인하는 테스트를 작성하세요.

평가 기준

확장 아이디어 (심화 학습)

기본 스케줄러가 완성되었다면 다음 기능들을 추가해 보세요:

1. 우선순위 큐: 특정 우선순위가 높은 태스크를 먼저 처리합니다.
2. 재시도 전략(Retry Policy): 실패한 태스크를 N번까지 자동으로 재시도합니다.
3. 취소(Cancellation): 특정 TaskId를 가진 대기 중인 태스크를 취소합니다.
4. 비동기 버전: tokio와 비동기 채널을 사용하도록 포팅해 보세요.
5. 메트릭 수집: 각 워커별 처리량, 평균 실행 시간, 실패율을 추적합니다.

본 프로젝트를 성공적으로 마치셨다면, Rust의 핵심 디자인 패턴을 실무에 적용할 준비가 되신 것입니다.