零成本类型状态机：Rust 编译期工程实战

编译期保证的 API 设计

接下来为每个状态提供专属的方法集：

use std::marker::PhantomData;
use std::net::{SocketAddr, TcpListener as StdListener};

impl TcpStream<state::Closed> {
    pub fn new() -> Self {
        TcpStream {
            inner: InnerTcpStream::new(),
            _state: PhantomData,
        }
    }

    pub fn connect(self, addr: SocketAddr) -> Result<TcpStream<state::Connected>, ConnectError> {
        self.inner.connect(addr)?;
        Ok(TcpStream {
            inner: self.inner,
            _state: PhantomData,
        })
    }

    pub fn bind(addr: SocketAddr) -> Result<TcpStream<state::Listening>, BindError> {
        let inner = InnerTcpStream::bind(addr)?;
        Ok(TcpStream {
            inner,
            _state: PhantomData,
        })
    }
}

impl TcpStream<state::Listening> {
    pub fn accept(self) -> Result<(TcpStream<state::Connected>, SocketAddr), AcceptError> {
        let (inner, peer_addr) = self.inner.accept()?;
        Ok((
            TcpStream { inner, _state: PhantomData },
            peer_addr,
        ))
    }
}

impl TcpStream<state::Connected> {
    pub fn write(&mut self, buf: &[u8]) -> Result<usize, WriteError> {
        self.inner.send(buf)
    }

    pub fn read(&mut self, buf: &mut [u8]) -> Result<usize, ReadError> {
        self.inner.recv(buf)
    }

    pub fn close(self) -> TcpStream<state::Shutdown> {
        self.inner.shutdown();
        TcpStream {
            inner: self.inner,
            _state: PhantomData,
        }
    }

    pub fn into_inner(self) -> InnerTcpStream {
        self.inner
    }
}

现在看看编译期保护效果——以下代码无法编译：

fn main() {
    let stream = TcpStream::new(); // 状态: Closed
    stream.write(b"hello");  // 编译错误: method not found

    let mut connected = stream.connect("127.0.0.1:8080".parse().unwrap()).unwrap();
    connected.write(b"hello"); // ! 编译通过

    let closed = connected.close();
    closed.read(&mut buf); // 编译错误: method not found
    closed.write(b"data"); // 编译错误: method not found
}

这就是零成本抽象的精髓：错误在编译期暴露，运行时零额外开销。

验证器的真实工程案例

类型状态模式在工业级项目中最典型的应用是构建验证器（Builder Pattern）。

// HTTP 请求构建器——确保必需参数在发送前已被设置
pub struct HttpRequestBuilder<B, H, Q> {
    base_url: B,      // Option<&str> 或 &str
    headers: H,       // bool 或 Vec<(String, String)>
    query_params: Q,  // bool 或 Vec<(String, String)>
    method: Method,
    body: Option<Bytes>,
}

// 类型别名简化使用
pub type BuilderInitial = HttpRequestBuilder<(), (), ()>;
pub type BuilderReady = HttpRequestBuilder<&str, Vec<(String, String)>, Vec<(String, String)>>;

impl BuilderInitial {
    pub fn new() -> Self {
        HttpRequestBuilder {
            base_url: (),
            headers: (),
            query_params: (),
            method: Method::GET,
            body: None,
        }
    }

    pub fn base_url(self, url: &str) -> HttpRequestBuilder<&str, (), ()> {
        HttpRequestBuilder {
            base_url: url,
            headers: (),
            query_params: (),
            method: self.method,
            body: self.body,
        }
    }
}

impl HttpRequestBuilder<&str, (), ()> {
    pub fn add_header(self, key: &str, value: &str) -> HttpRequestBuilder<&str, Vec<(String, String)>, ()> {
        let mut headers = Vec::new();
        headers.push((key.to_string(), value.to_string()));
        HttpRequestBuilder {
            base_url: self.base_url,
            headers,
            query_params: (),
            method: self.method,
            body: self.body,
        }
    }
}

impl HttpRequestBuilder<&str, Vec<(String, String)>, ()> {
    pub fn add_query(self, key: &str, value: &str) -> BuilderReady {
        let mut query = Vec::new();
        query.push((key.to_string(), value.to_string()));
        HttpRequestBuilder {
            base_url: self.base_url,
            headers: self.headers,
            query_params: query,
            method: self.method,
            body: self.body,
        }
    }

