类型状态编程：用 Rust 类型系统构建零成本的编译时安全状态机#

在嵌入式、驱动开发或协议实现中，我们经常遇到这样的场景：硬件外设或协议栈必须按照严格的顺序进行配置和使用。违反顺序会导致未定义行为、硬件出错或协议违规。传统的做法是加入大量的运行时检查，但这会带来性能开销和不良的开发者体验。如果能让编译器来替我们保证顺序的正确性，并且不产生任何运行时成本，那该多好？这正是 类型状态编程 所擅长的。

一、一个典型的“顺序依赖”问题#

假设我们要配置一个 GPIO 引脚。硬件手册规定：

必须先使能（Enable）引脚，才能配置它的方向（输入或输出）。
只有在输入模式下，才能设置上拉/下拉电阻和读取电平。
只有在输出模式下，才能设置输出电平。

如果我们用最直接的方式设计 API，往往会得到这样的代码：

pub struct Gpio {
    reg: GpioRegisters,
}

impl Gpio {
    pub fn enable(&mut self) { self.reg.modify(...); }
    pub fn set_direction(&mut self, output: bool) -> Result<(), Error> {
        if !self.is_enabled() { return Err(Error::NotEnabled); }
        // ...
    }
    pub fn set_pull(&mut self, mode: PullMode) -> Result<(), Error> {
        if !self.is_enabled() { return Err(Error::NotEnabled); }
        if !self.is_input() { return Err(Error::WrongDirection); }
        // ...
    }
    pub fn set_output(&mut self, high: bool) -> Result<(), Error> {
        if !self.is_enabled() { return Err(Error::NotEnabled); }
        if !self.is_output() { return Err(Error::WrongDirection); }
        // ...
    }
}

rust

这段代码存在三个问题：

运行时开销：每个方法都要读取寄存器检查状态，甚至多次读取。
用户负担：调用者必须记住顺序，而且得到的只是 Err，缺乏指引。
语义模糊：API 未能反映硬件的真实约束，容易误用。

二、类型状态方案：用类型编码状态#

类型状态的核心思想是：将对象可能处于的每一种“状态”表示为不同的 Rust 类型。状态之间的合法转换通过消费旧状态、返回新状态的方法来强制执行。这样，非法操作在编译期就被阻止，而不会产生任何运行时检测开销。

第一步：定义状态类型#

我们定义一组零大小的类型（Zero-Sized Types，ZST），它们只用于类型标记，不占用实际内存：

// 状态标记类型
struct Disabled;
struct Enabled;
struct Input;
struct Output;
struct PullUp;
struct PullDown;
struct HighZ;
struct DontCare; // 用于未使用的状态参数

rust

第二步：用泛型参数表达当前状态#

Gpio 结构体现在带有三个类型参数，分别代表：使能状态、方向、具体模式。

pub struct Gpio<ENABLED, DIRECTION, MODE> {
    reg: GpioRegisters,
    _enabled: core::marker::PhantomData<ENABLED>,
    _direction: core::marker::PhantomData<DIRECTION>,
    _mode: core::marker::PhantomData<MODE>,
}

rust

PhantomData 是 Rust 的标准零大小类型，它告诉编译器我们“拥有”这些类型参数，但实际上并不存储它们，因此不会增加结构体的大小。

第三步：定义状态转换函数#

状态转换函数通常以 into_xxx 命名，它们消费当前的 Gpio 实例，并返回一个新类型的新实例。

impl Gpio<Disabled, DontCare, DontCare> {
    /// 使能并配置为输入模式（默认高阻）
    pub fn into_enabled_input(self) -> Gpio<Enabled, Input, HighZ> {
        // 直接操作硬件寄存器，无需任何检查！
        self.reg.modify(|_r, w| {
            w.enable().enabled()
             .direction().input()
             .input_mode().high_z()
        });
        Gpio {
            reg: self.reg,
            _enabled: PhantomData,
            _direction: PhantomData,
            _mode: PhantomData,
        }
    }

    /// 使能并配置为输出模式
    pub fn into_enabled_output(self) -> Gpio<Enabled, Output, DontCare> {
        self.reg.modify(|_r, w| {
            w.enable().enabled()
             .direction().output()
        });
        Gpio {
            reg: self.reg,
            _enabled: PhantomData,
            _direction: PhantomData,
            _mode: PhantomData,
        }
    }
}

rust

注意：这些方法只存在于 Gpio<Disabled, DontCare, DontCare> 上，也就是说，只有尚未使能的引脚才能调用它们。一旦引脚被使能，这些方法就“消失”了，因为类型已经改变。

第四步：不同状态提供不同方法#

现在，我们可以为特定状态组合实现方法，完全无需检查：

// 只有输入状态才有的方法
impl<MODE> Gpio<Enabled, Input, MODE> {
    pub fn read(&self) -> bool {
        // 安全：类型保证了引脚已使能且为输入
        self.reg.read().input_status().bit_is_set()
    }

