画图这件事，表面是手上功夫，实际是脑力活。早年在梳理一套老系统的模块依赖时，我画出来的架构图被同组的开发同事吐槽"像一盘打翻的意大利面"：线乱、颜色多、各种边界框叠在一起，连自己隔一周再看都得辨认半天。后来我花了很长时间研究"怎么把图画得又快又清楚"，慢慢沉淀了一套绘图方法，最终整理成了一个叫 diagram-design 的实践项目。
diagram-design 听起来像个设计专题，其实更像一本"画图说明书"：它负责回答图表类型怎么选、工具怎么挑、配色和连线有哪些规则、源文件怎么进代码仓库维护，以及最重要的——一张图给谁看、到底想表达什么。它能帮你解决的具体问题很实在：告别随手乱画，让团队里每一张图都保持统一的视觉规范，让读者第一眼就能抓到重点。
不管你是软件工程师、产品经理、技术文档写作者，还是刚进团队就要画架构图的新人，这套思路都能直接落地。我会把这套方法完整拆开讲一遍，里面大部分结论都来自实际项目里的踩坑和复盘，不是从网上整理的二手模板。
1. 项目缘起与整体设计思路
1.1 为什么会出现 diagram-design 这个项目
很多人画图没有"设计"这一环。拿到需求，打开绘图工具就直接拖图标、拉线条，不同模块用什么颜色全凭当天心情，连线走直线还是曲线完全看鼠标手感。画完当下觉得挺完整，但过两周再看，根本想不起来当时为什么要这样配色、为什么这条线从右边绕了一大圈。
diagram-design 的出发点就是解决这个痛点：在动手之前，先定义清楚"图给谁看、要表达什么、用哪种图最合适"。它不是为了把图画得花哨，而是为了建立一套约束。设计本身就是约束，没有约束的图很快就会退化成一堆图形元素的随机排列。我见过太多次评审会上，作者指着图里的线条说"这里我先这么连，后面再调整"，结果后面永远没有再调。
项目的核心输出物是三类东西：第一类是一份"图表类型速查表"，告诉你不同场景该用哪种图；第二类是一套"视觉规范参数"，把颜色数量、间距、字号、线型都量化；第三类是一组"源文件管理约定"，让每一张图都能像代码一样被版本管理、被评审、被复用。
1.2 图表的第一性原理：图是给人看的
图表本质是一个"信息压缩器"。一段复杂的依赖关系写成文字可能要几百行，画成图可能一分钟就懂。但前提是看图的人能快速建立心理模型。所以 diagram-design 里的所有规则，归根结底都指向同一个目标：降低读者的认知负担。
这里有一个反直觉的结论：图里的元素越少越好。很多人以为图要详尽，把类名、方法、属性、模块内部实现全部塞进一张图，结果就是没有人愿意看。我画图前会先问自己一个问题：如果这张图只能保留五个信息点，我会保留哪五个？这五个就是图的骨架，其余内容可以放到附录、注释或者另一张详细图里。
另一个常见误区是追求"信息齐全"而牺牲"信息层级"。一张图上有十种不同颜色的模块、三种粗细的线条、七八个图标，读者根本不知道该先看哪里。正确做法是先让视觉层级和逻辑层级对齐：最重要的模块颜色最深、位置最靠中心，次要的模块逐渐变淡、向外围分布。眼睛先看哪里，哪里就是最重要信息。
1.3 三步法：定受众、定类型、定工具
我把整个工作流压缩成三步：
- 定受众：图给谁看。给管理层看，侧重模块归属和系统边界；给开发看，侧重接口依赖和数据流；给新成员看，侧重流程顺序和角色分工。
- 定类型：根据要表达的内容选择图表类型。架构关系用模块结构图，业务流程用流程图，消息先后用时序图，数据模型用实体关系图。
- 定工具：考虑单次协作、使用频率、维护方式之后再选工具。工具不是越强越好，而是越合适越好。
这三步顺序不能换。先定受众，很多后续的"画多细""用什么颜色"自然就都有了答案。我见过太多失败的图，根因根本不是画功差，而是受众和类型没搞明白就开画。
举个例子，有一次团队内部讨论消息队列的消费链路，有人直接打开在线白板就开始画，各种箭头满天飞，画了半小时也没讲清楚。后来我让他在画之前先回答三个问题：这张图的读者是谁？——后端开发；要表达什么？——消息从哪来、经过哪个消费者、失败后去哪；用什么图？——时序图，因为核心是时间的先后顺序。明确以后，重画只用了十分钟。
2. 图表类型与视觉规范细节
2.1 常用图表类型怎么选
用了几年的 diagram-design，我最常用的图表类型其实就是下面这六种。不需要贪多，能把它们用好，工作中至少九成的画图需求都能覆盖。
- 模块结构图：表达系统由哪些部分组成、边界在哪里。适合讲软件架构、微服务划分、文件夹目录结构。特征是用嵌套的容器框表示层级归属。
- 流程图：表达业务或逻辑的分支与走向。适合讲审批流程、异常处理、算法步骤。特征是有明确的起点和终点，菱形表示判断。
- 时序图：表达不同对象或角色之间的消息传递顺序。适合讲接口交互、异步事件、多人协作流程。特征是纵向时间轴加横向消息线。
- 实体关系图：表达数据模型和表间关系。适合数据库设计、领域建模。特征是实体框加连线上的关系标记。
- 状态图：表达某个对象在不同状态之间的迁移。适合订单状态机、设备生命周期、审批状态流转。特征是状态节点加迁移条件。
- 甘特图：表达任务时间计划和依赖关系。适合项目管理、迭代排期。特征是横向时间轴加任务条。
diagram-design 里对每种类型都有一条"一句话定义"。画图之前先对着定义自查：如果画出来的东西不符合定义，多半是类型选错了。最常见的是有人把流程图画成了模块结构图，流程分支被画成嵌套方框，看起来像架构，实际上讲的是顺序，读者很容易被误导。这种情况宁可重画，也不要将就。
2.2 视觉规范：最有用的四句话
视觉规范不需要定得很复杂，越简单越容易被团队接受。我最后沉淀下来的核心原则就四句，每一句都来自实际翻车后的教训。
第一句：颜色不超过五种。要给信息层级上色，不要给每个模块上色。主色、辅色、强调色各一种，加上深浅灰用来画背景和文字，足够覆盖绝大多数场景。超过五种颜色，读者就开始为"这个颜色代表什么"浪费脑力。
第二句：先搭骨架再填肉。任何一张图，先用方框和文字把主要模块的位置定下来，确认布局平衡之后再连第一根线，最后才加图标、注释、底色这些装饰元素。我见过很多人第一步就在纠结圆角矩形的圆角半径，结果整个图的结构完全没想清楚。
第三句：连线走正交，不走斜线。横平竖直、带九十度拐角的线看起来更整齐，斜线只在表达"方向感"和"非直接关系"时用。正交线也更容易被网格吸附，改起来不会散架。
第四句：对齐靠网格，不靠眼睛。主流绘图工具几乎都有网格和吸附功能，打开之后元素间距一致、边缘对齐，图立刻显得专业。手拖出来的东西，永远不如吸附之后的整齐。
2.3 一套可以直接抄的图纸参数
我自己常用的画布和样式参数是固定的一套，这样能保证团队里每张图风格统一。参数本身不是金科玉律，但一致性比单个参数是否最优重要得多。
- 画布尺寸：1280x800 或 1600x900。宽高比更适合信息展示，导出后也容易放进文档和演示。
- 网格间距：10px 或 8px，必须打开吸附。
- 字号规范：图标题 16px，模块名称 13px，注释文字 10px。三档足够，不需要更多。
- 图形样式：功能模块用圆角矩形，系统边界用直角矩形，非强依赖关系用虚线，外部系统用不同底色但同规格边框。
- 连线方式：默认正交，箭头明确方向，不要使用无箭头线条，因为读者会困惑数据到底往哪流。
这套参数集一开始可能觉得死板，但用久了就会体会到它的价值。团队里新画出来的图，和三个月前画的旧图看起来像同一个人的作品，后续维护的人不会因为风格跳跃而分心。
3. 工具选型解析与选择套路
3.1 为什么工具不是越强越好
工具选型如果脱离"维护成本"来谈，基本都会失败。我见过一个团队花大力气引进了很贵的多人协作白板，结果大多数成员还是偷偷在本地画图，最后文档里的图东一张西一张，格式和风格全不统一。
这个问题的核心在于，图不像代码有明确的版本管理和评审流程，一旦没有一个可靠的主工具，团队很容易分裂成好几派：有人用在线工具保存到云端，有人用本地软件存成二进制文件，还有人干脆用文本脚本。最后整理文档时非常痛苦。diagram-design 的一个重要原则就是：主工具只能有一个，其余作为辅助。
另外还要考虑工具的学习成本、文件格式的开放性、导出图片的清晰度。不要为了"功能全面"选一个全团队都用不顺手的工具；也不要在免费工具已经够用时盲目买订阅制产品。
3.2 四类工具的适用场景对照
我把市场上的绘图工具粗略分成四类，每一类都有它最舒服的场景，也有明显的短板。
| 需求场景 | 推荐类型 | 理由 |
|---|---|---|
| 快速画一个想法 | 轻量手绘风画板 | 零门槛、随手就能画，不用纠结细节 |
| 正式技术文档插图 | 开源跨平台绘图工具 | 文件格式开放、样式可控、离线可用 |
| 需要纳入代码仓库维护 | 文本图表引擎 | 文本即可 diff，方便评审和版本管理 |
| 多人实时头脑风暴 | 在线协作白板 | 协作成本低，适合会议和远程评审 |
这里我特意没有写具体产品名，是因为工具迭代太快，真正重要的是它们所属的类别。每一类都有做得不错的代表产品，选型时照着这几条标准去试就行。
3.3 我的默认组合与踩坑记录
我现在的默认组合是：正式文档插图用开源跨平台绘图工具，快速想法用手绘风画板，需要版本控制的图用文本图表引擎，需要和非技术同事实时评审时打开在线协作白板。
这套组合不是一步到位的，我踩过两个大坑：
第一个坑是试图只靠文本图表引擎画所有图。固定的语法写起来快，但复杂的模块关系一旦需要精细布局，文本描述就非常吃力，调整一个模块位置要改好几处坐标和连接关系，效率远低于直接拖拽。
第二个坑是试图只靠在线协作工具。在线工具确实方便，但每次导出图片都要手动处理，而且图存在服务商的服务器上，团队内部比较敏感的信息根本不敢往上传，更别提版本管理了。
踩完这两个坑之后，我得出结论：工具的本质是权衡，不是越多越好，也不是越少越好。让合适的工具干它最擅长的事，其余场景交给另一类工具，这个组合才能稳定下来。
4. 实操：从空白画布到一张合格的架构图
4.1 找一个人人都能看懂的真实练手场景
为了讲清楚具体操作，我用一个大家都熟悉的场景来演示完整工作流：画一张"某订单处理模块的模块关系图"。这个系统有四个内部模块——订单校验、库存扣减、通知服务、日志服务，还有一个外部系统支付网关。目标读者是组内开发，需要表达模块之间的依赖关系和外部调用边界。
这是一个非常典型的技术文档场景，既包含系统边界，也包含清晰的模块依赖，用来演示 diagram-design 的流程很合适。
4.2 动手前的准备步骤
第一步定受众：组内开发，不需要解释业务背景，可以直接画技术关系。所以图中的细节可以包含接口方向的箭头，而不是只有含糊的连线。
第二步定类型：模块结构图。核心表达的是"系统由哪几个部分组成、相互怎么调用"，不是"谁先执行谁后执行"，所以不用时序图。
第三步定布局：我采用从上到下的布局。支付网关作为外部系统放在最上方，用不同底色区分边界；订单校验作为核心入口放在中部；下方左侧放库存扣减，中间放通知服务，右侧放日志服务。这样主数据流从上到下、一目了然。
4.3 用文本图表引擎快速出初稿
先不要打开绘图工具拖拽，而是用文本图表引擎把结构先描述出来。这一步的优势是速度极快，而且后续改起来非常方便。类似这样的示意结构：
graph TD Gateway[支付网关] --> Verify[订单校验] Verify --> Stock[库存扣减] Verify --> Notify[通知服务] Verify --> Logger[日志服务]这个阶段不需要考虑颜色和样式，只需要确认节点和关系对不对。文本引擎的自动布局虽然不一定好看，但能让人快速预览结构是否完整。如果发现有模块没画进去、某条依赖被遗漏，这时候修改成本最低。
4.4 手工精修：让图从"能看"变"好看"
文本引擎生成的布局往往不是最终交付样式。我会把初稿导成 SVG 或截图，放到开源跨平台绘图工具里精修。精修不是重新画一遍，而是按视觉规范逐步调整。
调整顺序很重要，我是这样操作的：
- 统一颜色：先给外部系统上灰色底，给核心模块上主色，给辅助模块上浅色，一共不超过三种彩色。
- 对齐和间距：打开网格吸附，把五个模块拖到同一水平线上，最近的两个模块保持至少两倍网格间距。
- 理顺连线：全部改成正交线，箭头朝向一致。如果出现交叉线，把一个模块的位置微调，让线从外侧绕行而不是穿过别的模块。
- 添加边界容器：用一个直角矩形框把四个内部模块圈起来，标注"订单服务"，这样就明确了系统边界。
- 加注释：在支付网关旁边加一行 10px 的灰色注释，说明"外部系统，双活部署"，不占主视觉但信息到位。
精修这一步是所有画图流程里最耗时、也最出效果的一步。很多人画图"感觉不专业"，问题往往不是设计能力，而是没有按这套顺序做系统化的调整。
4.5 导出与交付
图画完之后，导出环节也有讲究。我一般导出两到三个版本：
- 2 倍分辨率的 PNG，放进文档或演示不会糊；
- SVG 矢量版，后续可以被绘图工具直接编辑；
- 如果团队支持，顺便导出一份 PDF，用来保证打印和分享时的版式一致。
文件名和存放位置必须约定好，我会用统一的命名规则：diagram-订单模块-20250601.draw这类格式。导出的 PNG 放在docs/images，源文件放在docs/diagrams。这样一年之后翻出来，仍然知道哪张图是最新的、源文件在哪里。
5. 常见问题与排查技巧实录
5.1 图总是越画越乱怎么办
这个问题通常不是"画得慢"，而是"想得太少"。用"草稿优先"策略可以解决：任何图都先快速画一个只带文字的简单版，不纠结任何视觉细节。骨架稳定之后，再从颜色、间距、图标开始补。
把"草稿优先"养成习惯之后，你会发现大部分图会在草稿阶段被推翻——你发现布局根本不合理、模块之间关系太多画不开，这时候修改成本极低。我最怕的是有人花了两个小时精修一张图，最后发现逻辑关系本身就是错的。
5.2 多模块连线绕成一团怎么处理
连线交叉是模块关系图最常见的失败原因。有一个非常有效的处理手段：统一入口模式。让所有外部依赖先汇聚到一个中间节点，再由中间节点分发到各个模块。
比如表格里的架构图如果改成"支付网关 -> 订单校验 -> 下游三个模块"，交叉线会明显减少。如果模块之间确实存在大量的网状关系，说明一张图画不下，应该拆成多张图，按子系统分开表达，而不是硬塞进一张图里。
5.3 颜色太多、看起来像烟花的排查
颜色过多往往不是颜色选择本身的问题，而是信息层级没理清。先用灰度看这张图：如果灰度下模块之间的层次依然清晰，说明问题不在颜色，在布局。如果灰度下完全没有层次，那就要回到"信息优先级"重新排布。
我会用"主色不超过 40% 区域、强调色不超过 10% 区域"这个粗粒度原则来帮忙。高饱和的颜色只留给关键路径，普通模块用低饱和色或者灰色。
5.4 图片导出模糊、字体变形
这个问题的根源通常是画布尺寸和导出分辨率不匹配。先确认画布尺寸，导出时选择两倍或三倍缩放，图片就不容易模糊。
字体变形一般是因为图里用了只有某台电脑才安装的特殊字体。解决方案是团队统一使用通用无衬线字体，比如中文环境下的思源黑体类字体或者系统默认黑体，避免花哨字体带来的兼容问题。
5.5 源文件管理失控
只导出图片但不保留源文件的团队，最终一定会遇到"图与代码不同步"的问题。代码迭代了三个月，文档里的架构图还是三个月前的旧版，因为画图的人离职了，源文件根本找不到。
diagram-design 的一条硬性约定是：源文件必须进代码仓库。绘图源文件和文本图表脚本跟代码一样走版本管理，记录每次改动的 diff。SVG 和 PNG 只是发行版，源文件才是真正的源码。评审图的时候，像评审代码一样去 review，才能保证图的质量。
5.6 协作时总有人改完图不通知
如果工具本身没有评论和通知功能，就靠流程兜底。我的做法是在文件命名里加入编辑人缩写和日期，比如diagram-订单模块-zyj-20250601.draw。改图之后要求同步更新对应文档，把它写进团队协查清单。
这个流程看起来笨，但非常可靠。记住一个小原则：图的信任建立在"每个人都知道图在哪、谁是最近改过的人"这个共识上。有了这个共识，协作冲突会大大减少。
现在团队里新来的同学问我怎么快速上手画图，我都会直接把这套内容丢给他，然后加一句：别急着打开工具，先把受众和类型想清楚，再动手。diagram-design 这套方法不是让画图这件事变得更高大上，而是让每个人都能稳定地画出清晰、可维护、不依赖个人审美发挥的图。坚持一两个月，你就能体会到，一张好图带来的沟通效率提升，远比它花掉的那半小时更有价值。
