3. 接口设计基本原则

在嵌入式C++项目中，接口不是“把函数声明放进头文件”这么简单。接口是模块之间签订的契约：调用方依赖它，实现方兑现它，测试代码围绕它构造桩件，版本迭代还要兼容它。接口设计一旦失当，最直接的后果是编译依赖扩散、二进制体积膨胀、单元测试难以隔离，最终导致“改一处、崩一片”。本节围绕五条基本原则展开：接口与实现分离、最小接口、依赖倒置、单一职责、接口稳定性与版本管理。

一、接口与实现分离：让依赖停在抽象层

接口与实现分离的核心目标是切断“调用方直接依赖具体实现”的编译期耦合。在嵌入式开发中，这一点尤其重要：同一份业务逻辑可能运行在STM32、ESP32或Linux网关之上，底层驱动、RTOS、文件系统各不相同。如果业务代码直接#include "stm32_hal_i2c.hpp"，那么换平台就意味着重写业务层。

正确做法是把“能做什么”与“怎么做”拆开。接口只描述行为语义、参数约束和错误返回，不暴露寄存器、句柄、DMA通道等实现细节。例如传感器读取接口只应表达“读取一次测量值”，而不应暴露I2C地址和时序。

// sensor_reader.hpp —— 纯接口，不包含任何平台头文件
class SensorReader {
public:
    virtual ~SensorReader() = default;
    // 返回0成功，负值为错误码；out_value单位：摄氏度
    virtual int readTemperature(float& out_value) = 0;
};

// bmp280_reader.hpp —— 实现方，才依赖具体总线
class Bmp280Reader final : public SensorReader {
public:
    explicit Bmp280Reader(I2cBus& bus, uint8_t addr);
    int readTemperature(float& out_value) override;
private:
    I2cBus& bus_;
    uint8_t addr_;
};

这样，业务层只依赖SensorReader，编译时不需要知道BMP280的存在；测试时可以用FakeSensorReader注入固定值，无需真实硬件。

二、最小接口：只暴露调用方真正需要的能力

最小接口原则（Interface Segregation）要求接口尽量窄。一个“大而全”的接口会强迫所有实现者实现无关方法，也会让调用方看到不该看到的能力。嵌入式场景中常见反例是“万能设备接口”：同时包含初始化、读、写、复位、升级、日志、自检。结果是只想读温度的模块也被迫链接升级逻辑，增加代码体积和测试负担。

判断接口是否最小，可以用三个问题检验：调用方是否真的会调用每个方法？每个方法是否只服务于一个明确场景？实现者是否可能对某个方法只能抛出“不支持”？如果第三个问题答案是“是”，就说明接口该拆了。

三、依赖倒置：高层策略不依赖低层细节

依赖倒置原则（DIP）指出：高层模块不应依赖低层模块，二者都应依赖抽象；抽象不应依赖细节，细节应依赖抽象。在嵌入式C++中，这通常表现为“业务逻辑持有接口引用，由外部注入具体实现”。

例如，数据采集任务不应直接创建FlashLogger，而应依赖ILogger接口。运行时可以注入Flash实现、串口实现或内存环形缓冲实现。这样，同一套采集逻辑在量产固件中写Flash，在单元测试中写内存，在调试版本中打串口。

class DataCollector {
public:
    DataCollector(SensorReader& sensor, ILogger& logger)
        : sensor_(sensor), logger_(logger) {}

    void tick() {
        float t = 0.0f;
        if (sensor_.readTemperature(t) == 0) {
            logger_.log("temp=%.2f", t);
        }
    }
private:
    SensorReader& sensor_;
    ILogger& logger_;
};

注意这里使用的是引用而非指针，表达“生命周期由调用方保证”的契约；如果允许为空，才使用指针并在接口文档中说明。

四、单一职责：一个接口只因一个原因变化

单一职责原则（SRP）在接口设计中的含义是：一个接口应该只有一个变化方向。如果传感器接口同时承担“读取测量值”和“校准参数持久化”，那么测量协议变化和存储介质变化都会导致该接口修改，调用方和实现方都被迫跟着变。

更细的拆分方式是按“变化原因”切分：SensorReader负责测量，CalibrationStore负责校准参数读写，SensorLifecycle负责初始化与自检。三者可以独立演进，也可以由同一个具体类实现多个接口，但调用方只看到自己需要的那一个。

五、接口稳定性与版本管理：契约要能演进

接口一旦发布，就被调用方、测试、文档和二进制兼容性同时依赖。稳定性不是“永不修改”，而是“修改可控、可预期、可迁移”。在嵌入式C++中，常用策略包括：

• 只增不改：新增虚函数时提供默认实现，避免破坏已有实现类；但要注意默认实现可能掩盖错误，需在文档中标注。
• 版本命名空间：如v1::SensorReader与v2::SensorReader并存，旧调用方继续使用v1，新功能走v2。
• 能力查询：通过supports(Capability)或独立的能力接口，让调用方在运行时判断实现是否支持某特性，而不是依赖版本号硬编码。
• ABI边界：跨动态库或跨编译单元时，避免在接口中暴露STL容器、异常和RTTI；使用固定宽度整数、POD结构体和错误码。

六、案例与复盘：一次接口重构

某电机控制项目最初定义了一个Motor接口，包含init()、setSpeed()、readEncoder()、saveParams()、updateFirmware()。随着产品线扩展，步进电机实现不需要readEncoder()，只能空实现；测试桩件也被迫实现五个方法。重构后拆为MotorDriver（初始化与设速）、EncoderReader（编码器读取）、ParamStore（参数持久化）、FirmwareUpdater（升级）。业务层只注入自己需要的接口，测试桩件从五个空方法缩减为一个。

综合来看，五条原则共同服务于一个目标：让接口成为稳定、清晰、可替换的契约。接口与实现分离解决耦合方向，最小接口控制暴露面，依赖倒置保证高层策略独立，单一职责限制变化影响范围，稳定性与版本管理让契约能够长期演进。在嵌入式C++中，这些原则最终都要落到头文件依赖、虚函数表体积、错误码约定和ABI边界这些具体工程约束上。