    pub fn post(self) -> BuilderReady {
        HttpRequestBuilder {
            base_url: self.base_url,
            headers: self.headers,
            query_params: self.query_params,
            method: Method::POST,
            body: self.body,
        }
    }
}

impl HttpRequestBuilder<&str, Vec<(String, String)>, Vec<(String, String)>> {
    pub fn send(self) -> Result<HttpResponse, RequestError> {
        let mut req = http::Request::builder()
            .method(self.method)
            .uri(self.base_url);

        for (k, v) in &self.headers {
            req = req.header(k, v);
        }

        // 构建查询字符串...
        let uri = format!("{}?{}", self.base_url, query_string);
        // 发送请求...
    }
}

使用效果：

fn api_call() {
    // ! 错误：缺少 base_url
    // HttpRequestBuilder::new().send();

    // ! 错误：缺少 headers
    // HttpRequestBuilder::new().base_url("http://api.example.com").send();

    // 正确流程
    let response = HttpRequestBuilder::new()
        .base_url("http://api.example.com/v1/data")
        .add_header("Authorization", "Bearer token123")
        .add_query("page", "1")
        .post()
        .send()
        .expect("request failed");

    println!("Status: {}", response.status());
}

状态机高阶：泛型组合与验证链

真正强大的类型系统用法是多类型参数组合——让类型的"形状"精确反映状态空间：

// GPIO 引脚配置状态机
pub struct Pin<P, D, M> {
    port: PhantomData<P>,
    direction: PhantomData<D>,
    mode: PhantomData<M>,
    // 实际寄存器操作句符
    reg: &'static mut GpioRegisters,
}

mod gpio {
    // 端口
    pub struct PortA;
    pub struct PortB;
    pub struct PortC;

    // 引脚
    pub struct Pin0;  pub struct Pin1;  pub struct Pin2;
    pub struct Pin3;  pub struct Pin4;  pub struct Pin5;
    pub struct Pin6;  pub struct Pin7;  pub struct Pin8;
    pub struct Pin9;  pub struct Pin10; pub struct Pin11;
    pub struct Pin12; pub struct Pin13; pub struct Pin14; pub struct Pin15;

    // 方向
    pub struct Input;
    pub struct Output;
    pub struct Alternate;
    pub struct Analog;

    // 模式
    pub struct Unconfigured;
    pub struct PushPull;
    pub struct OpenDrain;
    pub struct AlternateFunction { af: u8 }
}

use gpio::*;

impl<P: ValidPort, N: ValidPin> Pin<P, N, Unconfigured, ()> {
    pub fn new(port: P, pin: N) -> Self {
        Pin {
            port: PhantomData,
            direction: PhantomData,
            mode: PhantomData,
            reg: GpioRegisters::get(port, pin),
        }
    }

    pub fn as_input(self) -> Pin<P, N, Input, ()> {
        self.reg.set_mode(Input::MODE);
        Pin { reg: self.reg, ..unsafe_new() }
    }

    pub fn as_output(self) -> Pin<P, N, Output, ()> {
        self.reg.set_mode(Output::MODE);
        Pin { reg: self.reg, ..unsafe_new() }
    }

    pub fn as_alternate(self, af: u8) -> Result<Pin<P, N, Alternate, ()>, GpioError> {
        if af > 15 {
            return Err(GpioError::InvalidAlternateFunction);
        }
        self.reg.set_mode(Alternate::MODE);
        self.reg.set_alternate(af);
        Ok(Pin { reg: self.reg, ..unsafe_new() })
    }
}

impl<P, N> Pin<P, N, Output, ()> {
    pub fn push_pull(self) -> Pin<P, N, Output, PushPull> {
        self.reg.set_output_type(PushPull::OTYPE);
        Pin { reg: self.reg, ..unsafe_new() }
    }

    pub fn open_drain(self) -> Pin<P, N, Output, OpenDrain> {
        self.reg.set_output_type(OpenDrain::OTYPE);
        Pin { reg: self.reg, ..unsafe_new() }
    }

    // 只有配置了输出模式的引脚才能写
    pub fn set_high(&mut self) where N: ValidPinIdx {
        self.reg.set_output(true);
    }

    pub fn set_low(&mut self) where N: ValidPinIdx {
        self.reg.set_output(false);
    }
}

