前阵子接手一个遗留系统仓库里文档不少最有分量的是一张架构图。可我看完只得到三个信息中间一个方框写着系统周围几个小方框写着模块A、模块B、模块C箭头方向还自相矛盾。我花了将近两周才把真实调用链摸清最后自己重画了一张贴进 Wiki。画完那一刻我明白了一个道理diagram-design图设计这件事从来不是画得漂亮的问题而是能不能让看的人快速做出正确判断的问题。我在多个项目里反复看到同一个规律绝大多数团队的默认状态是能看懂就行。但能看懂其实是一个很低的及格线真正的图设计要回答的是看完这张图的人能不能据此做出正确决策。这篇分享不打算教某款绘图软件怎么点按钮而是把我在实践中沉淀出来的一套图设计方法拆开来讲为什么要把画图当工程而不是美工、不同图型该怎么选、为什么我最终转向图即代码、以及用代码维护图之后踩过的一堆坑。适合正在做系统设计、写技术文档或者被画图一小时、改图一下午折磨过的同学。1. 为什么画图是工程设计而不是美工活儿1.1 图的第一职责是传递约束不是展示美感很多人画图的第一反应是打开画布、找图标、调颜色。我早期也这样画一张系统拓扑图能磨两个小时最后产出物确实好看但同事看完问我的第一个问题是这个模块和那个模块之间数据到底怎么走的我愣住了——图上有连线但线没有方向也没有标注协议。后来我意识到架构图、流程图这类技术图本质上是约束的表达。它需要回答四个问题系统边界在哪、模块间能不能互相调用、数据往哪个方向流、失败时由谁兜底。一张图如果答不上这四个问题那它就是装饰画应该挂在墙上而不是放进技术文档。我常用一个比喻好的架构图应该像地铁线路图。地铁图一点都不写实站间实际距离被随意拉伸但它用颜色区分线路、用节点表示换乘、用方向标清走向乘客只需要三秒钟就能做出我该坐哪条线的判断。反过来那种照着真实地理位置画的轨道交通图虽然真实却根本没法用于日常导航。所以我在 diagram-design 里给自己定的第一条原则每一条线、每一个框、每一处颜色都必须有语义没有语义的元素一个都不要放。与其追求好看不如追求看完能直接做决策。1.2 我习惯把图分成三个层级来设计不同读者、不同阶段需要的信息粒度完全不同硬把三层信息塞进一张图是最常见的翻车现场。我通常把图拆成三个层级。第一层是全貌图landscape一页讲清楚系统边界和外部依赖。它回答这个系统站在哪里和谁打交道读者通常是新同学、评审会上的非技术角色。绘制要点是只画外部系统、网关、核心存储不画内部模块细节。第二层是模块图module/component展示系统内部有哪些模块、模块间的依赖关系、关键数据存储。它回答改一个功能会影响谁读者是开发同组的人这是日常被引用最多的图。第三层是链路图sequence/process针对一条具体业务链路画清楚跨模块的时序调用。它回答一笔请求到底经历了什么读者是正在排查问题或实现需求的开发者。这三层图不是一个项目只画一套而是各自独立演进。全貌图半年更新一次模块图每次架构调整都更新链路图则跟着具体需求走。把它们硬塞进同一张图要么全貌和细节互相遮挡要么为了保持整体布局牺牲某一层的信息完整度两头不讨好。1.3 有些场景我真的不建议你画图并不是所有关系都值得画成图。我见过有人在文档里给一个只有三个模块、依赖关系一句话能说清的系统硬画了一张架构图结果图比文字还难读。我现在的判断标准很简单这张图的信息增益是否大于它带来的理解成本如果一个依赖关系用一行文字能表达清楚就用文字如果流程超过一屏还是说不清说明流程本身需要先被拆分而不是靠一张巨图硬撑。图是降低沟通成本的工具不是文档的装饰品。图一旦需要读者反复去猜它的价值就是负的。2. 图型选型不同决策场景该用哪张图2.1 常用图型的定位速查在 diagram-design 的实践里我经常被问到该用流程图还是时序图要不要画 ER 图。我的经验是图型不是越复杂越好而是越贴合决策场景越好。下面是我最常用的几种图型定位图型核心回答的问题典型读者我通常使用的时机架构图系统边界和模块依赖新同学、评审会项目启动、架构调整流程图业务分支与状态流转产品、开发、测试需求分析、异常分支梳理时序图一次调用跨模块的顺序后端开发、排查问题设计跨服务接口、排查线上故障ER图数据实体间关系后端开发、DBA数据库设计、字段变更评审状态图对象生命周期与合法迁移后端开发、测试订单、任务等有状态业务部署图组件与运行环境映射运维、SRE环境搭建、容量规划这张表不是拍脑袋定的而是我从实际协作里总结出来的每种图型天然对应一类决策点。比如评审接口设计时序图比流程图好使因为时序图强调消息顺序和返回路径而流程图强调分支条件——评审接口时我最关心的是调用顺序对不对、超时和失败怎么处理这些恰恰是时序图的强项。2.2 三个选型问题如果你只想快速决定该画哪种图我建议每次画图前先问自己三个问题。第一这张图给谁看新同学入职看全貌用架构图同事讨论具体接口用时序图测试同学写用例用流程图或状态图。读者的身份决定了图的抽象层级。第二读者拿到图要做什么决策是要判断该不该拆模块还是要搞清失败时走哪个分支决策不同图型就不同。一张图如果同时想支撑多个决策通常会一个都支撑不好。第三这张图的变更频率有多高变更频繁的图必须考虑用代码化方式维护否则每次改图都是一次体力活变更很慢的图拖拽工具也能接受。这三个问题回答完选型基本不会跑偏。2.3 一个真实场景的图型组合举个我最近处理的例子设计一个订单支付的跨系统调用。我没有只画一张大全图而是按决策拆了三张。第一张架构图画订单服务、支付网关、账户中心、消息队列之间的关系用于评审服务边界。第二张时序图画用户下单后订单服务如何调用支付网关、如何异步回调、超时怎么补偿用于评审接口细节和异常路径。第三张状态图画订单从待支付到已支付、已取消、退款中的状态迁移用于和产品确认业务规则。三张图合在一起覆盖了边界、交互、状态三个维度每张图都足够简单评审时一次只过一张效率明显比一张全家福高。这也是我反复强调的diagram-design 的核心是拆分决策不是堆砌信息。3. 从拖拽画布到图即代码我为什么换了套路3.1 拖拽工具的三个痛点早些年我用过各种拖拽式绘图工具界面友好、模板丰富画的过程确实爽。但用久了三个痛点越来越明显。第一个痛点是版本管理。架构调整之后我改了三个框的位置、两条线的颜色同事根本看不出这次改动的意图。拖拽工具没有像样的 diff 能力架构评审变成了你截图对比。第二个痛点是协作门槛。图文件是二进制或私有格式没法在代码评审的地方直接评论。每次都要导出图片、传到文档里、再圈圈点点链路长到让人不想更新。第三个痛点是随手画的成本太低。工具越方便越容易让人不假思索就开始画画到一半发现思路没想清前面的功夫全废。图即代码最大的价值其实是逼你在写 DSL 之前先想清楚结构——语法本身比拖拽要笨但这种笨强制了思考顺序。3.2 Mermaid 的实践心得Mermaid 是我用得最多的方案因为它语法最接近自然语言团队上手成本极低。一个时序图大概长这样sequenceDiagram participant U as 用户 participant O as 订单服务 participant P as 支付网关 U-O: 提交订单 O-P: 创建支付单 P--O: 返回支付参数 O--U: 返回支付链接这种写法特别适合放在代码注释或者 PR 描述里我甚至会在接口定义的注释块里直接贴一段图源码编译器没法校验但至少文档和代码在同一个仓库里不会走丢。Mermaid 的坑我也踩过不少。最典型的是流程图里节点文字一旦包含特殊字符比如括号、冒号就必须用引号包起来否则渲染会莫名其妙失败。还有时序图里异步消息的箭头写法是 -同步是 -少写一个箭头符号语义就完全变了但语法检查不一定能拦住你。我的习惯是一段图写完后立刻在本地预览一遍别等到提交后才发现。3.3 PlantUML 的实践心得PlantUML 是我在时序图特别复杂时的备选。它的 DSL 表达能力更强尤其适合画有分组alt/opt/loop的大型时序图startuml actor 用户 participant 订单服务 as O participant 支付网关 as P 用户 - O: 提交订单 activate O O - P: 创建支付单 activate P P -- O: 返回支付参数 deactivate P alt 支付成功 O - 用户: 返回成功页 else 支付失败 O - 用户: 返回失败页 end endumlPlantUML 的激活块activate/deactivate能把方法调用期间的资源占用画得很直观这对排查连接池、事务问题特别有帮助。缺点也很明显语法更繁琐新手容易把精力花在调格式上而且默认渲染出的样式比较工程风需要额外配主题。3.4 我的选型建议如果你也在纠结我的建议可以浓缩成一张对比表维度MermaidPlantUML上手成本低接近自然语言中需要记关键词时序图能力够用复杂分支略吃力强支持 alt/opt/loop 分组流程图能力好方向控制灵活中渲染依赖轻前端即可渲染需要本地工具或服务端适合场景文档、PR 描述、快速表达复杂时序设计、正式设计文档另外一个现实约束是团队的基建。如果团队的文档平台原生支持 Mermaid 渲染我基本无脑选 Mermaid如果团队有统一的 PlantUML 服务那 PlantUML 也能用得很顺。工具本身不是关键关键是图能不能跟着代码一起走、一起被评审、一起被版本管理。这两点才是 diagram-design 里最值钱的部分。4. 一套让图不过期的图即代码工作流4.1 图文件进仓库目录怎么摆我在团队里推行过一个习惯把图的源文件放到仓库的 docs/diagrams 目录下和代码一起提交、一起走评审。目录按图的作用域来分而不是按画图的人来分docs/diagrams/ ├── landscape/ # 全貌图命名带系统名 │ └── order-system-overview.md ├── modules/ # 模块依赖图 │ └── order-modules.md ├── flows/ # 业务流程图、时序图 │ ├── create-order.md │ └── payment-callback.md └── data/ # ER 图、状态图 └── order-states.md这种分层和代码分层保持一致的目录让新同学找图就像找代码一样自然想知道全貌去 landscape想看订单链路去 flows想看状态去 data。图和代码同构是图能被持续维护的前提。4.2 命名、状态与图例的规范图文件命名我要求带场景名禁止出现新建文档 1未命名图这种名字。规范是业务场景-图型.md例如 order-payment-sequence.md 或 user-login-flow.md。图文件内部我建议在最顶部用注释标清三件事这张图的读者是谁、最后一次校验的提交号、当前状态草稿/待评审/已生效/已过时。别小看这个注释半年后回来看图如果没有这些信息你根本无法判断这张图还信不信得过。每张图还应该有一个微型图例至少说明框代表什么服务/模块/外部依赖、线代表什么同步调用/异步消息/数据流、颜色代表什么。如果一张图不需要图例就能看懂说明它足够简单如果它需要图例那就必须把图例画全不能只画图不画例。4.3 渲染与文档集成把图变成活的图即代码如果只停留在源码阶段价值会打折。我在团队里做了三件集成的事。第一把图渲染脚本接进持续集成。每次提交触发构建脚本自动把文档里的图源码渲染成图片作为构建产物存档。这样 PR 描述里可以直接引用渲染图评审人不用本地装任何工具。第二文档站点自动收集。技术文档站点的导航从 docs/diagrams 目录自动生成路径就是图名新同学点进去看到的是渲染好的图旁边附源码链接。想看细节就点源码想快速理解就看图。第三代码注释反向链接。在关键服务类或配置文件的注释里加上一句话本模块的依赖关系见图 docs/diagrams/modules/xxx.md。这等于给代码和文档之间拉了一条永久跳转链路。这三件事做完图过期的问题被极大缓解因为图已经变成代码构建链的一部分改代码的人会下意识地去看关联图是否也要改。5. 我在 diagram-design 路上踩过的四个坑5.1 坑一把所有信息塞进一张图我第一次负责一个中型系统的全貌图时把消息队列、缓存、每个微服务、甚至几张核心表都画进去了。结果这张图打印出来需要放大镜评审会上没人愿意看。后来我忍痛把它拆成六张图每张只讲一个视角讨论效率反而上来了。拆图的标准很简单读者在三分钟之内能不能指着图讲清楚这张图的核心结论如果不能说明信息熵太高必须拆。拆的时候不要按模块数量均分而是按决策点切——每个子图对应一个看完了能拍板的问题。5.2 坑二颜色语义混乱我见过不少图默认绿色正常红色异常但画到一半又用红色表示重点模块再用绿色表示已通过评审。等读者看图时颜色已经没有统一含义了只能靠猜。颜色是图里最容易被滥用、也最容易被忽视的语义载体。我现在的铁律是能够用形状和文字表达的绝不用颜色表达如果一定要用颜色全图最多三色并且必须在图例里写死含义。为了照顾色弱读者我还要求关键信息不能只靠颜色区分必须配合线型或文字标注。这条规矩执行之后图的可用性提升非常明显。5.3 坑三图不更新变成历史文物最常见的问题是架构图是三个月前画的现在系统已经重构了两次但图还是那张。新同学看完图照着去接接口结果接口早没了白白浪费半天。我后来总结出一套保质期机制图文件头部标注最后校验提交号并且把图更新挂在代码评审的检查清单里。凡是涉及模块拆分、接口变更、依赖新增的 PR评审人必须在清单里确认相关图是否已更新。机制很笨但有效。图一旦失去时效性比没有图更可怕因为它会误导所有人。5.4 坑四过度美化把时间花在刀刃外我也有一段画图先调图标的日子给每个模块配一个精致的图标阴影、渐变、立体效果都安排上然后被同事一句这个框代表什么服务问得哑口无言。真实世界里技术图的审美优先级应该排得很靠后。我的排序是语义正确 结构清晰 命名统一 排版整洁 视觉美化。如果你发现自己在画图时花了超过三分之一的精力在调整视觉细节大概率是语义还没想清楚在用美化逃避思考。6. 让图真正进入协作流从画完就扔到持续有效6.1 把图当作评审材料而不是交付物我过去有个错误心态图是设计完成后的产出物画完了就存档。后来我改成图是设计过程中的思考工具先画图再讨论最后才写代码。评审会上大家对着同一张图说话分歧会提前暴露在编码之前改图的成本比改代码低一个数量级。现在我带新方案时流程通常是先在白板上画潦草的草图和同事对齐关键决策再把草图代码化成 Mermaid 或 PlantUML放进 PR 描述里给评审人看评审通过后把图归档到 docs/diagrams 并标记已生效。这个流程里图既不是一次性草图也不是事后补交的作业而是评审的对象本身。6.2 图例和术语表一张图的README一张复杂一点的图如果不配术语表读者很容易被缩写打懵。比如OMSPGWACC这些缩写画图的人习以为常新读者完全不知道是什么。所以我在 diagram-design 规范里加了一条图文件内必须有一个缩略语表第一次出现的缩写要给全称。这个成本和收益极不成比例——一句话的注释能省掉别人大半天的猜测。另外图里用到的线型、箭头、框线样式我会在图的 README 里统一登记例如实线同步调用虚线异步消息带叉失败补偿。只有语义被白纸黑字写下来图才不会在不同人的理解里逐渐失焦。6.3 我现在的个人工作流落到每天的行动上我的个人 diagram-design 工作流其实只有五步。第一步想清楚读者和决策点回答给谁看、看完做什么决定。第二步选图型按第 2 节的三问来确定架构图、时序图还是状态图。第三步画草图在白板或纸上用最丑的线条把结构画出来只求语义正确。第四步代码化用 Mermaid 或 PlantUML 把草图转成 DSL放进仓库。第五步评审和维护把图挂进 PR、在评审清单里确认更新、给图标注状态和校验提交号。这套流程看起来很朴素但它把我从画图一小时、改图一下午里彻底解放出来了。我现在画一张模块图从想清楚到提交通常不超过半小时更重要的是半年后任何人再打开这张图都能在五分钟内判断它还信不信得过、该不该改。如果你现在还被画图这件事困扰我的建议是不要去买更多模板不要研究更多渲染技巧先拿一张你最常被别人问这里是什么的图按照上面的三层拆分、三问问诊、代码化、保质期这套方法重新走一遍我猜你会立刻感受到差别。
前阵子接手一个遗留系统仓库里文档不少最有分量的是一张架构图。可我看完只得到三个信息中间一个方框写着系统周围几个小方框写着模块A、模块B、模块C箭头方向还自相矛盾。我花了将近两周才把真实调用链摸清最后自己重画了一张贴进 Wiki。画完那一刻我明白了一个道理diagram-design图设计这件事从来不是画得漂亮的问题而是能不能让看的人快速做出正确判断的问题。我在多个项目里反复看到同一个规律绝大多数团队的默认状态是能看懂就行。但能看懂其实是一个很低的及格线真正的图设计要回答的是看完这张图的人能不能据此做出正确决策。这篇分享不打算教某款绘图软件怎么点按钮而是把我在实践中沉淀出来的一套图设计方法拆开来讲为什么要把画图当工程而不是美工、不同图型该怎么选、为什么我最终转向图即代码、以及用代码维护图之后踩过的一堆坑。适合正在做系统设计、写技术文档或者被画图一小时、改图一下午折磨过的同学。1. 为什么画图是工程设计而不是美工活儿1.1 图的第一职责是传递约束不是展示美感很多人画图的第一反应是打开画布、找图标、调颜色。我早期也这样画一张系统拓扑图能磨两个小时最后产出物确实好看但同事看完问我的第一个问题是这个模块和那个模块之间数据到底怎么走的我愣住了——图上有连线但线没有方向也没有标注协议。后来我意识到架构图、流程图这类技术图本质上是约束的表达。它需要回答四个问题系统边界在哪、模块间能不能互相调用、数据往哪个方向流、失败时由谁兜底。一张图如果答不上这四个问题那它就是装饰画应该挂在墙上而不是放进技术文档。我常用一个比喻好的架构图应该像地铁线路图。地铁图一点都不写实站间实际距离被随意拉伸但它用颜色区分线路、用节点表示换乘、用方向标清走向乘客只需要三秒钟就能做出我该坐哪条线的判断。反过来那种照着真实地理位置画的轨道交通图虽然真实却根本没法用于日常导航。所以我在 diagram-design 里给自己定的第一条原则每一条线、每一个框、每一处颜色都必须有语义没有语义的元素一个都不要放。与其追求好看不如追求看完能直接做决策。1.2 我习惯把图分成三个层级来设计不同读者、不同阶段需要的信息粒度完全不同硬把三层信息塞进一张图是最常见的翻车现场。我通常把图拆成三个层级。第一层是全貌图landscape一页讲清楚系统边界和外部依赖。它回答这个系统站在哪里和谁打交道读者通常是新同学、评审会上的非技术角色。绘制要点是只画外部系统、网关、核心存储不画内部模块细节。第二层是模块图module/component展示系统内部有哪些模块、模块间的依赖关系、关键数据存储。它回答改一个功能会影响谁读者是开发同组的人这是日常被引用最多的图。第三层是链路图sequence/process针对一条具体业务链路画清楚跨模块的时序调用。它回答一笔请求到底经历了什么读者是正在排查问题或实现需求的开发者。这三层图不是一个项目只画一套而是各自独立演进。全貌图半年更新一次模块图每次架构调整都更新链路图则跟着具体需求走。把它们硬塞进同一张图要么全貌和细节互相遮挡要么为了保持整体布局牺牲某一层的信息完整度两头不讨好。1.3 有些场景我真的不建议你画图并不是所有关系都值得画成图。我见过有人在文档里给一个只有三个模块、依赖关系一句话能说清的系统硬画了一张架构图结果图比文字还难读。我现在的判断标准很简单这张图的信息增益是否大于它带来的理解成本如果一个依赖关系用一行文字能表达清楚就用文字如果流程超过一屏还是说不清说明流程本身需要先被拆分而不是靠一张巨图硬撑。图是降低沟通成本的工具不是文档的装饰品。图一旦需要读者反复去猜它的价值就是负的。2. 图型选型不同决策场景该用哪张图2.1 常用图型的定位速查在 diagram-design 的实践里我经常被问到该用流程图还是时序图要不要画 ER 图。我的经验是图型不是越复杂越好而是越贴合决策场景越好。下面是我最常用的几种图型定位图型核心回答的问题典型读者我通常使用的时机架构图系统边界和模块依赖新同学、评审会项目启动、架构调整流程图业务分支与状态流转产品、开发、测试需求分析、异常分支梳理时序图一次调用跨模块的顺序后端开发、排查问题设计跨服务接口、排查线上故障ER图数据实体间关系后端开发、DBA数据库设计、字段变更评审状态图对象生命周期与合法迁移后端开发、测试订单、任务等有状态业务部署图组件与运行环境映射运维、SRE环境搭建、容量规划这张表不是拍脑袋定的而是我从实际协作里总结出来的每种图型天然对应一类决策点。比如评审接口设计时序图比流程图好使因为时序图强调消息顺序和返回路径而流程图强调分支条件——评审接口时我最关心的是调用顺序对不对、超时和失败怎么处理这些恰恰是时序图的强项。2.2 三个选型问题如果你只想快速决定该画哪种图我建议每次画图前先问自己三个问题。第一这张图给谁看新同学入职看全貌用架构图同事讨论具体接口用时序图测试同学写用例用流程图或状态图。读者的身份决定了图的抽象层级。第二读者拿到图要做什么决策是要判断该不该拆模块还是要搞清失败时走哪个分支决策不同图型就不同。一张图如果同时想支撑多个决策通常会一个都支撑不好。第三这张图的变更频率有多高变更频繁的图必须考虑用代码化方式维护否则每次改图都是一次体力活变更很慢的图拖拽工具也能接受。这三个问题回答完选型基本不会跑偏。2.3 一个真实场景的图型组合举个我最近处理的例子设计一个订单支付的跨系统调用。我没有只画一张大全图而是按决策拆了三张。第一张架构图画订单服务、支付网关、账户中心、消息队列之间的关系用于评审服务边界。第二张时序图画用户下单后订单服务如何调用支付网关、如何异步回调、超时怎么补偿用于评审接口细节和异常路径。第三张状态图画订单从待支付到已支付、已取消、退款中的状态迁移用于和产品确认业务规则。三张图合在一起覆盖了边界、交互、状态三个维度每张图都足够简单评审时一次只过一张效率明显比一张全家福高。这也是我反复强调的diagram-design 的核心是拆分决策不是堆砌信息。3. 从拖拽画布到图即代码我为什么换了套路3.1 拖拽工具的三个痛点早些年我用过各种拖拽式绘图工具界面友好、模板丰富画的过程确实爽。但用久了三个痛点越来越明显。第一个痛点是版本管理。架构调整之后我改了三个框的位置、两条线的颜色同事根本看不出这次改动的意图。拖拽工具没有像样的 diff 能力架构评审变成了你截图对比。第二个痛点是协作门槛。图文件是二进制或私有格式没法在代码评审的地方直接评论。每次都要导出图片、传到文档里、再圈圈点点链路长到让人不想更新。第三个痛点是随手画的成本太低。工具越方便越容易让人不假思索就开始画画到一半发现思路没想清前面的功夫全废。图即代码最大的价值其实是逼你在写 DSL 之前先想清楚结构——语法本身比拖拽要笨但这种笨强制了思考顺序。3.2 Mermaid 的实践心得Mermaid 是我用得最多的方案因为它语法最接近自然语言团队上手成本极低。一个时序图大概长这样sequenceDiagram participant U as 用户 participant O as 订单服务 participant P as 支付网关 U-O: 提交订单 O-P: 创建支付单 P--O: 返回支付参数 O--U: 返回支付链接这种写法特别适合放在代码注释或者 PR 描述里我甚至会在接口定义的注释块里直接贴一段图源码编译器没法校验但至少文档和代码在同一个仓库里不会走丢。Mermaid 的坑我也踩过不少。最典型的是流程图里节点文字一旦包含特殊字符比如括号、冒号就必须用引号包起来否则渲染会莫名其妙失败。还有时序图里异步消息的箭头写法是 -同步是 -少写一个箭头符号语义就完全变了但语法检查不一定能拦住你。我的习惯是一段图写完后立刻在本地预览一遍别等到提交后才发现。3.3 PlantUML 的实践心得PlantUML 是我在时序图特别复杂时的备选。它的 DSL 表达能力更强尤其适合画有分组alt/opt/loop的大型时序图startuml actor 用户 participant 订单服务 as O participant 支付网关 as P 用户 - O: 提交订单 activate O O - P: 创建支付单 activate P P -- O: 返回支付参数 deactivate P alt 支付成功 O - 用户: 返回成功页 else 支付失败 O - 用户: 返回失败页 end endumlPlantUML 的激活块activate/deactivate能把方法调用期间的资源占用画得很直观这对排查连接池、事务问题特别有帮助。缺点也很明显语法更繁琐新手容易把精力花在调格式上而且默认渲染出的样式比较工程风需要额外配主题。3.4 我的选型建议如果你也在纠结我的建议可以浓缩成一张对比表维度MermaidPlantUML上手成本低接近自然语言中需要记关键词时序图能力够用复杂分支略吃力强支持 alt/opt/loop 分组流程图能力好方向控制灵活中渲染依赖轻前端即可渲染需要本地工具或服务端适合场景文档、PR 描述、快速表达复杂时序设计、正式设计文档另外一个现实约束是团队的基建。如果团队的文档平台原生支持 Mermaid 渲染我基本无脑选 Mermaid如果团队有统一的 PlantUML 服务那 PlantUML 也能用得很顺。工具本身不是关键关键是图能不能跟着代码一起走、一起被评审、一起被版本管理。这两点才是 diagram-design 里最值钱的部分。4. 一套让图不过期的图即代码工作流4.1 图文件进仓库目录怎么摆我在团队里推行过一个习惯把图的源文件放到仓库的 docs/diagrams 目录下和代码一起提交、一起走评审。目录按图的作用域来分而不是按画图的人来分docs/diagrams/ ├── landscape/ # 全貌图命名带系统名 │ └── order-system-overview.md ├── modules/ # 模块依赖图 │ └── order-modules.md ├── flows/ # 业务流程图、时序图 │ ├── create-order.md │ └── payment-callback.md └── data/ # ER 图、状态图 └── order-states.md这种分层和代码分层保持一致的目录让新同学找图就像找代码一样自然想知道全貌去 landscape想看订单链路去 flows想看状态去 data。图和代码同构是图能被持续维护的前提。4.2 命名、状态与图例的规范图文件命名我要求带场景名禁止出现新建文档 1未命名图这种名字。规范是业务场景-图型.md例如 order-payment-sequence.md 或 user-login-flow.md。图文件内部我建议在最顶部用注释标清三件事这张图的读者是谁、最后一次校验的提交号、当前状态草稿/待评审/已生效/已过时。别小看这个注释半年后回来看图如果没有这些信息你根本无法判断这张图还信不信得过。每张图还应该有一个微型图例至少说明框代表什么服务/模块/外部依赖、线代表什么同步调用/异步消息/数据流、颜色代表什么。如果一张图不需要图例就能看懂说明它足够简单如果它需要图例那就必须把图例画全不能只画图不画例。4.3 渲染与文档集成把图变成活的图即代码如果只停留在源码阶段价值会打折。我在团队里做了三件集成的事。第一把图渲染脚本接进持续集成。每次提交触发构建脚本自动把文档里的图源码渲染成图片作为构建产物存档。这样 PR 描述里可以直接引用渲染图评审人不用本地装任何工具。第二文档站点自动收集。技术文档站点的导航从 docs/diagrams 目录自动生成路径就是图名新同学点进去看到的是渲染好的图旁边附源码链接。想看细节就点源码想快速理解就看图。第三代码注释反向链接。在关键服务类或配置文件的注释里加上一句话本模块的依赖关系见图 docs/diagrams/modules/xxx.md。这等于给代码和文档之间拉了一条永久跳转链路。这三件事做完图过期的问题被极大缓解因为图已经变成代码构建链的一部分改代码的人会下意识地去看关联图是否也要改。5. 我在 diagram-design 路上踩过的四个坑5.1 坑一把所有信息塞进一张图我第一次负责一个中型系统的全貌图时把消息队列、缓存、每个微服务、甚至几张核心表都画进去了。结果这张图打印出来需要放大镜评审会上没人愿意看。后来我忍痛把它拆成六张图每张只讲一个视角讨论效率反而上来了。拆图的标准很简单读者在三分钟之内能不能指着图讲清楚这张图的核心结论如果不能说明信息熵太高必须拆。拆的时候不要按模块数量均分而是按决策点切——每个子图对应一个看完了能拍板的问题。5.2 坑二颜色语义混乱我见过不少图默认绿色正常红色异常但画到一半又用红色表示重点模块再用绿色表示已通过评审。等读者看图时颜色已经没有统一含义了只能靠猜。颜色是图里最容易被滥用、也最容易被忽视的语义载体。我现在的铁律是能够用形状和文字表达的绝不用颜色表达如果一定要用颜色全图最多三色并且必须在图例里写死含义。为了照顾色弱读者我还要求关键信息不能只靠颜色区分必须配合线型或文字标注。这条规矩执行之后图的可用性提升非常明显。5.3 坑三图不更新变成历史文物最常见的问题是架构图是三个月前画的现在系统已经重构了两次但图还是那张。新同学看完图照着去接接口结果接口早没了白白浪费半天。我后来总结出一套保质期机制图文件头部标注最后校验提交号并且把图更新挂在代码评审的检查清单里。凡是涉及模块拆分、接口变更、依赖新增的 PR评审人必须在清单里确认相关图是否已更新。机制很笨但有效。图一旦失去时效性比没有图更可怕因为它会误导所有人。5.4 坑四过度美化把时间花在刀刃外我也有一段画图先调图标的日子给每个模块配一个精致的图标阴影、渐变、立体效果都安排上然后被同事一句这个框代表什么服务问得哑口无言。真实世界里技术图的审美优先级应该排得很靠后。我的排序是语义正确 结构清晰 命名统一 排版整洁 视觉美化。如果你发现自己在画图时花了超过三分之一的精力在调整视觉细节大概率是语义还没想清楚在用美化逃避思考。6. 让图真正进入协作流从画完就扔到持续有效6.1 把图当作评审材料而不是交付物我过去有个错误心态图是设计完成后的产出物画完了就存档。后来我改成图是设计过程中的思考工具先画图再讨论最后才写代码。评审会上大家对着同一张图说话分歧会提前暴露在编码之前改图的成本比改代码低一个数量级。现在我带新方案时流程通常是先在白板上画潦草的草图和同事对齐关键决策再把草图代码化成 Mermaid 或 PlantUML放进 PR 描述里给评审人看评审通过后把图归档到 docs/diagrams 并标记已生效。这个流程里图既不是一次性草图也不是事后补交的作业而是评审的对象本身。6.2 图例和术语表一张图的README一张复杂一点的图如果不配术语表读者很容易被缩写打懵。比如OMSPGWACC这些缩写画图的人习以为常新读者完全不知道是什么。所以我在 diagram-design 规范里加了一条图文件内必须有一个缩略语表第一次出现的缩写要给全称。这个成本和收益极不成比例——一句话的注释能省掉别人大半天的猜测。另外图里用到的线型、箭头、框线样式我会在图的 README 里统一登记例如实线同步调用虚线异步消息带叉失败补偿。只有语义被白纸黑字写下来图才不会在不同人的理解里逐渐失焦。6.3 我现在的个人工作流落到每天的行动上我的个人 diagram-design 工作流其实只有五步。第一步想清楚读者和决策点回答给谁看、看完做什么决定。第二步选图型按第 2 节的三问来确定架构图、时序图还是状态图。第三步画草图在白板或纸上用最丑的线条把结构画出来只求语义正确。第四步代码化用 Mermaid 或 PlantUML 把草图转成 DSL放进仓库。第五步评审和维护把图挂进 PR、在评审清单里确认更新、给图标注状态和校验提交号。这套流程看起来很朴素但它把我从画图一小时、改图一下午里彻底解放出来了。我现在画一张模块图从想清楚到提交通常不超过半小时更重要的是半年后任何人再打开这张图都能在五分钟内判断它还信不信得过、该不该改。如果你现在还被画图这件事困扰我的建议是不要去买更多模板不要研究更多渲染技巧先拿一张你最常被别人问这里是什么的图按照上面的三层拆分、三问问诊、代码化、保质期这套方法重新走一遍我猜你会立刻感受到差别。
平方复杂度无法被常规优化消除｜TaoToken 统一 Key 通道实测)
