大型项目模块划分实战：项目结构设计、模块依赖关系图、接口文档的编写规范
说实话，很多工程师写代码时，脑子里只有「功能」。他们想的是：我要实现A功能，写个函数；再实现B功能，再写个函数。结果呢？项目到一半，代码就成了一团乱麻。
我见过最夸张的一个项目，一个.c文件里塞了8000行代码。你敢信？那哥们离职后，接手的人直接崩溃了。嗯，这就是典型的「模块划分没做好」的后果。
今天咱们就聊聊，怎么把一个大型项目，拆成清晰、可维护、可复用的模块。说白了，就是教你怎么「分而治之」。
一、项目结构设计：别让代码「躺平」
先说说目录结构。我个人习惯，一个嵌入式C语言项目，至少分这么几层：
project_root/
├── app/ # 应用层，业务逻辑
├── bsp/ # 板级支持包，硬件抽象
├── kernel/ # 内核/调度/任务管理
├── lib/ # 通用库，无业务依赖
├── third_party/ # 第三方代码
├── config/ # 配置文件
├── doc/ # 文档
└── test/ # 单元测试
你想想看，如果所有代码都堆在src目录下，找文件都得翻半天。分层之后，每个目录的职责就清楚了。
我在项目中遇到过最头疼的事，就是底层驱动里偷偷调了应用层的全局变量。查bug查了三天，最后发现是这种「循环依赖」搞的鬼。从那以后，我定了个死规矩：依赖关系必须单向。
二、模块依赖关系图：画出来才看得清
光有目录结构还不够。你得把模块之间的依赖关系画出来。为什么？因为人脑记不住那么多关系，但图可以。
下面是我用SVG画的一个典型嵌入式项目的模块依赖关系图。你看一眼就明白了：
看到没？箭头方向就是依赖方向。应用层依赖业务逻辑层和协议栈层，业务逻辑层依赖HAL，HAL和驱动层都依赖基础库。没有循环依赖，没有跨层调用。
三、接口文档的编写规范：别让调用者猜
模块划分好了，依赖关系也清楚了。接下来就是接口文档。说实话，很多团队不写接口文档，或者写得很敷衍。结果就是：你写的函数，别人看不懂；别人写的函数，你不敢用。
我总结了一套接口文档的「四要素」模板，你直接套用就行：
| 要素 | 说明 | 示例 |
|---|---|---|
| 函数名 | 清晰表达功能，模块前缀+动词+名词 | hal_uart_send() |
| 功能描述 | 一句话说清楚「做什么」 | 通过UART发送指定长度的数据 |
| 参数说明 | 参数名、类型、方向（输入/输出）、取值范围 | data: const uint8_t* [输入] |
| 返回值 | 成功/失败码，以及可能的错误原因 | 0=成功, -1=超时, -2=参数错误 |
举个例子，一个标准的接口文档长这样：
/**
* @brief 通过UART发送数据
* @param uart_id UART端口号，取值范围0~2
* @param data 待发送数据缓冲区指针
* @param len 待发送数据长度（字节）
* @param timeout 超时时间（毫秒），0表示不等待
* @return 0 发送成功
* -1 参数错误（uart_id无效或data为NULL）
* -2 发送超时
* -3 硬件错误
* @note 此函数为阻塞模式，在RTOS中会挂起当前任务
*/
int hal_uart_send(uint8_t uart_id, const uint8_t *data,
uint16_t len, uint32_t timeout);
四、模块划分的实战经验
说了这么多理论，来点实际的。我总结了几条模块划分的「铁律」，你记一下：
- 单一职责：一个模块只做一件事。比如UART驱动就管收发，别在里面加什么协议解析。
- 接口稳定：模块对外的接口一旦确定，尽量不改。要改也得走版本升级流程。
- 隐藏实现：模块内部的结构体、全局变量，别暴露给外部。用
static锁死。 - 依赖注入：如果模块需要依赖其他模块，通过初始化参数传入，别硬编码。
举个例子，一个「好的」模块头文件长这样：
// hal_uart.h
#ifndef __HAL_UART_H__
#define __HAL_UART_H__
#include <stdint.h>
// 初始化UART，传入波特率和回调函数
int hal_uart_init(uint8_t uart_id, uint32_t baudrate,
void (*rx_callback)(uint8_t data));
// 发送数据
int hal_uart_send(uint8_t uart_id, const uint8_t *data,
uint16_t len, uint32_t timeout);
// 接收数据（非阻塞）
int hal_uart_recv(uint8_t uart_id, uint8_t *data,
uint16_t max_len);
#endif
你看，这个头文件里只有函数声明，没有结构体定义，没有全局变量。调用者只需要知道「怎么用」，不需要知道「怎么实现」。
五、避坑指南
最后，分享几个我踩过的坑：
- 别搞「万能模块」：有人喜欢搞一个
utils.c，里面塞了字符串处理、数学计算、日志打印、定时器……结果这个模块谁都依赖，改一处全项目都得重新编译。拆！拆成string_utils.c、math_utils.c、log.c、timer.c。 - 别让头文件「传染」：如果模块A的头文件里
#include了模块B的头文件，那么所有使用模块A的代码，都间接依赖了模块B。这叫「头文件传染」。解决办法：能用前置声明就别include。 - 接口文档要「活」：别写完就扔那。代码改了，文档也得同步更新。我习惯在代码注释里直接写接口文档，然后用Doxygen自动生成。这样文档和代码永远在一起。
嗯，今天就聊这么多。模块划分这事，说白了就是「分而治之」+「约定大于配置」。你按照我说的这几步走，项目结构清晰了，依赖关系理顺了，接口文档写规范了，后面维护起来会轻松很多。
公众号:蓝海资料掘金营，微信deep3321