模块化设计原则（上）：高内聚、低耦合——嵌入式C语言中的接口与实现分离

各位同学，咱们今天聊一个老生常谈、但真正做好的没几个的话题——高内聚、低耦合。

我刚开始做嵌入式那几年，也踩过不少坑。记得有一次维护一个电机控制项目，一个 .c 文件写了三千多行，全局变量满天飞。改一个定时器参数，结果串口打印格式乱了。排查了两天，最后发现是某个全局变量被三个模块同时读写。嗯，从那以后，我彻底明白了什么叫「牵一发而动全身」。

说白了，模块化设计就是让每个模块各司其职，互不干扰。今天咱们先讲上半部分：接口与实现分离。

为什么嵌入式C语言更需要接口与实现分离？

你想想看，嵌入式开发有几个特点：

• 资源受限：RAM、Flash 就那么点，不能像 PC 软件那样随便堆
• 硬件耦合深：驱动直接操作寄存器，稍有不慎就死机
• 团队协作多：一个人写驱动，另一个人写应用，接口不清晰就互相等

接口与实现分离，说白了就是：.h 文件只告诉别人「我能干什么」，.c 文件藏着「我怎么干」。

一个反面教材：耦合到崩溃

先看一个我早期项目里真实出现过的写法：

// motor_control.h
#ifndef MOTOR_CONTROL_H
#define MOTOR_CONTROL_H

#define MOTOR_SPEED_MAX  1000
#define MOTOR_ACCEL_STEP 50

int motor_speed;          // 全局变量，直接暴露
int motor_target_speed;   // 全局变量，直接暴露

void motor_init(void);
void motor_set_speed(int speed);
void motor_emergency_stop(void);

#endif

问题在哪？

• motor_speed 和 motor_target_speed 是全局变量，任何模块都能直接读写
• 如果应用层不小心写了 motor_speed = 9999;，电机可能直接飞车
• 想修改内部实现（比如改成用结构体管理速度），所有引用这些变量的地方都得改

我曾经在一个项目中，就因为这种写法，导致测试同事在调试时误改了全局变量，电机堵转烧了驱动板。嗯，从那以后，我对全局变量暴露深恶痛绝。

正确的做法：接口与实现分离

咱们重新设计一下：

// motor_control.h
#ifndef MOTOR_CONTROL_H
#define MOTOR_CONTROL_H

/* 接口声明 —— 只告诉别人能做什么 */
void motor_init(void);
int  motor_get_speed(void);
void motor_set_speed(int speed);
void motor_emergency_stop(void);

#endif

// motor_control.c
#include "motor_control.h"

/* 内部实现 —— 细节全部藏起来 */
static int motor_speed = 0;          // 静态全局变量，外部不可见
static int motor_target_speed = 0;

#define MOTOR_SPEED_MAX  1000
#define MOTOR_ACCEL_STEP 50

void motor_init(void) {
    motor_speed = 0;
    motor_target_speed = 0;
    // 初始化硬件寄存器...
}

int motor_get_speed(void) {
    return motor_speed;
}

void motor_set_speed(int speed) {
    if (speed > MOTOR_SPEED_MAX) {
        speed = MOTOR_SPEED_MAX;     // 限幅保护
    }
    motor_target_speed = speed;
    // 启动加速曲线...
}

void motor_emergency_stop(void) {
    motor_speed = 0;
    motor_target_speed = 0;
    // 立即切断 PWM 输出...
}

看到了吗？.h 文件里只有函数声明，没有变量。内部变量全部用 static 限定在 .c 文件内。外部模块只能通过接口函数来操作，无法直接篡改内部状态。

接口与实现分离的三大好处

好处	说明	嵌入式场景举例
可替换性	更换硬件平台时，只需重写 .c 文件，.h 不变	从 STM32F1 移植到 STM32F4，驱动接口不变
可测试性	可以单独编译测试每个模块，不依赖其他模块	单元测试时 mock 掉硬件依赖，只测逻辑
可维护性	修改内部实现不影响外部调用者	优化算法、更换通信协议，应用层代码不用动

嵌入式C语言中的常见误区

我这些年评审过的代码，接口与实现分离方面常见这几个坑：

1. 头文件里定义结构体：如果结构体成员是内部实现细节，就别放在 .h 里。可以用「不透明指针」技巧，只声明结构体类型，不定义成员。
2. 头文件里写宏定义：宏是文本替换，一旦暴露就无法隐藏。能用 static const 或枚举的，尽量别用宏。
3. 头文件里包含不必要的头文件：比如驱动模块的头文件里包含了 <stdio.h>，导致所有引用它的模块都引入了 printf 的代码，增加 ROM 占用。

知识结构图：接口与实现分离的核心逻辑

下面这张图展示了接口与实现分离的完整关系：

实践建议：如何落地接口与实现分离

光说不练假把式。我给大家几个可操作的建议：

• 写头文件前先画接口图：列出这个模块对外提供哪些函数，每个函数的输入输出是什么。画清楚了再动笔。
• 内部变量一律 static：除了极少数的全局配置（比如系统时钟频率），所有模块内部变量都加上 static。
• 用「不透明指针」隐藏结构体：如果必须传递结构体，在 .h 里只做前向声明，在 .c 里定义完整结构体。
• 头文件自包含：每个 .h 文件都能独立编译，不依赖其他头文件的包含顺序。