学习开源项目时我们应该画哪些图？
大家好，我是不会喷火的小火龙。
刚开始深入看开源项目的时候，我经历过两个极端。
一个是纯靠肉眼硬看。连着翻了三天，几万行代码从头看到尾，自以为搞懂了，合上电脑脑子里依然是一团浆糊。
另一个是把精力全花在画图的排版上。打开 Draw.io，花了一整个下午在画布上拖方块、微调对齐像素、挑选各种莫兰迪配色，画出一张五颜六色的庞大架构图。结果第二天回头看，自己都找不到核心的调用链路在哪里。
后来我才明白，画图真正的价值是帮大脑把复杂的调用和数据流降维，理清骨架，而不是做图表美化。
关键在于什么阶段、带着什么目的、选什么工具、画什么图。
这篇文章把这件事梳理清楚：工具怎么选、常见问题对应什么图、拿到项目按什么顺序画，以及几个容易踩坑的地方。
一、工具选型：Mermaid、draw.io、Excalidraw、SVG 各自的边界
很多人问我画图该用什么工具，我的建议是不同场景用不同的工具，不用强求某一款。
Mermaid：代码化与版本管理首选
Mermaid 用纯文本语法生成图表，天然支持 Git 版本管理，和 Markdown 完美融合。GitHub 的 README 里直接写 Mermaid 代码就能直接渲染。
它的优势在于修改极快：调整一张图只需要改几行文本，不用打开任何独立的图形编辑器，也特别适合让 AI 帮我们生成初稿。
适合场景：API 调用流程图、Agent 状态执行循环、时序图（Sequence Diagram）、README 技术流程文档。
draw.io：正式架构与工业级排版
draw.io（diagrams.net）完全免费开源，组件库非常全，自带 AWS、GCP、Azure 和 K8s 的官方图标集。它的连线锚点吸附精准，支持复杂的多层对齐。当你需要画一张正式的技术方案图或论文架构图时，它最稳妥。
适合场景：微服务架构图、云原生与 K8s 部署拓扑、技术方案设计图、PPT 汇报图。
Excalidraw：讨论方案与直观教学的手绘白板
Excalidraw 的手绘质感能降低心理门槛。画出来的线条带着手绘感，不会让人觉得是不可更改的最终定稿，反而能鼓励大家提出修改建议。
适合场景：早期技术方案讨论、团队白板脑暴、教程里的直观概念解释图。
SVG：矢量控制与极简图形
SVG 本质是 XML 代码，可以精准控制每一个节点与路径，无限放大不会模糊，文件体积极小。
适合场景：极简矢量插画、高质量技术信息图、Logo 与技术图标。
AI 生图：概念隐喻与视觉呈现
如果不需要精确的技术细节，只是想表达某种技术概念的反差或情绪隐喻，用 Midjourney 或 GPT-4o 生图效率最高。
适合场景：技术博客与公众号封面、宏观概念反差插画。
如下表所示，我把常见的开发场景与推荐的绘图工具整理成了对照表：
| 开发场景 | 推荐工具 | 选型理由 |
|---|---|---|
| API 调用流程 | Mermaid | 纯文本代码化，Git 可版本控制，AI 生成方便 |
| Agent 执行流程 | Mermaid | 状态循环与条件分支表达清晰 |
| UML 时序图 | Mermaid | 语法简洁，sequenceDiagram 原生支持强 |
| 微服务架构图 | draw.io | 组件库全，锚点吸附准，适合复杂拓扑 |
| 云 / K8s 架构 | draw.io | 内置各云厂商与 K8s 官方图标 |
| 论文系统架构 | draw.io / SVG | 矢量导出，排版精度容易对齐 |
| 方案讨论草稿 | Excalidraw | 手绘风格心理门槛低，方便随时修改 |
| 教程解释图 | Excalidraw | 风格柔和，降低读者的理解门槛 |
| README 技术流程 | Mermaid | 直接在 Markdown 中渲染，无需上传图片文件 |
| PPT 高质量信息图 | SVG / draw.io | 矢量无损缩放，支持精细排版 |
| 博客 / 公众号封面 | AI 生图 | 视觉冲击力强，易于传达情绪 |
| 概念视觉 | AI 生图 | 适合抽象概念的隐喻呈现 |
| 极简矢量插画 | SVG | 代码可控，文件体积极小 |
| Logo / Icon | SVG | 矢量无限缩放，保持视觉规范统一 |
二、问题驱动：想搞清楚什么问题，就画什么图
画图容易犯的错误是把静态依赖、动态调用和部署环境全揉在一张图里，箭头到处穿插，最后画成一张谁也看不懂的蜘蛛网。
画图的核心是问题驱动：心里有什么疑问，就画什么图去回答。
工程中常见的核心问题，可以按照从宏观到微观分为四个层次。如图所示：
下面挑几个最常用的具体拆解：
系统架构图回答项目整体是干什么的。重点标出前端、后端、AI 模块、数据库、消息中间件以及第三方外部服务的边界，让人一眼看清系统的大致构成。
模块图与组件图回答项目由哪些模块组成。重点是标清每个模块的单一职责，以及模块之间的单向依赖关系。
调用链图回答一个请求穿透了哪些代码。从 Controller 到 Service，再到数据访问层，梳理出入口到出口的调用路径。
时序图回答不同对象之间的调用顺序。谁先发起调用、返回什么、是同步等待还是异步通知，时序图最适合表达这类时序关系。
数据流图回答数据从哪里来、到哪里去。顺着请求参数，看它在内存里被转换成了什么对象、通过消息队列发送了什么格式、最终持久化到了数据库的哪些字段。
状态图回答核心对象的状态迁移规则。比如订单从待支付到已支付、已发货的生命周期，或者 Agent 记忆提取时的添加、更新、删除判定。
Agent Workflow 图回答 AI Agent 怎么循环运转。LLM 推理、工具选择、执行反馈、记忆读写、条件路由，这些用带有判断条件的状态图画出来最为直观。
三、实战闭环：学习开源项目的 6 步画图 SOP
拿到一个陌生的开源项目，具体可以按下面这 6 步来画。如图所示：
Step 1：跑起来项目，画系统架构图
这是第一步。先别扎进源码，顺着 README 的 QuickStart 把 Demo 跑通一遍，感受一下输入输出和交互方式。
项目跑起来后，画一张粗粒度的系统架构图：前端在哪、后端在哪、用了什么数据库、调了哪些第三方接口。这张图不需要任何代码细节，把黑盒变成灰盒即可。
Step 2：看 README 和目录结构，画模块图
不深入具体文件，只看一级目录名和项目文档说明。弄清楚项目分了几个主要模块、各模块负责什么业务、它们之间的大致依赖方向。
画出来的模块图应该能解答一个问题：如果后续要改某个功能，应该去哪个目录下找。
Step 3：选一个核心功能，画业务流程图
在所有功能中，选出最常用的一条主线（Happy Path）。比如电商项目选下单支付，Agent 项目选用户提问到输出回复，知识库项目选文档解析到检索召回。
画出纯业务视角的流转步骤：从哪里触发、经历几个阶段、产生什么结果。这一步暂时不涉及具体的代码和类名。
Step 4：从入口开始追踪源码，画调用链或时序图
找到入口函数（比如 Controller 接口或 CLI 命令），顺着刚才挑出的业务主线单向跟读代码。
这里有个关键原则：只跟正常流程的主干，先忽略异常重试、参数兜底和日志打印。把一条请求流经的关键类和方法串联起来。涉及多个对象协同的，画时序图往往更清楚。
Step 5：分析关键参数与消息传递，画数据流图
把目光从代码调用转移到数据本身。请求携带的入参是什么结构，在中间层被解组成什么对象，有没有通过消息管道流转，最终落盘时的表结构是怎样的。
数据流图能帮我们理清核心业务实体在整个系统里的流动全貌。
Step 6：遇到复杂结构按需补图
前 5 步已经能帮我们掌握系统的大致脉络。遇到某些局部复杂度高的模块，再针对性补充：
- 数据库表关联较多，补一张 ER 图
- 类继承和接口抽象层级较深，补一张类图
- 实体状态迁移规则较多，补一张状态图
- 涉及智能体自主决策，补一张 Agent Workflow 流程图
- 涉及上线部署和容器编排，补一张部署架构图
举个例子，如图所示，一个典型的 AI Agent 循环执行图如下：
Agent 的核心机制包含推理、判断、工具调用、观察反馈与再次推理。这类包含循环与条件分支的结构，用状态图能够把每一次跳转的条件表达得清晰明了。
四、画架构图容易踩的 3 个坑
很多经验丰富的工程师画出来的图线条不多，但表达很精准。他们通常会注意避开这几个常见误区：
1. 试图在一张图里展示所有细节
如果一张图在 30 秒内没办法让读者看明白核心逻辑，说明它的信息量过载了。
不少人画图习惯把所有技术栈图标全摆上去，每个方块之间拉满箭头，最终变成一张庞杂的连线网。好的架构图通常是做减法的结果，画出来的模块越克制，沟通成本越低。
2. 第一版图就塞入大量分支逻辑
第一版架构图最好只关注标准的正常流程。
如果一上来就把重试策略、熔断降级、权限校验、日志打点全画进去，主干流程就会被杂音淹没。先把正常主干画清晰，有需要再为复杂的边缘逻辑单独画子图。
3. 脱离源码之后图无法自解释
判断一张图是否清晰的标准很简单：不看源码的情况下，把图拿给同组的工程师看，对方能不能在短时间内看懂业务逻辑和流转顺序。
如果必须边看图边翻源码才能明白箭头在表达什么，说明图上的职责边界或数据流向还没有梳理到位。
写在最后
画图本身并不是目的，通过画图建立对系统的全局理解才是目的。
代码细节随时可以让 AI 协助编写或查找，但能把复杂系统抽象为清晰结构的能力，是工程师长期积累下来的关键基本功。
下次看一个陌生的开源项目时，可以先别急着逐行读代码。先问自己当前最需要弄清楚什么问题，选好合适的工具，把那张对应的图画出来。
我是小火龙，一个持续在 GitHub 等开源社区挖掘真正好用、能打的高价值项目，同时记录自己用 AI 搓工具、做产品、踩坑填坑全过程的独立开发者。如果今天这篇对你有启发，欢迎关注公众号「小火龙AI 手记」，我们下篇见。
