📚 课程目录第3章接口定义原则（上）

3. 接口定义原则（上）：接口的稳定性、抽象性、最小化原则

好，咱们今天聊点实在的。接口定义这件事，说简单也简单，说难也难。我见过太多项目，前期接口拍脑袋定，后期改得鸡飞狗跳。说白了，接口就是模块之间的契约。契约写得好，大家各干各的，互不干扰；契约写得烂，天天扯皮，联调能调到你怀疑人生。

这一章，我们先讲三个最核心的原则：稳定性、抽象性、最小化。这三个原则，是我这些年做嵌入式架构设计时反复验证过的。你把这三点吃透了，接口设计至少不会出大问题。

3.1 稳定性原则：接口一旦发布，就不要轻易改

什么叫稳定性？就是接口对外公布之后，它的函数签名、数据结构、行为语义，尽量保持不变。哪怕你内部实现改得面目全非，接口层也要纹丝不动。

我在一个车载项目中遇到过这种事：A 工程师写了一个驱动接口，B 工程师调用。A 觉得参数顺序不合理，顺手改了。结果 B 那边编译通过，运行直接跑飞。查了一整天，最后发现是参数类型对调了。你说冤不冤？

⚠️ 我曾经踩过的坑： 接口的稳定性不是靠自觉，而是靠机制。没有版本号、没有变更通知、没有评审流程，所谓的稳定性就是一句空话。

保证稳定性的几个实操建议：

接口冻结前充分评审——多找几个调用方一起看，别自己闷头定。
接口变更必须走版本号——v1.0、v1.1、v2.0，每个版本记录变更内容。
提供兼容层——实在要改，旧接口保留，新接口另起一个，用适配器桥接。
头文件加变更日志——我习惯在头文件末尾加一段注释，记录每次修改的日期、作者、原因。

3.2 抽象性原则：隐藏实现细节，暴露行为语义

抽象性，说白了就是「你只管告诉我你要什么，别管我怎么干」。接口应该描述「做什么」，而不是「怎么做」。

举个例子，一个 LED 驱动接口：

// 坏的抽象：暴露了寄存器地址和位操作
void led_set_gpio_bit(uint32_t reg_base, uint8_t pin, uint8_t level);

// 好的抽象：只暴露行为
void led_on(uint8_t led_id);
void led_off(uint8_t led_id);
void led_toggle(uint8_t led_id);

你看，第一个接口把 GPIO 的寄存器细节全暴露了。调用方得知道基地址、引脚号、电平值。万一换芯片了，所有调用代码都得改。第二个接口只关心「开灯」「关灯」「翻转」，底层怎么实现，调用方完全不用管。

  💡 我的经验： 抽象层每多一层，代码的可移植性就上一个台阶。但注意，抽象不是越多越好。过度抽象会让接口变得臃肿，反而失去清晰度。适可而止。

3.3 最小化原则：接口能少一个就少一个

最小化原则，就是接口的数量和复杂度，控制在刚好够用的程度。不要为了「以后可能用到」而提前加接口。你想想看，多一个接口，就多一份维护成本，多一份测试负担，多一份出错的可能。

我见过一个串口驱动，头文件里定义了 30 多个函数。什么 uart_set_baud_rate、uart_set_data_bits、uart_set_stop_bits、uart_set_parity…… 实际上，90% 的场景只需要 uart_init、uart_send、uart_recv 三个函数就够了。

怎么做到最小化？

先写调用代码，再定义接口——从使用者的角度倒推，需要什么就定义什么。
合并同类项——比如 set_baud、set_data_bits、set_stop_bits 可以合并成一个 uart_config 结构体参数。
不要提前暴露内部状态——比如 get_tx_buffer_usage 这种接口，除非调用方明确需要，否则别加。

3.4 头文件设计规范

接口定义最终要落到头文件里。头文件写得好不好，直接决定了接口的可读性和可维护性。我总结了几条硬性规范：