    pub fn into_pull_up(self) -> Gpio<Enabled, Input, PullUp> {
        self.reg.modify(|_r, w| w.input_mode().pull_up());
        Gpio { reg: self.reg, _enabled: PhantomData, _direction: PhantomData, _mode: PhantomData }
    }

    pub fn into_pull_down(self) -> Gpio<Enabled, Input, PullDown> {
        self.reg.modify(|_r, w| w.input_mode().pull_down());
        Gpio { reg: self.reg, _enabled: PhantomData, _direction: PhantomData, _mode: PhantomData }
    }
}

// 只有输出状态才有的方法
impl Gpio<Enabled, Output, DontCare> {
    pub fn set_high(&mut self) {
        self.reg.modify(|_r, w| w.output_status().high());
    }

    pub fn set_low(&mut self) {
        self.reg.modify(|_r, w| w.output_status().low());
    }
}

rust

第五步：使用体验#

现在，用户代码变得既安全又直观：

let gpio = get_gpio_from_hal(); // 类型为 Gpio<Disabled, DontCare, DontCare>

// 配置为输入并开启上拉
let input_pin = gpio.into_enabled_input()    // 现在类型是 Gpio<Enabled, Input, HighZ>
                    .into_pull_up();         // 现在类型是 Gpio<Enabled, Input, PullUp>

let level = input_pin.read(); // OK

// input_pin.set_high(); // ❌ 编译错误！输入引脚没有 set_high 方法

// 重新配置为输出
let mut output_pin = input_pin.into_enabled_output(); // 现在类型是 Gpio<Enabled, Output, DontCare>
output_pin.set_high(); // OK
output_pin.set_low();  // OK

// output_pin.read(); // ❌ 编译错误！输出引脚没有 read 方法

rust

三、零成本抽象：这是如何做到的？#

零成本抽象 是 Rust 的核心原则之一：你不需要为不使用的东西付出代价，而使用抽象层也不会引入额外开销。类型状态编程完美体现了这一点：

没有运行时状态存储：状态类型是零大小的，它们在编译期被擦除，不会占用任何内存空间。
没有运行时检查：所有状态合法性验证都发生在编译期的类型检查阶段。最终的机器码中，方法调用直接转化为寄存器操作，没有任何额外的分支或条件判断。
单态化（Monomorphization）：由于 Gpio 是泛型，编译器会为每个具体的状态组合生成专门的代码。这些代码中不包含任何与状态判断相关的逻辑，因为状态已经是类型的一部分，编译时就确定了。

反观传统方式，每个方法都要读取寄存器判断状态，这导致了额外的内存访问和分支预测开销。而类型状态方式在编译期就排除了非法路径，运行时只需要执行合法路径上的操作，与直接手写硬件寄存器操作一样高效。

我们可以通过一个简单的对比来感受：

维度	运行时检查方式	类型状态方式
状态存储	可能需要标志位	类型参数，零大小
方法调用开销	读取寄存器 + 分支	仅寄存器操作
非法调用处理	返回 `Err`	编译错误
出错时机	运行时	编译时
用户体验	需要文档和测试	编译器引导

四、类型状态的适用场景#

类型状态编程并非银弹，它在以下场景中尤其适用：

嵌入式开发：外设初始化、电源管理、时钟配置等有严格顺序的操作。
协议栈实现：TCP 状态机、TLS 握手流程等。
事务管理：数据库连接状态、文件打开状态等。
Builder 模式：构建复杂对象时强制必填字段和正确顺序（如我们上一篇文章讨论的）。

类型状态的核心价值在于：将程序的不变量编码到类型系统中，让编译器替你验证。

五、总结#

类型状态编程是一种利用 Rust 强大类型系统来提升代码安全性和性能的设计模式。它通过将状态表示为类型，将状态转换表示为类型转换，从而在编译期排除所有非法状态组合。这不仅消除了运行时的检查开销，还极大地改善了 API 的易用性和安全性。

Rust 的零成本抽象理念在这里得到了完美体现：我们使用高级抽象（类型状态），却生成了与手写底层代码一样高效的机器码。你付出的只是设计类型系统的初始脑力，换回的是免于运行时错误的安心和更高的性能。

如果你正在设计一个具有严格顺序依赖的 API，不妨思考一下：能否用类型状态让编译器替你把关？ 答案往往是肯定的，而且你会获得出乎意料的收益。

理解 Rust 的类型状态编程

类型状态编程：用 Rust 类型系统构建零成本的编译时安全状态机#

一、一个典型的“顺序依赖”问题#

二、类型状态方案：用类型编码状态#

第一步：定义状态类型#

第二步：用泛型参数表达当前状态#

第三步：定义状态转换函数#

第四步：不同状态提供不同方法#

第五步：使用体验#

三、零成本抽象：这是如何做到的？#

四、类型状态的适用场景#

五、总结#