2. 嵌入式系统基础

说到模块化设计，很多人第一反应是「把代码拆成几个文件」。但拆完才发现，模块之间互相调用、全局变量满天飞，改一个地方崩一片。问题出在哪？接口没有定义清楚。

我做了十几年嵌入式，见过太多项目因为接口模糊而返工。说白了，接口就是模块之间的「契约」。今天咱们就聊聊，怎么用C语言头文件把这个契约写明白。

为什么是C语言头文件？

你可能想问：现在都流行用专门的IDL工具，比如Protobuf、Thrift，为什么还要用C头文件？

原因很简单：嵌入式环境资源受限。很多MCU上跑不了复杂的IDL解析器，而且C头文件是编译器原生支持的，零运行时开销。我在一个车载ECU项目中，整个系统只有64KB Flash，用Protobuf根本塞不下，最后还是回归到头文件定义。

但注意，我说的不是随便写个.h文件就完事了。我们需要一套规范化的头文件编写方法，让它真正起到IDL的作用。

接口定义的核心要素

一个合格的模块接口头文件，应该包含以下内容：

嗯，这里要注意：头文件里只放接口声明，不要放实现细节。我见过有人把静态函数、内部全局变量都塞到头文件里，结果其他模块直接访问了内部数据，耦合得一塌糊涂。

实战：一个传感器模块的接口定义

咱们直接看代码。下面是一个温度传感器模块的接口头文件，我按照IDL的思路来组织：

/* ============================================================
 * 模块: 温度传感器 (Temperature Sensor)
 * 文件: temp_sensor_if.h
 * 版本: v1.2.0
 * 日期: 2024-03-15
 * 说明: 本文件定义温度传感器模块的外部接口
 * ============================================================ */

#ifndef TEMP_SENSOR_IF_H
#define TEMP_SENSOR_IF_H

#include <stdint.h>

#ifdef __cplusplus
extern "C" {
#endif

/* ---------- 版本定义 ---------- */
#define TEMP_SENSOR_IF_MAJOR    1
#define TEMP_SENSOR_IF_MINOR    2
#define TEMP_SENSOR_IF_PATCH    0
#define TEMP_SENSOR_IF_VERSION  ((TEMP_SENSOR_IF_MAJOR << 16) | \
                                 (TEMP_SENSOR_IF_MINOR << 8)  | \
                                 TEMP_SENSOR_IF_PATCH)

/* ---------- 错误码定义 ---------- */
#define TEMP_OK                 0
#define TEMP_ERR_PARAM          (-1)
#define TEMP_ERR_BUSY           (-2)
#define TEMP_ERR_TIMEOUT        (-3)
#define TEMP_ERR_HW             (-4)

/* ---------- 数据类型定义 ---------- */
typedef enum {
    TEMP_UNIT_CELSIUS = 0,
    TEMP_UNIT_FAHRENHEIT,
    TEMP_UNIT_KELVIN
} TempUnit_t;

typedef struct {
    int32_t     temperature;    /* 温度值，单位由 unit 字段指定 */
    TempUnit_t  unit;           /* 温度单位 */
    uint32_t    timestamp_ms;   /* 采样时间戳，毫秒 */
    uint8_t     valid;          /* 数据有效标志：1-有效，0-无效 */
} TempData_t;

/* ---------- 接口函数声明 ---------- */
int32_t Temp_Init(void);
int32_t Temp_Deinit(void);
int32_t Temp_Read(TempData_t *pData);
int32_t Temp_SetUnit(TempUnit_t unit);
int32_t Temp_GetVersion(uint32_t *pVersion);

#ifdef __cplusplus
}
#endif

#endif /* TEMP_SENSOR_IF_H */

你看，这个头文件有几个特点：

• 文件头注释：写明模块名、版本、日期、用途。这是接口的「身份证」。
• 版本宏：用主版本+次版本+补丁版本组合成一个32位整数，方便比较。
• 错误码统一：所有返回值都用负数表示错误，0表示成功。调用方不用猜。
• 数据结构清晰：TempData_t 把温度值、单位、时间戳打包在一起，一次读取搞定。

接口版本管理：别让兼容性问题坑了你

项目迭代过程中，接口一定会变。加个参数、改个结构体字段，都是家常便饭。但问题是：你怎么知道当前固件用的是哪个版本的接口？

我曾经在一个IoT项目中吃过亏。设备端和云端用的是同一个接口头文件，但设备端升级了固件，云端没同步更新。结果结构体大小变了，数据解析全乱套，后台收到一堆乱码。排查了两天才找到原因。

从那以后，我定了一条铁律：每个模块接口必须有版本号，并且在初始化时做版本校验。

版本管理的最佳实践

我推荐用语义化版本（Semantic Versioning）来管理接口：

在代码里做版本校验，其实很简单：

/* 模块内部实现 */
#define EXPECTED_VERSION  ((1 << 16) | (2 << 8) | 0)  /* v1.2.0 */

int32_t Temp_Init(void)
{
    uint32_t version;
    
    /* 读取接口版本 */
    Temp_GetVersion(&version);
    
    /* 校验主版本号是否匹配 */
    if ((version >> 16) != (EXPECTED_VERSION >> 16)) {
        return TEMP_ERR_VERSION;  /* 主版本不匹配，拒绝初始化 */
    }
    
    /* 版本兼容，继续初始化... */
    return TEMP_OK;
}

接口隔离的另一个关键：隐藏内部实现

头文件定义好了接口，但还有一个常见问题：模块内部的结构体被暴露了。

比如，你定义了一个结构体 SensorContext_t，里面存了I2C句柄、校准参数、缓冲区等内部状态。如果不小心把这个结构体定义放到了接口头文件里，其他模块就能直接访问内部字段。一旦你改了内部布局，所有依赖这个头文件的模块都得重新编译。

我的做法是：用不透明指针（Opaque Pointer）隐藏内部实现。

/* 接口头文件：只声明类型，不定义结构体 */
typedef struct TempContext TempContext_t;

/* 接口函数 */
int32_t Temp_Init(TempContext_t **ppCtx);
int32_t Temp_Read(TempContext_t *pCtx, TempData_t *pData);

/* 模块内部实现文件：定义结构体 */
struct TempContext {
    I2C_Handle_t    i2c;
    uint8_t         addr;
    int32_t         calib_offset;
    uint8_t         buffer[32];
};

这样，外部模块只能通过指针操作，看不到内部细节。你想改内部结构，只要接口函数签名不变，外部模块完全不受影响。

接口定义的知识体系

说了这么多，咱们用一张图把接口定义的核心逻辑串起来：

避坑指南：我踩过的几个坑

最后分享几个实战中容易踩的坑，希望能帮你少走弯路：

• 坑一：头文件互相包含。A模块的头文件包含了B模块，B又包含了A，编译直接报错。我的解决办法是：尽量用前置声明，只在真正需要的地方才包含头文件。
• 坑二：结构体字节对齐不一致。不同编译器、不同优化选项下，结构体的对齐方式可能不同。如果两个模块用不同的编译器编译，结构体成员偏移量对不上，数据就错了。我习惯在结构体定义后面加 __attribute__((packed)) 或者显式填充字节。
• 坑三：接口变更后忘记更新版本号。改完接口，头文件里的版本宏还是旧的。别人拿到新头文件，根本不知道接口变了。我现在用脚本在CI流程里自动检查：如果头文件内容有变化，版本号必须递增，否则构建失败。