impl<P, N, M> Pin<P, N, Input, M> {
    // 只有输入模式才能读
    pub fn read(&self) -> bool {
        self.reg.read_input()
    }
}

使用效果 —— 以下代码无法通过编译：

let pin = Pin::new(PortA, Pin5);

// ! 编译错误：输入模式没有 set_high 方法
// pin.as_input().set_high();

// ! 编译错误：必须先配置方向再配置输出类型
// let pin = Pin::new(PortA, Pin5).push_pull();

// 正确链式调用
let mut led = Pin::new(PortA, Pin5)
    .as_output()
    .pin_mode();

led.set_high();
led.set_low();

let button = Pin::new(PortB, Pin3).as_input();
let is_pressed = button.read(); // 编译通过：输入模式支持 read

与 async/await 的梦幻组合

类型状态机在异步 I/O 场景下特别有价值——确保异步资源在正确的生命周期使用：

pub struct AsyncChannel<S> {
    inner: InnerChannel,
    _state: PhantomData<S>,
}

mod channel_state {
    pub struct Created;
    pub struct Open;      // 可以发送/接收
    pub struct HalfClosedRead;  // 只能收
    pub struct HalfClosedWrite; // 只能发
    pub struct Closed;
}

impl AsyncChannel<channel_state::Created> {
    pub async fn open(self) -> io::Result<AsyncChannel<channel_state::Open>> {
        self.inner.handshake().await?;
        Ok(AsyncChannel {
            inner: self.inner,
            _state: PhantomData,
        })
    }

    pub fn configure(mut self, cfg: ChannelConfig) -> Self {
        self.inner.apply_config(cfg);
        self
    }
}

impl AsyncChannel<channel_state::Open> {
    pub async fn send(&mut self, msg: Message) -> Result<(), SendError> {
        self.inner.write_message(&msg).await?;
        Ok(())
    }

    pub async fn recv(&mut self) -> Result<Message, RecvError> {
        let msg = self.inner.read_message().await?;
        Ok(msg)
    }

    pub fn close_read(self) -> AsyncChannel<channel_state::HalfClosedRead> {
        self.inner.shutdown_read();
        AsyncChannel {
            inner: self.inner,
            _state: PhantomData,
        }
    }

    pub fn close_write(self) -> AsyncChannel<channel_state::HalfClosedWrite> {
        self.inner.shutdown_write();
        AsyncChannel {
            inner: self.inner,
            _state: PhantomData,
        }
    }

    pub async fn close(self) -> io::Result<AsyncChannel<channel_state::Closed>> {
        self.inner.flush().await?;
        self.inner.shutdown();
        Ok(AsyncChannel {
            inner: self.inner,
            _state: PhantomData,
        })
    }
}

impl AsyncChannel<channel_state::HalfClosedRead> {
    // 只允许接收
    pub async fn recv(&mut self) -> Result<Message, RecvError> {
        self.inner.read_message().await
    }

    pub async fn close(self) -> io::Result<AsyncChannel<channel_state::Closed>> {
        self.inner.flush().await?;
        self.inner.shutdown();
        Ok(AsyncChannel {
            inner: self.inner,
            _state: PhantomData,
        })
    }
}

这样，以下错误在编译期就被拦截：

async fn process(msg: Message) {
    let mut ch = AsyncChannel::new().open().await.unwrap();

    // ! 编译错误：HalfClosedRead 没有 send 方法
    // let closed = ch.close_read();
    // closed.send(msg).await;

    ch.send(msg).await.unwrap(); // 编译通过

    // 在 Open 状态可以正常接收
    let response = ch.recv().await.unwrap();
    handle_response(response).await;
}

运行时零开销证明

类型状态模式的"体感开销"常被高估。我们用一个简单的基准测试验证：

use criterion::{black_box, criterion_group, criterion_main, Criterion};

// 运行时版本（枚举方式）
fn runtime_state_machine(stages: &[Stage]) -> usize {
    let mut conn = RuntimeConnection::new(RuntimeState::Init);
    for stage in stages {
        match stage {
            Stage::Write(data) => {
                if let RuntimeState::Open = conn.state {
                    conn.write(black_box(data));
                } else {
                    panic!("invalid state");
                }
            }
            Stage::Read => {
                if let RuntimeState::Open = conn.state {
                    conn.read();
                } else {
                    panic!("invalid state");
                }
            }
            Stage::Close => {
                conn.state = RuntimeState::Closed;
            }
        }
    }
    conn.bytes_written
}

