1. diagram-design 是什么为什么我要专门写它很多技术人看到 diagram-design 这个标题第一反应是“画图有什么好设计的”。说实话早几年我也是这么想的。那时候画图对我来说就是顺手拉几个矩形、框一框箭头能看懂就行。直到有几次因为“图太乱、没逻辑、谁也看不懂”被反复追问我才意识到图表本身也是一种需要认真设计的技术产物和写代码、写文档一样有方法论。diagram-design 不是某个单一工具或语言它是一个组合概念怎么选型、怎么组织信息、怎么保证图表的可维护性、怎么让读者三秒内抓住重点。作为技术从业者我们几乎每天都在跟图表打交道——架构图、时序图、流程图、ER 图、部署拓扑图、用户状态机图。但很多人画了几百张图画完连自己都不想再看第二眼。这篇内容就是围绕“如何设计与维护一张高可读性的 diagram”展开的既讲工具也讲方法适合正在梳理系统架构的开发者、做技术文档的工程师、以及任何需要把复杂逻辑讲清楚的人。我会从工具选型讲起再讲画图的核心原则然后是代码化图表的落地实践最后是一些踩坑经验。内容不堆理论都是可以马上拿去用的东西。2. 工具选型从手绘白板到代码化我的选择逻辑2.1 先理清需求再选工具不要一上来就装一堆软件工具选型之前先问自己几个问题这张图是谁在看是给自己梳理思路还是要做成文档给团队甚至跨团队的人看这张图会不会频繁修改图的量级是多大五六个节点还是上百个节点需不需要嵌入到 Markdown、Confluence、GitLab 这种平台里我见过太多人一开始就切到 Visio 或者在线白板画完之后发现导出很麻烦、要改一个细节就得手动拖半天、版本管理全靠“最终版 v3 改改2”这种文件名。实际上图表设计的第一原则不是“画得好看”而是可维护。如果你的图只画一次、再也不动那用什么工具都无所谓但技术图几乎总是会随系统演进不断调整所以维护成本必须从一开始就考虑进去。我推荐的需求判断标准很简单单人快速梳理想法用白板类工具需要多人同屏头脑风暴用在线协作白板需要写进技术文档且长期维护直接上代码化图表需要非常精细的排版控制比如出版级效果再考虑桌面绘图软件。把这个决策做在前面能省掉后面一大半的折腾。2.2 主流图表工具横向对比以下是几种我在实际项目里用过的工具方案各有各的适用场景没有绝对的好坏关键是匹配自己的使用场景。工具/方案上手成本适合场景维护方式痛点draw.io / diagrams.net低快速画图、文档插图半手动可存 XML 到仓库复杂布局仍需手动调整Excalidraw极低手绘风格草图、交互式讨论手动支持简单协作正式文档中风格偏随意PlantUML中UML 图、时序图、部署图纯代码适合版本管理编写时需要记忆语法Graphviz (DOT)中高自动布局、复杂节点关系、依赖图纯代码默认样式丑调样式需要经验Mermaid低Markdown 文档内嵌图、轻量流程文本即所得复杂布局表现力受限visio / OmniGraffle中高出版级制图、精细手绘手动私有格式无法有效 diff团队协作弱在线白板Miro 等低头脑风暴、实时协作手动内容一多就乱难追溯变更我个人的主力组合是“Excalidraw 做前期构思 PlantUML/Graphviz 写入正式文档”。前一个解决“想清楚”后一个解决“长期维护”。Mermaid 虽然在 Markdown 里集成很方便但稍微复杂一点的图它就容易排得稀烂我一般只拿它画简单的流程和饼图。2.3 为什么代码化图表越来越受青睐说起来也简单代码化图表的本质是把图当作源代码来看待。这意味着可以进 Git、可以做评审、可以 diff、可以复用、可以自动生成。比如你改了某个模块的依赖关系改成一行文字后重新生成图前后差别一目了然这在手绘或者是拖拽式工具里是完全做不到的。另一个关键点是可嵌入。代码化的图可以轻松嵌入到文档系统里不需要截图、不需要担心图片分辨率。团队里任何人拿到源文件都知道是怎么画出来的而不是拿到一个无法编辑的 PNG。我承认代码化图表的学习曲线是存在的——语法、布局控制、样式调整都要重新学。但一两次项目用下来这个投入会成倍赚回来。尤其是画 UML 图和架构图改动一个节点比在 GUI 里拖半天要快得多。3. 画好一张图的核心原则先有逻辑再有艺术3.1 一张图只传递一个核心信息我见过最典型的问题是一张图里又想表达模块关系、又想表达调用时序、还想带上数据流和部署边界结果整张图变成蜘蛛网谁也看不懂。图表不是芯片 layout不是连线越多越牛。在设计任何一张 diagram 之前先写一句话定义这张图要传递的信息。比如“这张图描述订单服务创建订单时的外部依赖关系”然后所有节点、连线、分组都服务于这句话凡是跟这句话无关的东西一律不要。这个习惯养成之后你会发现图的可读性提升了一个很大的级别。画图的时候要主动做“信息分层”把宏观架构、核心链路、异常分支分到不同的图里而不是硬塞在同一张。打个比方你的目标读者是在看“城市的交通规划图”你却给他一张包含每一栋楼每一条水管电线走向的施工总图他肯定懵。3.2 版面与结构网格、分组、动线排布上我一般会在动手前先画一个粗糙的草稿确认大的模块分区再细化每个节点。这里有一个很实用的技巧让主要流向遵循读者自然的阅读顺序——从上到下或从左到右不要在中间设计需要读者来回折返的连线。分组和折叠是控制复杂度的利器。模块边界用容器框住或用不同背景色区分次要细节可以用子图或注释折叠起来不在主图上展开。节点之间的距离也要注意间距太密会显得乱太疏则信息密度低容易让人失去注意力。我习惯在一个批次画图的开始就定好网格基准尺寸比如节点统一用 32px 间距、圆角统一 4px、字号统一 11pt。不要小看这种一致性的效果当整张图所有元素都遵循同一套视觉节奏时即使不加任何装饰也会显得专业。3.3 命名、颜色、箭头视觉语言要统一很多人的图乱不是因为布局而是因为视觉语言混乱。比如箭头有时表示依赖、有时表示时序、有时表示数据流那读者就不得不靠猜。我给自己定了一个视觉规范写文档时一直沿用实线箭头表示“调用/依赖”虚线箭头表示“异步/可选路径”粗线表示“关键链路”颜色只用来区分“类型/层级”不用来单纯装饰最多不超过 4 种主色节点标题用“动词名词”来写比如“创建订单”“校验库存”少用含糊的“订单模块”作为节点名。命名上有一个容易被忽略的点节点上的文字是读者最先看到的东西字号和对比度一定要排在装饰前面。我经常看到有人把图做得特别花哨结果文字压在低对比度的背景上看都看不清这种图再好看都是失败品。颜色还要注意可访问性色盲人群约占人口总数 8%如果你用红绿对比来表达关键状态这部分读者可能就完全读不懂图。可以在关键地方同时用样式来区分比如虚线、形状而不是只靠颜色。4. 代码化图表的落地实践用版本管理和自动化把图“养”起来4.1 选型细节PlantUML 和 Graphviz 谁更适合你这两个是我日常用得最频繁的代码化方案。PlantUML 胜在领域语法画时序图、用例图、组件图时特别顺手几乎是声明式的写法——声明一个 Actor、声明一个 Component连线用一行-表示生成的图结构基本合理。Graphviz 胜在自动布局引擎和对复杂关系图的控制力它的 DOT 语言里可以精确指定节点顺序、层级方向、甚至节点之间的约束关系。如果只是画 UML 类图、时序图我强烈建议直接 PlantUML理由是它的语法跟 UML 概念一一对应团队里其他人接手也容易看懂。但如果要画的是依赖关系图、调用链图、甚至是 Devops 的部署拓扑Graphviz 的自动布局会用一种极其聪明的方式帮你把关系理顺手动排不出来的复杂连线它都能给出可接受效果。快速对比一下判断维度PlantUMLGraphviz DOT上手速度快像在写伪代码中等需要理解图模型UML 支持原生开箱即用需要自己构建结构自动布局一般但按领域优化非常强适合复杂关系样式定制够用需要花时间调典型场景时序图、用例图、部署图架构依赖图、状态机、流程图我见过有人非要用 Graphviz 画时序图也有人非要用 PlantUML 画网状依赖图都是在跟工具的优势硬刚最后效果都不理想。选型不是看哪个高级而是看哪个跟你的问题模型匹配。4.2 搭建可维护的图表仓库代码化了之后下一步就是把图组织好。我习惯在项目的docs/diagrams目录下按域拆分子目录比如docs/ └── diagrams/ ├── order/ │ ├── create_order.puml │ └── order_state.dot ├── payment/ │ └── payment_flow.puml └── common/ ├── legend.puml └── style_config.dot关键文件用include或!include引用公共的样式定义、颜色变量和图例说明避免每个图里复制粘贴各自的样式后续改样式只改一处就够了。同时把“渲染结果图片”和“源文件”分开存。源文件进仓库保存而渲染出的 PNG/SVG 不要提交到 Git而由 CI 在构建文档时自动生成或者本地用脚本一键更新。这样 pr 里看到的永远是源文件的 diff而不是对着一张改动的图片发呆。4.3 用构建脚本一键渲染所有图表我一般会在仓库里放一个render.sh循环处理所有.puml和.dot文件统一输出到docs/assets/diagrams/目录。这比在 IDE 里一个个手动导出要省心太多毕竟图的迭代频率是跟着代码走的代码改一版图就要跟着改一版每次手动导出不出十次就会开始摆烂。脚本的大致思路是这样的#!/usr/bin/env bash # 注意需要提前安装好 plantuml 和 graphviz set -euo pipefail DIAGRAM_DIRdocs/diagrams OUTPUT_DIRdocs/assets/diagrams mkdir -p $OUTPUT_DIR # 渲染所有 PlantUML 文件 find $DIAGRAM_DIR -name *.puml | while read -r file; do plantuml -tsvg -o $OUTPUT_DIR $file done # 渲染所有 Graphviz DOT 文件 find $DIAGRAM_DIR -name *.dot | while read -r file; do base$(basename ${file%.dot}) dot -Tsvg $file $OUTPUT_DIR/${base}.svg done echo All diagrams rendered.用 SVG 而非 PNG 的好处是导出到文档里后放大缩小都不失真而且可以直接用 CSS 控制某些颜色主题。如果你确实需要位图png 也可以但注意把 DPI 调高一些至少 300别拿默认的 72 DPI 糊弄人。4.4 用版本管理和评审机制保证图不被“画歪”代码化的图最大优势是能进 Code Review。我强烈建议团队把图表的变更纳入评审范围改动一张架构图一样需要说明为什么、改了什么。因为很多时候改图意味着系统结构的变化这正是评审应该关注的事情。以我实际经验刚开始团队会抱怨“画个图还要走流程太重了”但坚持十来个迭代后大家就会尝到甜头——没有人再敢随手画一张误导新人的图进文档了。配合 Git 标签和各版本快照你想回溯系统任何时期的架构状态都只是一行命令的事。5. 常见问题与排查技巧实录我踩过的那些坑5.1 中文乱码与字体问题中文乱码是代码化图表里最常见的问题症状是生成出来的图里中文全变成方块或者问号。这个问题的根源几乎都是运行环境中缺少对应字体的字体渲染配置而不是代码写错了。PlantUML 的解决办法是显式声明字体名称skinparam defaultFontName Microsoft YaHeiGraphviz 则需要在 DOT 文件里给节点和边设置fontnamedigraph G { node [fontnameMicrosoft YaHei]; edge [fontnameMicrosoft YaHei]; }如果你在 Linux 服务器上跑 CI还需要确保服务器装了中文字体比如fonts-noto-cjk。别问我怎么知道的我第一次在 CI 里渲染文档时就是忘了这步所有图的中文全是方块。这是一类典型的环境问题把“本地能渲染”和“环境能渲染”当成两件事能少走很多弯路。5.2 布局乱飞如何让 Graphviz 按你的思路排线Graphviz 的自动布局大部分时候很聪明但偶尔也会出现连线绕来绕去、乱七八糟的情况。我有几个百试百灵的调整手段。用rankdirLR或rankdirTB指定整体方向别让引擎自由发挥用ranksame把同一层级的节点强制保持在一条水平线/垂直线上对关键连线用constraintfalse让它不影响默认层级排序给节点设置group属性让同组节点更紧凑地聚在一起。实战中我最常用的是ranksame和constraintfalse。很多时候图乱的原因是次要关系影响到了主线布局把这些次要连线的constraint关掉主线层级马上就清朗了。5.3 图片太模糊导出的时候就要选对格式和参数经常有人把图截个 PNG 糊进文档然后被质疑“这个图好糊”。技术文档里我一般不用位图一律导出 SVG。如果平台强制要求 PNG就把 DPI 调到 300 以上。PlantUML 的-DPLANTUML_LIMIT_SIZE8192参数也可以调整输出尺寸上限避免大图被压缩到看不清楚。这里注意一个细节不是所有文档平台都支持 SVG。有些后端渲染会把 SVG 当外部文件屏蔽这种情况下可以“SVG 源文件 PNG 预览图”双份输出源文件保证可维护性预览图保证兼容性。5.4 没人愿意维护图把维护成本降到最低技术文档图最大的杀手不是技术问题而是“维护的人几天后离职了没人知道他当时是怎么画出来的”。所以与其强迫团队用某个工具不如把画图的门槛降到最低。我采取的组合是仓库里提供一键渲染脚本、公共样式模板、简单清晰的目录结构新成员十分钟内就能上手套模板改图。另一个实用技巧是在每个 diagram 源文件头部写注释说明这张图是谁画的、对应哪个模块哪个版本的架构、更新时需要同步修改哪些代码或文档。这就像给代码写良好的注释一样能显著降低长时间后的理解成本。6. 关于团队协作与工具推广的一些体会把 diagram-design 从一个人画图变成团队规范刚开始并不容易。最大的阻力不是工具的熟练度而是“画图没有收益感”——很多人觉得写代码才是正事画图是额外负担。我的做法是把图和实际的代码评审、模块说明绑定起来让画图变成“梳理逻辑”的必要步骤改架构前先画目标图而不是架构定了之后再敷衍画一张。这样图就成了设计过程的一部分而不是事后文档。我还发现一个规律图的质量基本反映了设计者对系统理解的深度。一个人画得清晰的模块图通常对应着设计上的胸有成竹画得模糊混乱的图往往意味着逻辑还没想清楚。这跟画图技巧无关跟思维方式有关。所以如果你所在团队还没有一套 diagram 规范建议不要一上来就搞大而全的流程而是先从一张图开始选一个常用的系统场景用代码化方式画出来把源文件公开在团队文档里让大家看到“改一行字和重新渲染”的体验自然会有更多人愿意跟上。diagram-design 这件事说到底不是为了画一张好看的图而是为了把脑子里的复杂关系理清楚再以最低的成本让它保持清晰。希望上面这些踩坑和总结能让你在画下一张图的时候少绕几步远路。