今天想好好聊聊 diagram-design。最近这个词在技术社区出现频率很高但很多人以为它就是“画图”打开工具拉几个框、连几根线一两个小时交差。我在一线做系统设计和技术文档这些年最大的感受是绝大多数团队里的图根本算不上设计。流程图只有箭头没有流程架构图只有框没有边界时序图只画了调面没画数据的来龙去脉。真正能承担“表达复杂关系”的图是需要一套方法论的从布局到配色从逻辑分层到版本管理每一步都在影响读者能不能在三秒内看懂你想说什么。这篇文章我会先把 diagram-design 的核心问题拆开再讲工具选型、实操流程和排障经验。无论你是后端、前端、架构师、文档工程师还是产品经理只要需要向别人解释“系统怎么工作、流程怎么走、数据怎么流动”这套思路都能直接用。我尽量不写虚的都是我在真实项目里试过、踩过坑、最后沉淀下来的做法。1. 先别急着画diagram-design 到底在设计什么1.1 一张图最重要的不是好看是“关系正确”很多新手画图第一步就打开工具拖方块拖完再想怎么连线。这个顺序是错的。diagram-design 的前提是你要先把“待表达的知识结构”想清楚然后才谈得上视觉呈现。举个例子。我见过一张“系统部署图”里面把 Nginx、网关、四个微服务、Redis、MySQL 全部画在同一层每个框都一样大箭头从 Nginx 发散到所有服务又从每个服务连回 MySQL。这么画信息是有的但读者根本看不出哪个模块依赖哪个、哪条链路是核心路径、哪里存在瓶颈。问题不出在绘图技巧而出在对“关系”的建模就出了问题。所以我在带团队时定了一条规矩画图前先在纸上或用文字列出三件事——实体、关系、方向。实体是“有哪些模块/角色/系统”关系是“谁依赖谁谁调用谁谁属于谁”方向是“数据从哪里流向哪里控制流又是怎么走的”。这三件事列清楚了图形化只是把列表翻译成方框、圆形和箭头的过程翻译出来的图天然就具备逻辑骨架。关系正确还有一个容易忽略的点不要为了图面“好看”而牺牲关系。正交折线、弧线、分组框这些都是辅助读者理解的手段不是装饰。如果一条依赖线为了绕开某个视觉元素而故意拐弯读者会以为这两个点之间有什么特殊语义这就在制造误导。遇到这种情况正确做法是调整布局重新规划区域而不是别扭地连一根线。1.2 流程图、架构图、时序图选错类型图就输了一半diagram-design 里最基础但也最容易被搞错的一步是选图表类型。不同类型的图承载的语义完全不同用错了读者会按错误的语法去解读。我做一个快速对照表列一下我在项目中最高频用到的几类图以及它们最适合出现的场景图表类型核心问题适用场景常见误区流程图“接下来发生什么”业务流程、操作步骤、告警处理规则把分支画成并行忽略条件判断架构图“系统由哪些部分构成如何分层”系统整体结构、模块边界、部署关系所有框一个层级没有边界语义时序图“一次交互里消息按什么顺序传递”API 调用链、异步事件、事务过程只画调用成功路径不画异常分支ER 图“数据实体之间有什么关系”数据库设计、领域模型、元数据梳理把外键关系画成普通依赖线泳道图“流程中的每个环节由谁负责”跨部门流程、分布式任务角色划分泳道过多导致主流程被切割成碎片用户旅程图“用户在每个阶段体验如何”产品设计、用户增长、体验优化把内部业务流程硬塞进用户视角这里最关键的判断标准是“你要回答什么问题”。如果问题关心“顺序”选流程图和时序图问题关心“结构”选架构图问题关心“归属”选泳道图问题关心“实体关系”选 ER 图。选对类型后面所有布局和样式工作才有基础。2. 工具选型扔掉全家桶按场景搭一套轻量组合2.1 主流工具的真实体感对比工具不是越多越好但“一个工具打天下”在真实项目里也经常吃瘪。为什么因为 diagram-design 的场景差异太大写方案时你需要快速产出、容易改做架构评审时你需要协同批注沉淀到代码仓库时你需要源文件是纯文本做对外发布时你需要像素级精美的导出图。这四件事目前没有任何一个工具能全部做到优秀。我把用过的工具按真实体感整理了一下工具最大优势最让人头疼的点最适合的场景draw.io离线免费、桌面 Web、导出质量稳定样式偏工程风默认配色土系统架构图、网络拓扑、ER 图Excalidraw手绘风极度轻量实时协作顺滑不好表达复杂正交布局没有严格图层管理头脑风暴、快速对齐、临时讲解Figma设计能力强图层/组件/样式系统完善学习成本高画技术图有点“杀鸡用牛刀”对外展示图、关键架构视觉稿PlantUML纯文本可纳入 Git自动布局复杂布局控制力弱调样式要写代码代码库内文档、快速生成时序图MermaidMarkdown 原生支持学习曲线平缓复杂架构图布局容易乱排错靠经验仓库 README、Confluence 快速插图Lucidchart模板丰富企业协作成熟收费不便宜数据安全要求高的团队不敢用跨团队大型流程图、流程建模这个表不是“排行榜”而是帮你判断在这个项目里你需要在“改得动、传得开、长得好看”三个维度上做取舍。有一次我在做一个客户交付方案对方要求所有图都能在 Word 里继续编辑我只能选 draw.io 导出可编辑对象而内部技术评审时大家最看重的是“评论里能人”于是就用 Excalidraw。2.2 我现在的推荐组合以及为什么这样搭我现在个人常用的组合很简单PlantUML draw.io Excalidraw偶尔用 Figma 做一张对外发布的主视觉图。PlantUML 负责“想清楚逻辑”。所有需要在评审前反复修改的图我优先用 PlantUML 写文本版。文本的好处是可以 diff可以评论可以随着代码一起提交。比如画时序图写十来行描述语言就能生成一张还算规范的序列图改起来比拖拽快得多。draw.io 负责“正式化交付”。当图的核心逻辑已经稳定需要精细调整对齐、配色、字体、导出清晰度时我会用 draw.io 重新整理。它支持导入部分模型也可以直接手绘更重要的是导出 SVG 的兼容性很好放进 ArkTS、Latex、PPT、Word 都不会出大问题。Excalidraw 负责人“早期碰撞”。需求还没定、架构还在讨论的阶段画严谨的正交连线反而会让人不敢改。Excalidraw 的手绘风传递了一个潜台词“这是草稿随便改。”这个心理暗示在共创讨论里非常有用。这个组合背后的原则是不要让工具成为你思考的枷锁也不要让图成为不可修改的圣旨。一旦一张图的源文件锁死在某个在线平台里导出格式又不可控它就会迅速腐烂成无人维护的“历史文物”。3. 布局、配色、标注一张图的自解释能力3.1 布局先于元素把阅读顺序留给读者布局是 diagram-design 里最容易被忽视的“隐形层”。大多数人画图时是随机放框的——哪里有空位就往哪里拖最终出来的图信息密度极高但阅读顺序完全失控。真正好的布局是让读者的视线沿着你预设的路径走一遍。我常用的布局策略有以下几条主流程方向一致。流程图和架构图默认从上到下或者从左到右不要混用。写方案文档时左上角是起点做数据流转时左侧是源系统右侧是目标系统。整体保持一个方向读者就不用来回找位置。把强关联元素放进同一个视觉容器。可以利用系统边界、泳道、分组框在一张大图里划出几个“区域”比如“用户端”“服务端”“数据层”。分组的作用不是装饰而是降低读者的工作记忆负担。留白是布局的一部分。元素之间至少保持一个统一的基础间距宁可图稍微长一点也不要密到让连接线彼此粘连。我一般遵循“框与框之间至少留出框本身高度的 0.5 倍”这个下限。对齐和统一夸张重要。所有同层级的框宽度保持一致同一列的中心线对齐同一行的基线对齐。这种视觉上的“规则感”会让读者潜意识觉得这张图是经过推演的而不是随手拼的。一个很实用的办法画完初稿后把图缩小到缩略图大小。如果在这个尺度下你仍然能清晰说出“这里有几块、每块的边界在哪里”那布局就是合格的。反之就说明图面太碎需要合并分组。3.2 配色和样式用“少即是多”对抗花哨配色是 diagram-design 里翻车率最高的一环。很多人觉得图要“高大上”就每个框填一个颜色结果整张图像打翻的调色盘。读者根本分不清哪些颜色有语义、哪些只是装饰。我的配色原则非常简单整张图最多使用三种主色加一种强调色。主色用来区分大类比如“外部系统”统一用一种色“内部服务”用一种色“数据存储”用一种色强调色只用来标记关键路径、异常分支、风险点。注意强调色不是让你把每个环节都涂一遍而是只在少数几个需要读者特别关注的地方用。还有一个经常被忽略的点颜色不能作为唯一编码。在色弱或色盲用户眼里红色和绿色可能无法区分。所以我在用颜色区分语义时一定会同时用“线型、形状、图标、文字标签”做补充。比如“危险流程”用红色虚线 一个警示图标“正常流程”用蓝色实线 普通箭头。这样就算读者看不出颜色差异也能通过形状和虚线识别含义。样式统一也非常重要。所有框尽量用相同的圆角、线宽、阴影风格。如果从网上拖了一堆形状有的圆角大有的直角有的有阴影有的没有整张图的专业感会瞬间崩塌。我一般会在图例里写明“主色、虚线、实线、箭头”分别代表什么然后所有元素严格遵守。3.3 标注与图例让图脱离讲解也能读一张合格的 diagram-design 作品应该能做到“开会时你不需要解释每一根线”。这就必须靠标注和图例来兜底。先说节点命名。我看到太多人用“后台系统”“接口服务”“数据库”这种极其模糊的名字。节点名称应该遵循“名词 动词 / 状态”的结构比如“订单服务接收创建请求”“库存扣减事务完成”“消息队列待消费”。读者哪怕不熟悉代码也能明白节点在这个流程里承担什么职责。连线也不能只画一根素箭。理想情况下每条线旁边应该有简短标注说明这条关系的语义。数据流图里写“HTTP 调用”“异步通知”“读写缓存”时序图里写“返回订单详情”“抛出异常”。能写动词就不要只写数据表名因为动词才表示行为。图例和元信息是很多图的短板。我强烈建议在图的右下角加一个小图例区至少包含图中的颜色分别代表什么、实线和虚线分别代表什么、菱形/圆形等特殊形状代表什么。如果是正式文档还要在外面标上图的标题、版本号、日期、绘制人。这样读者拿到一张截图也能追溯背景不会过两个月就不知道这图说的是哪版系统。4. 实操演示从0画一张系统架构图4.1 动手前先列信息清单别让工具替你做设计我拿一张最常见的系统架构图举例走一遍完整流程。假设我们要设计一个“电商订单服务”的架构图诉求是让新同事快速理解系统边界和核心调用链。在打开任何工具之前我会先列一份信息清单系统的边界是什么哪些模块属于这个服务哪些属于外部依赖。核心模块有哪些订单处理、库存服务、支付客户端、消息中心。外部依赖有哪些用户系统、商品中心、第三方支付渠道。关键数据流下单请求进入 - 校验库存 - 冻结库存 - 调用支付 - 支付回调 - 更新订单状态 - 发送消息。部署视角这些模块运行在什么环境里是否需要区分 K8s 集群、数据库实例、缓存集群。这些信息列出来之后你会发现画图已经完成了 50%。剩下的工作只是把这几个问题翻译成图形语言。4.2 用 PlantUML 快速打草稿先有逻辑再谈样式第二步我会用 PlantUML 写一个可运行的草稿。这样有两个好处一是纯文本方便修改二是我能先把关系和顺序确定下来不会被鼠标拖拽带偏节奏。下面是一份示意性的 PlantUML 描述startuml title 电商订单服务架构草稿 skinparam componentStyle rectangle package 外部依赖 { [用户系统] [商品中心] [支付渠道] } package 订单服务 { [订单API网关] as api [订单核心服务] as order [库存适配器] as stock [支付客户端] as pay [消息中心] as mq } database 订单库 as db database 缓存 as cache [用户系统] - api : HTTP下单 api - order : 创建订单 order - stock : 校验并冻结库存 stock - [商品中心] : 远程调用 order - pay : 创建支付单 pay - [支付渠道] : 请求支付 [支付渠道] -- pay : 异步回调 pay - order : 更新支付状态 order - db : 持久化订单 order - cache : 写缓存 order - mq : 发送订单事件 enduml这个草稿画完你不需要关心字体大小、对齐和配色只需要做一件事把这段描述念给同事听问他们“这张图表达的关系有没有歧义”。在这个阶段改逻辑成本几乎为零等到了 draw.io 里调整完样式才发现箭头方向错了返工成本就高了。4.3 把草稿导进 draw.io 做精细布局确认逻辑没问题后我会到 draw.io 里重绘一遍。为什么不直接导入源文件因为自动布局出来的图往往在视觉上不够收敛导进去调整样式的功夫不如手动重画一遍更干净。在 draw.io 里我按五个步骤推进画边界。先在最外层拖一个大的容器写上“电商订单服务”把所有内部模块放进去。这样读者第一眼就知道系统的边界在哪里。放模块。按照“上到下”的顺序最上面是入口网关中间是业务核心下面是数据层。把外部依赖放在左侧或右侧用虚线框圈起来标注“外部系统”。连主线。先画最重要的调用链用实线加粗线条尽量用正交折线避免斜线。每条线都加上动词标注。加异常和弱依赖。用虚线表示异步事件、回调、定时任务。这些线尽量走图的外围不要穿插主链路。打磨样式。统一框的圆角、宽度、字体大小。用不同的填充色区分边界订单服务内部用一种主色外部依赖用灰色数据库用深色。这里有一个很关键的技巧draw.io 里开启“布局 - 吸附到网格”并且把网格间距设置为 10 的倍数。这样所有元素拖出来都会自动对齐后续手动微调的工作量会少很多。如果对齐还是费劲就多使用“对齐”功能里的左对齐、居中对齐、等宽、等高。4.4 发布前的自检清单和导出配置图基本完成后我习惯花两分钟按一份清单过一遍而不是直接导出分享逻辑层所有连线是否都有方向有没有悬空的线头有没有指向不明的线布局层主流程是否一眼能看出来有没有交叉线两边留白是否均匀样式层颜色是否超过五种实线和虚线是否有明确语义字体是否统一是否全是黑体或思源黑体等可商用字体标注层节点名称是否清晰连线是否有动词右下角有没有图例外部是否标了版本和日期导出层若用于文档优先导出 SVG透明度高、可无损缩放若用于发消息导出 PNG倍率选 2x且注意背景透明或白色背景若用于演示 PPT也可以直接复制为可编辑图形。导出 SVG 时特别要注意字体。draw.io 默认导出的 SVG 里如果字体是系统字体换台电脑打开可能显示成另一样式。稳妥做法是在“文件 - 导出 - SVG”时勾选“嵌入字体”或者干脆在发布前把所有文本转换为路径。前者文件稍微大一点但能保证跨端一致。5. 常见问题与排障我踩过的坑和排查套路5.1 连接线乱飞、布局发散的根治方法我见过最多的图是“蜘蛛网状”的连接线横七竖八人在里面绕来绕去。出现这种情况通常不是工具的问题而是布局策略没做对。如果你发现线开始乱了先做三个动作把每条线删掉重新从主线开始连。不要怕删图的面子没有逻辑的真重要。检查节点是否都放在同一条主路径上。如果一个模块同时被五个模块依赖你要么把它放到中心位置要么用“数据总线”/“消息中心”这样的虚拟节点来聚合依赖关系。把部分细节下沉到子图里。主图只保留核心链路细节画成“子步骤”或“展开图”。一图表达所有最后的结果往往是谁都看不懂。我还有一个独家技巧在 draw.io 里打开“布局 - 线路 - 正交”选项然后手动拖动连接线的中间节点。正交路由能极大减少斜线带来的视觉噪声但工具默认不一定给你最好的路径需要手动微调一两次把这条线调整成最顺眼的一条。5.2 中文乱码、字体丢失、SVG导出不清晰的坑中文乱码和字体问题是 diagram-design 里最尴尬的仪式感杀手。你辛辛苦苦画好的图换台电脑打开中文全变成了豆腐块或者 SVG 在浏览器里模糊。先说中文乱码。本质原因是字体编码不一致。我自己的习惯是所有图源文件统一使用 UTF-8 编码在工具里也明确选择中文字体比如 draw.io 里指定“Microsoft YaHei”或“PingFang SC”样式而不是让工具自动选“默认字体”。用 PlantUML 时有条件就在环境里装好中文字体包并在脚本里设置 font 参数。避免直接继承系统默认字体。再说 SVG 模糊。很多人不知道SVG 是矢量格式本身不应该模糊。模糊通常出现在两种情况下一是你从工具里导出的其实不是 SVG 而是一个位图嵌入的 SVG 包装二是你在导入 Word 或浏览器后被二次缩放时工具重新采样了。我的处理方式是导出时选择“作为扁平 SVG 导出”而不是“可编辑 SVG”在文档里使用时插入原尺寸不要反复拉伸。如果你需要位图直接从源文件导 2x 的 PNG不要拿 SVG 转多转一次就多一次失真风险。5.3 多人协作时图越改越乱怎么办多人协作画图最常见的结果是一周后这张图的元信息全没了、样式混乱、内容被无数人“微调”过。要解决这个问题技术能力是次要的关键是流程规范。我建议至少做到三点。第一所有图源文件尽量用文本格式存放在 Git 仓库里PlantUML、Mermaid、draw.io 的 XML 文件都可以入库。这样每次改动都能 diff、能追溯而不是在云盘里存一堆“最终版”“最终版2”“最终版真”。第二在协作工具里为每张图设置 Owner只允许 Owner 合并修改其他人通过评论提建议。我在 Excalidraw 协作时会把链接设置为“可评论”而非“可编辑”避免有人顺手改得不可收拾。第三统一模板。团队里如果有人用蓝底、有人用白底、有人用黑底最终的文档合集一定乱。把模板文件放到团队资源库规定新增图一律从模板复制能省下大量返工时间。6. 把 diagram-design 变成团队习惯的落地建议6.1 建一套轻量图件规范模板、命名、版本如果你想在团队里真正把 diagram-design 做成一种长期有效的能力靠一两次分享是不够的必须落到规范上。但这个规范不能太厚太厚没人看。我倾向于控制在三页以内只包含四个部分画图步骤先列关系清单 - 再画主线 - 最后上样式。这能保证所有人用同一套思维顺序产出。模板文件指定一个 draw.io 模板和一个 Excalidraw 模板里面已经配好字体、配色、图例、常用形状。新人画图不需要从白板开始。命名规范图文件名建议是“序号-主题-版本”比如“01-订单服务架构-v2.1.drawio”。版本号用语义化版本变更后递增。评审规则关键图件必须在 MR/PR 里经过至少一个人 reviewreview 的重点是关系有没有错而不是样式好不好看。实践中有个很现实的问题规范容易写坚持难。所以我推荐在团队里找个“图种子”最开始的两三张核心图由有经验的同事亲手画出来作为标准样例。样例比文档更有说服力——大家看到“原来这样画真的清晰”自然就会照着学。6.2 和文档代码联动图也是资产最后我想强调一点diagram-design 不只是“画图这个动作”它应该成为软件研发资产的一部分。把图源文件放进代码仓库和 README、设计文档、ADR架构决策记录放一起比存在个人网盘里有价值得多。我现在的做法是在一个docs/diagrams目录下统一放所有图源文件并在需要引用图的 Markdown 文档里通过相对路径引入。很多团队使用 GitLab CI 或 GitHub Actions可以在提交时自动把 PlantUML 或 Mermaid 文本渲染成 PNG/SVG 并发布到文档站。这样图永远跟代码同步代码改了图源文件也会在同一个 MR 里被强制更新。另外我强烈建议搭配 ADR 一起使用。每次做一个架构决策除了写文字说明附上一张小小的 diagram-design 图把“改动前后的依赖关系变化”画清楚。半年后回看这张图比长篇大论更容易唤起当时的上下文。如果你现在正准备给团队建一套 diagram-design 规范我最大的建议是不要一次到位。先挑一个正在进行的项目画一张真正用心的架构图或时序图把布局、配色、图例、版本号都做到位再让团队从这一张图开始复盘、改进。工具只是画笔真正值钱的是那张图背后被梳理清楚的关系。画图这件事从来不是为了好看而是为了让复杂世界可以被讨论、被理解、被改进。