规范项	说明	示例
头文件卫士	防止重复包含，格式统一	`#ifndef __LED_DRV_H__`
包含顺序	先标准库，再芯片库，最后模块内部	`#include <stdint.h>` → `#include "chip.h"` → `#include "led_drv.h"`
注释规范	每个函数都要有 Doxygen 风格注释	`/** @brief 打开指定 LED */`
类型定义	使用 `typedef` 封装底层类型	`typedef uint8_t led_id_t;`
错误码	统一枚举，不要用魔数	`typedef enum { LED_OK, LED_ERR_INVALID_ID } led_err_t;`

📌 小技巧： 我习惯在头文件开头加一段「接口概述」注释，说明这个模块是干什么的、依赖哪些资源、使用注意事项。这样新同事接手时，看一眼就知道大概。

3.5 实战：设计一个 LED 驱动接口

理论说完了，咱们动手写一个。假设我们要设计一个通用的 LED 驱动接口，支持多个 LED、支持 PWM 调光、支持闪烁模式。看看怎么把前面三个原则用进去。

先画一张结构图，理清思路：

好，结构清楚了。现在写头文件：

#ifndef __LED_DRV_H__
#define __LED_DRV_H__

#include <stdint.h>
#include <stdbool.h>

#ifdef __cplusplus
extern "C" {
#endif

/* ========== 类型定义 ========== */

/** @brief LED 标识符 */
typedef uint8_t led_id_t;

/** @brief 亮度等级（0~100） */
typedef uint8_t led_brightness_t;

/** @brief LED 工作模式 */
typedef enum {
    LED_MODE_ON,        /**< 常亮 */
    LED_MODE_OFF,       /**< 熄灭 */
    LED_MODE_BLINK,     /**< 闪烁 */
    LED_MODE_BREATHE    /**< 呼吸灯 */
} led_mode_t;

/** @brief 错误码 */
typedef enum {
    LED_OK = 0,
    LED_ERR_INVALID_ID,
    LED_ERR_INVALID_PARAM,
    LED_ERR_HW_FAILURE
} led_err_t;

/* ========== 接口函数 ========== */

/**
 * @brief 初始化 LED 驱动
 * @return LED_OK 表示成功，其他表示失败
 */
led_err_t led_init(void);

/**
 * @brief 打开指定 LED
 * @param id LED 标识符
 * @return LED_OK 或错误码
 */
led_err_t led_on(led_id_t id);

/**
 * @brief 关闭指定 LED
 * @param id LED 标识符
 * @return LED_OK 或错误码
 */
led_err_t led_off(led_id_t id);

/**
 * @brief 设置 LED 亮度
 * @param id   LED 标识符
 * @param brightness 亮度值（0~100）
 * @return LED_OK 或错误码
 */
led_err_t led_set_brightness(led_id_t id, led_brightness_t brightness);

/**
 * @brief 设置 LED 工作模式
 * @param id   LED 标识符
 * @param mode 工作模式
 * @return LED_OK 或错误码
 */
led_err_t led_set_mode(led_id_t id, led_mode_t mode);

#ifdef __cplusplus
}
#endif

#endif /* __LED_DRV_H__ */

你看这个接口，一共就 5 个函数。调用方想开灯就 led_on(0)，想调暗就 led_set_brightness(0, 30)，想闪烁就 led_set_mode(0, LED_MODE_BLINK)。底层是用 GPIO 还是用 PWM，是软件定时器还是硬件定时器，调用方完全不用关心。

  ✅ 这个接口体现了三个原则：
  稳定性——函数签名固定，不会因为硬件变化而改变。
抽象性——只暴露「开」「关」「调光」「模式」，隐藏了寄存器、定时器、中断等细节。
最小化——5 个函数覆盖了 95% 的使用场景。没有多余的 get_status、reset 之类的东西。

嗯，这里要注意一点：接口设计不是一锤子买卖。你第一次设计时，可能只想到常亮和熄灭。后来需求来了，要加闪烁。这时候怎么办？加一个 led_set_mode 函数，把闪烁作为模式加进去。原来的 led_on 和 led_off 保持不变。这就是稳定性原则的体现——旧接口不动，新功能通过扩展实现。

我个人习惯，每次加新接口之前，先问自己三个问题：

这个接口真的必须暴露给调用方吗？
能不能用现有接口组合实现？
如果必须加，命名和参数是否和现有风格一致？

这三个问题问完，至少能砍掉一半不必要的接口。