// 类型状态版本
fn typestate_machine(stages: &[Stage]) -> usize {
    let conn = TypeStateConnection::new();
    let mut conn = conn.connect();
    for stage in stages {
        match stage {
            Stage::Write(data) => conn = conn.write(black_box(data)),
            Stage::Read => conn.read(),
            Stage::Close => {
                let _ = conn.close();
            }
        }
    }
    conn.bytes_written()
}

// 基准测试显示两条路径性能几乎一致
// 编译器已将类型参数完全单态化（monomorphization）
// 所有状态判断在编译期消除，生成的机器码与手写 C 等价

使用 cargo benchtypestate 实测表明：

结论：类型状态版本的编译器已经将全部状态判断在编译期消除，生成的机器码与手写 C 等价，无额外运行时开销。

何时使用、何时回避

类型状态模式不是银枪弹药，在以下场景特别合适：

强烈推荐的场景：

• 硬件抽象层 (HAL) 和外设驱动：GPIO、UART、SPI、I2C 都有严格的状态转换约束
• 网络协议栈：TLS 握手、TCP 连接、HTTP/2 流的状态管理需要严格保证
• 构建器模式：配置选项的依赖关系复杂，允许的组合远少于笛卡尔积
• 资源生命周期：文件句柄、锁、事务的 open-lock-use-close 流程
• 加密协议：密钥派生、认证加密的操作顺序必须严格遵守

不建议使用的场景：

• 状态数量极动态、运行时有大量分支的状态机（例如 GUI 事件处理）
• 状态类型需要序列化/反序列化的场景
• 编译时间成为严重瓶颈的项目（每个状态变成一个类型，大幅增加 LLVM IR）
• 团队对 Rust 类型系统不够熟悉时，可能导致过度工程

进阶技巧与模式

1. 状态转换 trait 的泛型约束

// 用 trait 约束允许的状态链
pub trait AllowedTransition<From, To> {}

impl AllowedTransition<Idle, Running> for ApiService {}
impl AllowedTransition<Running, Paused> for ApiService {}
impl AllowedTransition<Paused, Running> for ApiService {}
impl AllowedTransition<Running, Shutdown> for ApiService {}

pub fn transition<S, T>(svc: Service<S>) -> Service<T>
where
    Self: AllowedTransition<S, T>,
{
    // 状态转换逻辑
}

2. 与 const generics 结合

// 编译期已知大小的缓冲区 + 类型状态
pub struct CircularBuffer<T, const N: usize, S: BufferState> {
    data: [MaybeUninit<T>; N],
    read_idx: usize,
    write_idx: usize,
    _state: PhantomData<S>,
}

pub trait BufferState {}
pub struct Empty;
pub struct NonEmpty;
pub struct Full;
impl BufferState for Empty {}
impl BufferState for NonEmpty {}
impl BufferState for Full {}

3. 运行时状态到类型的桥接

有时候最终状态只有在运行时才能确定，可以用枚举恢复：

pub enum TcpConnectionState {
    Closed(TcpStream<state::Closed>),
    Connected(TcpStream<state::Connected>),
    Shutdown(TcpStream<state::Shutdown>),
}

impl TcpConnectionState {
    fn from_inner(inner: InnerTcpStream) -> Self {
        match inner.current_state() {
            TcpState::Closed => TcpConnectionState::Closed(TcpStream {
                inner, _state: PhantomData,
            }),
            TcpState::Established => TcpConnectionState::Connected(TcpStream {
                inner, _state: PhantomData
            }),
            _ => TcpConnectionState::Shutdown(TcpStream {
                inner, _state: PhantomData
            }),
        }
    }
}

结语

类型状态模式是 Rust 将"正确性"从运行时推向编译时最优雅的工程实践之一。它利用零成本的泛型抽象，让非法状态转换直接成为编译错误，从根本上消灭了运行时状态不匹配这一类 bug。

这套模式在 embedded-hal、wgpu、tokio、hyper 等顶级 Rust 项目中已有大量成熟实践。对于任何涉及严格状态转换的系统编程场景，类型状态模式都值得作为默认的 API 设计手段 —— 并在遭遇性能或复杂度问题时，再退化为更简单的方案。毕竟，最好的错误是你根本无法写出的错误。