STM32 模块化开发指南 · 第 1 篇 写 STM32 项目时，如何组织代码结构？从裸机到模块化的进阶之路

本文是《STM32 模块化开发实战指南》系列的第一篇。作者将结合实际项目经验，分享在 STM32 裸机开发过程中，如何从单文件结构演进到清晰可维护的模块化架构。适合正面临项目复杂化、维护困难的嵌入式开发者。

---

一、为什么 STM32 项目一定要模块化？

很多初学者在做 STM32 项目时，往往都是一个 main.c 写到底：GPIO 初始化、串口收发、中断处理、逻辑判断、协议解析、状态切换，统统堆在一起。刚开始这样写，跑起来也没问题，但随着功能越来越多，项目会遇到以下典型问题：

• 代码结构混乱：所有逻辑堆一起，不同功能之间没有明确边界，修改容易牵一发而动全身；

• 调试困难：代码量太大找不到逻辑入口，想断点某一块逻辑还得从头追踪；

• 复用性差：想在下一个项目中用串口驱动？得复制一整段带宏的代码；

• 移植工作量大：每个项目都是复制+粘贴+改变量，既浪费时间又容易出错。

📌 所以，无论你的项目多小，只要你想让它“能维护、可扩展”，就必须在早期做好结构划分和代码模块化设计。

---

二、裸机项目推荐的分层结构和目录设计

为了解决上述问题，我们推荐使用如下 STM32 项目分层结构，并通过目录来体现模块之间的职责边界。

✅ 推荐项目目录结构

project_root/
├── inc/               # 公共头文件（模块对外接口）
│   ├── ring_buffer.h
│   ├── uart.h
│   ├── ble.h
├── src/               # 源码实现
│   ├── core/          # 启动文件、系统初始化、时钟配置等
│   ├── drivers/       # 低层驱动（GPIO、UART、EXTI等）
│   ├── middleware/    # 通用模块（RingBuffer、List、Timer等）
│   ├── app/           # 应用逻辑模块（AT命令、BLE协议、状态机等）
├── tests/             # 单元测试代码
├── Makefile           # 构建脚本
├── README.md          # 项目说明
└── docs/              # 设计文档、规范、API说明等

📌 每层职责解释

层级	说明