1. 课程导论与架构思维：为什么嵌入式需要架构？文档化的重要性，课程目标与学习路径

大家好，我是你们这门课的讲师。做了十几年嵌入式，从 8 位单片机一路折腾到多核 ARM，踩过的坑比写过的代码还多。今天咱们开篇第一讲，不急着上代码，先聊聊一个根本问题：嵌入式到底需不需要架构？

说实话，我早年也觉得架构是“大厂病”。一个跑 bare-metal 的灯控程序，总共几百行，要啥架构？后来被现实狠狠教育了几次——嗯，咱们慢慢聊。

1.1 为什么嵌入式需要架构？

很多人觉得嵌入式就是“点灯、读传感器、发串口”。没错，功能上确实是这样。但你想过没有：当项目从 1 个人变成 5 个人，从 1 个 MCU 变成 3 个 MCU 协同，从裸机变成 RTOS，代码量从 1K 涨到 100K——你还能靠“堆代码”搞定吗？

我在项目中遇到过最典型的场景：一个同事离职了，留下一个 2 万行的 main.c。没有模块划分，没有接口文档，全局变量满天飞。新来的同事花了整整两周才看懂那个状态机是怎么跑的。这就是没有架构的代价。

说白了，架构就是给系统立规矩。没有规矩，不成方圆。嵌入式系统往往有资源限制（RAM、Flash、CPU 主频），所以架构不能像 PC 软件那样“随便造”。但正因为资源有限，好的架构反而能帮你省资源——模块化之后，代码复用率高了，重复代码少了，Flash 占用自然就降下来了。

对比维度	无架构（堆代码）	有架构（模块化）
代码可读性	差，全局变量满天飞	好，接口清晰
调试效率	低，改一处崩一片	高，模块独立测试
团队协作	困难，互相覆盖代码	顺畅，接口契约驱动
资源占用	高，重复代码多	低，复用率高
可移植性	差，硬件耦合严重	好，硬件抽象层隔离

1.2 文档化的重要性

说到文档，很多嵌入式工程师的第一反应是：“写文档？那不是产品经理的事吗？”

我曾经也这么想。直到有一次，我接手一个基于 STM32F4 的无人机飞控项目。前任留下了 3 万行代码，零注释，零文档。我花了整整一个月才理清那个卡尔曼滤波的接口是怎么调用的。更崩溃的是，我发现他用了两个不同的 I2C 库——一个自己写的，一个从网上抄的，接口风格完全不一样。

文档化不是写作文，而是给系统画地图。你想想看，没有地图你怎么导航？

你可能会问：“写文档太花时间了，项目进度紧怎么办？”

我的经验是：文档化不是额外的工作，而是开发的一部分。接口定义写清楚了，联调的时候少吵架；架构图画明白了，新同事上手快 3 倍。这笔账，怎么算都划算。

1.3 课程目标与学习路径

这门课不是讲理论，而是讲实战。我会带着你，从零开始，把一个嵌入式系统从“堆代码”改造成“有架构、有文档、可维护”的工程典范。

具体来说，学完这门课，你能做到：

1. 掌握嵌入式架构设计方法：模块划分、分层设计、接口定义、状态机建模。
2. 学会文档化技术：用 Markdown 写接口文档、用 PlantUML 画架构图、用 Doxygen 生成 API 文档。
3. 理解设计模式在嵌入式中的应用：状态模式、观察者模式、命令模式、适配器模式……不是生搬硬套，而是落地到 MCU 上。
4. 能独立完成一个中型嵌入式项目的架构设计：从需求分析到架构评审，从接口定义到代码实现，全流程走一遍。

课程分四个阶段：

阶段	章节	核心内容
基础篇	1-5	架构思维、文档化工具、模块化设计、接口定义规范
模式篇	6-15	嵌入式常用设计模式（状态机、观察者、命令、适配器等）
实战篇	16-25	基于 STM32 的完整项目实战（传感器驱动、通信协议、任务调度）
进阶篇	26-30	架构评审、代码重构、测试驱动开发、持续集成

1.4 本章知识体系

下面这张图，把本章的核心逻辑串起来了。你可以把它当作整门课的“导航图”。

这张图其实就说了三件事：为什么需要架构、文档化怎么落地、课程怎么帮你做到。后面的 29 章，都是围绕这个框架展开的。

1.5 学习建议

最后，给各位几点建议：

• 别光看，要动手：每章都有配套的代码示例和练习。我建议你准备一块 STM32 开发板（F4 或 H7 系列都行），跟着课程一步步做。
• 带着问题学：你手头有没有“屎山”项目？有没有被接口不统一坑过？把这些痛点记下来，看看课程里有没有解决方案。
• 多问为什么：我讲的设计模式，不是让你死记硬背。你要想：这个模式解决了什么问题？有没有更好的方案？