两年前我接手维护一套内部微服务文档时发现光“业务订单流转”这个话题四个团队就各自画了六张“架构图”每一张的图例、箭头和分组方式都不一样。最要命的是这些图里没有一张能回答最简单的那个问题用户下单之后到底会有哪些系统参与这个经历直接催生了我对 diagram-design 这个主题的执念——不是折腾某个制图软件而是把“画图”当成一项和写代码同等严肃的设计工作。这篇文章不聊花哨的视觉风格只聊我是怎么定义 diagram-design 的从沟通目标、工具选型、视觉规范到把图表嵌进研发流程的全过程。适合后端开发、架构师、技术文档写作者以及对“图表维护”已经受够了的任何人。1. 先别打开画图工具想清楚这张图是给谁读的1.1 图表是一种“降维沟通”不是装饰很多人把画图当成写文档的最后一步代码写完了顺手画一张图放上去觉得“有图总比没图强”。但我在多次评审中得到的真实反馈是一张信息混乱的图比没有图更有害。因为它给读者制造了一种“我已经看懂了”的错觉等到深入细节才发现图里表达的东西和实际代码完全是两回事。我的理解里diagram-design 的第一步是承认一个事实图表是把多维信息强行压到二维平面上。比如一张系统架构图它同时包含组件之间的调用关系、数据流向、部署边界、异常分支、版本状态。如果你不加筛选地把这些信息全画进去这张图就退化成一团互相交叉的线。降维沟通的核心是你只选择当前场景里最需要传递的那一两个维度其余信息用文字补充。1.2 场景决定图型而不是工具决定图型我在给团队做内部培训时经常问一个问题你要画的到底是“流程”还是“结构”这两个问题对应完全不同的图型。流程类问题适合用流程图、时序图、状态图读者关心的是“先做什么再做什么出错怎么办”结构类问题适合用模块图、部署图、服务拓扑图读者关心的是“有哪些组成部分它们之间是什么关系”。一个很常见的失误是有人在画系统架构时把流程也硬塞进去。比如一张服务拓扑图里既画了服务之间的依赖线又画了“用户请求先经过 A 再到 B”的箭头还在边上标注“如果失败则重试”。结果就是同样的图形符号同时表达两种完全不同的语义读者每看一条线都要猜这是调用关系还是时序顺序。我总结了一张简单的选择表放到项目 wiki 里团队画图前先对号入座读者想解决的问题适合的图型核心表达元素一次功能操作经历了哪些步骤流程图/活动图泳道、分支、结束节点多个服务之间一次调用如何协作时序图参与者、消息顺序、返回当前系统有哪些模块依赖关系如何组件图/模块图分层、边界、依赖箭头请求从用户端到数据库经过哪些部署节点部署图/拓扑图节点、网络分区、协议一个对象在其生命周期中有哪些状态变化状态图状态、事件、迁移条件系统从大块拆到小块的层级关系C4 分层图/嵌套图容器、组件、代码边界这张表不是在限制创意而是在一开始就把“图形的语法”定下来。diagram-design 和写接口文档很像先定协议再填内容。1.3 每一种连线都要能被追问画完一张图之后我习惯做的第一件事是随机挑一条线问自己三个问题这条线代表什么语义它是同步调用还是异步消息它是必然发生还是条件触发如果任何一个问题答不上来说明这条线还没有被想清楚。这时候不应该急着把它画上去而应该回到代码或需求里查证。这里有一个我能反复验证的经验画图过程中的“卡壳点”往往就是系统里设计得最模糊的地方。有一次我画一个支付回调的时序图画到一半发现“支付成功通知”这条线我不知道是从支付网关直接到订单服务还是先到回调网关再转发。去翻了实际代码才知道支付网关只回调回调网关然后由回调网关做验签和转发通知可靠性和签名校验的责任边界完全不一样。这张图帮我发现了一个文档盲区而这是纯文字 Review 不会暴露的。所以diagram-design 的一个重要原则是每一根线条都必须经得起追问。画不下去的地方通常不是绘画技巧问题而是系统理解问题。2. diagram-design 的核心迁移从画布拖拽到图表即代码2.1 我在画布工具里踩过的三个坑早期我用的是 draw.io 和 Visio 这一类“所见即所得”的拖拽工具。它们最大的优点是上手快画出来的图可以直接用布局随心所欲。但用在长期维护的技术文档里我踩过三个非常痛的坑。第一个坑是变更不可追踪。四个人先后编辑同一张架构图每个人都挪动过几个框、改过几条线但你无法通过 diff 看出这个改动是“新增了一个服务”还是“只是把框拉宽了一点”。图变成了一张不可 Review 的黑盒资产。第二个坑是“复制粘贴式蔓延”。团队里只要有一张图画得不错就会出现十几个副本部署文档里一份、接口文档里一份、周报里一份每个副本被不同人手工改过。时间一长你根本不知道哪一份是对的。这个问题的根源是画布工具的文件很难做细粒度的版本对比也没人愿意每次改完同步到所有副本。第三个坑是布局感依赖个人状态。拖拽工具里同样的内容在不同人手里画出来完全是两套风格有人习惯从上到下画有人从左到右有人给每个框加一圈阴影有人喜欢纯平面。风格不统一其实不是审美问题而是信息表达不一致比如“虚线”在 A 的图里代表异步调用在 B 的图里代表弱依赖。2.2 文本图表方案的分工与选型后来我把主体图表全部迁移到“图表即代码”方案上。这里的“代码”不一定指编程语言而是指用结构化的文本描述来生成图表。我目前评估过的主流工具各有各的适用场景没有哪个能统一所有需求实际项目中我通常会混合用。工具最适合解决的问题优点明确短板Mermaid快速画流程图、时序图嵌入 Markdown 文档语法最简单GitHub/GitLab 原生渲染上手成本极低布局自动排版能力一般复杂架构图容易变得拥挤PlantUML时序图、活动图、C4 分层图有较成熟的 C4 扩展支持多 UML 图型结构化表达清晰工具生态偏老部分渲染引擎需要本地 Java 环境GraphvizDOT自动布局的节点关系图、依赖图布局算法强大适合“节点多、关系复杂”的图适合程序生成学习曲线陡控制细节需要写大量属性参数Structurizr架构治理从软件模型生成 C4 图图和模型分离同一个模型可导出多视角图适合团队架构基线偏重架构场景对普通流程图支持不足选择逻辑很简单如果这张图是放在接口设计文档里说明一次调用的先后顺序我首选 Mermaid 或 PlantUML如果这张图是给一个数十个微服务的系统做整体拓扑Graphviz 能帮我自动处理复杂布局如果团队想维护一套“架构即代码”的长期资产Structurizr 的模型层更有吸引力。diagram-design 不是绑定某个工具而是明确工具的边界和用途。一个文本图表的典型结构大致是这样的节点定义 - 外卖前端 - 订单服务 - 支付网关 - 回调服务 节点关系 - 外卖前端 - 订单服务HTTP - 订单服务 - 支付网关发起支付 - 支付网关 - 回调服务异步回调 - 回调服务 - 订单服务更新支付状态文本描述的好处是它天然强制你先把“有什么节点”和“节点怎么连”分开。很多人在画布上拖拽时不会刻意做这个分离画着画着就乱了。2.3 版本化与结构化 Review 的隐藏红利图表进入代码仓库之后最大的变化不是格式统一而是它可以像代码一样被 Review。每次修改图表时提交信息里写清楚“为什么改”新增了结算服务、把同步调用改成了消息队列、删除了已下线的库存查询接口。其他同事在 Code Review 时滚动 diff 就能看出这次改动对系统拓扑的真实影响。这里我要给一个非常具体的操作习惯永远不要让图表文件单独变更。也就是说如果你改了图却没有对应的代码变更或文档变更很可能说明你在画一个不存在的系统。反过来如果代码变更涉及服务间的接口协议而你却没有同步更新对应的 diagram 文件这个 PR 就不应该被合并。把“图表是否同步”作为合并条件的一部分能有效避免图变成永远落后的装饰品。结构化 Review 的另一个好处是大家可以在图表的文本注释里直接讨论而不需要打开图形编辑器再去找对应节点。我记得有一次评审同事在某个节点旁加了一行注释“这个组件的健康检查没有超时时间建议确认。”如果不是文本存储这条评论大概率会丢在 IM 聊天记录里。2.4 保留画布工具的四个理由虽然我大方向上是图表即代码的拥护者但必须诚实现在的工作流里仍保留了少量画布工具。纯文本方案在以下四种场景里确实力不从心。第一快速探索和头脑风暴。白板、Excalidraw 这类工具没有语法负担随手画一个想法、用箭头牵引思路效率远高于文本描述。我对团队的要求是探索阶段随便画一旦决定进入文档必须转成文本图表。第二需要精细控制视觉布局的对外图片。比如给客户做架构汇报客户不关心你的工具链只关心图上的信息是否一目了然。这种情况下我会在 Generate 出的图上手工调整或者直接用画布工具重画一张干净的展示稿。第三贴图类、手绘风格的抽象示意。讲概念类比时用“一张咖啡店的订单流”来做比喻画布工具更自由。我不觉得这是需要工程约束的场景。第四团队里确实有人对命令行和配置文件感到强烈不适。强行逼所有人用文本图表会激起逆反情绪最后图也没人画了。折中的办法是代码仓库里的正式文档用文本图表个人的工作笔记爱用什么用什么。目的是让人愿意画图而不是为了统一工具而统一。3. 一张图的可读性取决于视觉规则而不是灵感3.1 让颜色先有语义再被使用很多人画图时是凭感觉选颜色的蓝色表示服务绿色表示数据库黄色表示外部依赖。感觉型配色的问题在于同一个颜色在不同图里可能代表完全不同的东西。我早期在一个项目里用过粉色代表“故障”后来又在一张新图里用粉色代表“新功能”结果被读者问“这系统是已经挂了还是刚上线”。diagram-design 里的配色应该像代码里的命名一样先约定再使用。我给团队定了一套很朴素的语义色板颜色含义典型使用场景蓝底内部组件/服务本系统内可维护的模块绿数据存储数据库、缓存、消息队列橙外部依赖第三方服务、支付网关、云厂商 API红异常/风险不稳定的依赖、高失败率调用灰已下线/待下线过渡节点、遗留系统这套规则不追求视觉惊艳但保证任何一张新图递到你面前你不需要看图例就能猜到大概含义。颜色一旦被定义为语义就不要在同一张图里为了“好看”而临时换色。真到了不得不换色的时候先改规则再改图规则和图保持一致。3.2 方向、间距和分组的反射式设计人眼对方向的感知非常敏感。大多数技术读者默认的读图方向是自上而下或从左到右。如果你的架构图中 80% 的箭头都指向右下剩下的 20% 突然从下往上读者会在心里卡一下然后开始怀疑是不是自己漏了什么。我处理方向的经验是先用“主数据流”的方向确定整张图的骨架比如用户请求从左到右经过网关、服务、数据库那么这张图的主方向就是横向。所有分支调用、回调、异常路径都作为“次级信息”放在主链路下方或右侧而不是喧宾夺主地穿插在主链路中间。间距和分组其实也是在编码信息。离得近的元素会被认为是同一个集合离得远的则被当作不同集合。与其用颜色硬区分模块不如先把空间分好同一业务域的服务放在一个矩形边界框内边界框内统一用相同的底色框和框之间保留明显的空白隔离带。这个做法在视觉心理学上叫“接近性原则”不需要任何额外解释读者一看就能get到分组关系。很多工具支持子图或容器概念在 Graphviz 里是cluster在 PlantUML 里是package在 Mermaid 里可以用subgraph。我建议任何超过 8 个节点的图都必须做分组否则信息密度会迅速超过人眼处理能力。3.3 把图例和元信息直接画进图里技术图表的读者往往不是一次性读者。同一张图会被反复查阅每次看的关注点都不同这次关注服务依赖下次关注部署边界。如果图的语义规则不明确每次阅读都要靠猜。解决办法是养成一个很少人做但非常有效的习惯在图的右下角或左下角固定放一个图例区说明本图中的箭头、线条、颜色、边框样式分别代表什么。比如图例 - 蓝色方框内部服务 - 绿色圆角框数据存储 - 橙色方框外部依赖 - 实线箭头同步 HTTP/HTTPS 调用 - 虚线箭头异步消息 / 事件 - 红色描边当前存在稳定性风险这个图例区信息量不大但能把一张图的“语法”固定下来。团队协同时图例就是图表的接口文档。另外我还会在图的标题下方写一行元信息这张图对应的代码目录、最近一次更新日期、维护人。原因是再过半年回来看图的人大概率不是画图的人。有了元信息他至少能判断这张图值不值得信任以及找谁确认细节。3.4 给信息密度设上限超了就拆我个人的经验阈值是这样的一张技术图如果可以独立阅读的节点超过 20 个或者连线超过 30 条就必须拆分。拆图的逻辑不是按面积切而是按读者的关注点切。比如一张“订单全局架构图”可以拆成“订单主链路时序图”“订单服务依赖图”“订单部署拓扑图”三张分别服务不同的问题。这个方法有点像代码设计里的单一职责原则。一张图只回答一个问题才能保证图内的每个元素都在为这个问题服务。如果舍不得拆就会看到后来的人在这张图上继续堆节点堆到最后图变成了没人能读懂的“地图炮”。4. 一次完整的架构图设计过程从零梳理订单核心链路4.1 先收集事实别急着连线很多人在画图时倒过来先打开工具拉个框写“用户”再拉个框写“订单系统”然后开始连线一边连一边想还缺什么。这样画出来的图往往缺节点因为思维顺序是顺向的容易漏掉边界情况和反向调用。我的处理顺序是先按住自己用纯文本把事实列全。以一张订单服务拓扑图为例我会先列出所有参与者前端外卖小程序/H5 入口Nginx 网关 核心服务订单服务、支付服务、库存服务、积分服务、消息中心 数据存储MySQL订单库、Redis缓存、MQ订单消息 外部依赖微信支付、地图定位服务、短信服务商这个阶段不关心“画得漂不漂亮”只关心“有没有遗漏”。信息来源包括实际代码目录、接口清单、部署配置、以及线上监控里的服务调用关系。有条件的话宁可跑一遍 trace也别只凭记忆画。4.2 第一版必然是一堆乱糟糟的方框把节点列完后我通常会生成一版“平铺图”所有节点都在一个平面上不分组、不排序只用最原始的线条表达调用关系。这一版一定很难看但它有一个重要作用暴露出系统的真实复杂度。平铺图里最常见的问题是“跨层级依赖”和“网状调用”。比如前端直接调用了订单服务订单服务又直接查了用户服务用户服务还反向调了订单服务查订单状态这些在平铺图里会形成交叉线。看到交叉线不要急着重新布局而是先问自己这些依赖是不是设计上就是合理的有些交叉是架构腐化的信号。我第一次给一个老项目画服务拓扑时平铺图里出现了超过 30 条交叉线。我顺着每一条交叉线去翻代码发现有两个服务存在循环依赖订单服务调用库存服务库存服务在超卖回滚时又反过来调用订单服务的接口修改状态。这个循环在图上一目了然但在代码评审里被忽略了很久。4.3 用“边界”而不是“颜色”做分组纠正了不合理的依赖之后再来处理平铺图的混乱。我的分组原则是边界框优先于颜色分层优先于位置。对于订单系统我分了三个边界接入层前端、Nginx、网关业务层订单、支付、库存、积分、消息依赖层MySQL、Redis、MQ、微信支付、短信服务同一个边界框内部的节点是允许存在依赖关系的边界框之间的箭头表示跨层访问。跨边界的线条越少说明系统分层越清晰。很自然的当我把全部节点装进这三个框后图面立刻干净了因为绝大多数调用都发生在业务层内部跨边界的只有几条骨干链路。这个做法的本质是用“容器边界”替代“颜色区分”。颜色只能让人在视觉上归类但边界框还能限制节点的活动范围思路更接近代码里的命名空间。4.4 重新定义箭头的含义而不是全部画实线确定分组后下一步是重新审视每一条连线的语义。我要求每条线要么是“同步调用”要么是“异步消息”并且箭头样式必须一致实线代表同步虚线代表异步。平铺图阶段有些线画的是“订单服务 - 消息中心”这其实是发消息不是调用接口。如果全画实线箭头读者会误以为订单服务在同步等待消息中心返回。改成虚线后语义立刻清晰了。支付回调这条也非常典型。支付网关异步调用回调服务回调服务再主动查一次订单服务或者通过 MQ 通知订单服务。线型不同排查问题时的思路完全不同。这张图在 QPS 不高的时候看不出区别但一旦出现回调延迟虚线还是实线决定了你是先去查 API 超时还是先去查消费堆积。4.5 加一层“风险标注”让图具备可操作性架构图不只是现状的映射还应该是改进方向的输入。所以我会在图上额外标出风险点不稳定依赖用红色描边存在循环依赖的节点在图上注释以及对账补单的关键路径单独打星号。比如订单服务依赖库存服务做库存预占这个调用是同步的。一旦库存服务变慢订单服务的线程池会被占满进而拖垮整个下单入口。我在图上把这条线加粗并标成红色旁边备注“库存服务超时未设置存在级联故障风险”。这张图后来被拿到架构评审会上直接推动了超时时间和熔断阈值的配置优化。风险标注让图表从“记录现状”变成“指导行动”。否则图只是给大家一个虚假的安全感看过之后一切照旧。4.6 渲染之后的“可信度检查清单”最后一步是在渲染完成的图上做一次清单检查。我先贴团队现在用的检查项每个节点是否都有真实的代码或配置文件对应没有的话是不是纯概念节点每条线上是否有明确的协议或载体对应的接口路径或消息 Topic 是否能在代码里搜到图里的所有服务是否都还在线上运行有没有已下线但没删除的僵尸节点如果读者只花 15 秒看这张图他能不能说出系统由哪几个核心部分组成如果读者进一步花 5 分钟对照图去查日志图的描述是否与日志行为一致这份清单不是为了找茬而是为了防止“把图画得很完整但和真实系统没关系”的情况。我见过太多“理论上很完美”的图对着监控一看根本不是那么回事。图的最高原则是诚实。5. 把图表嵌进工程流程评审、版本、发布与自动化5.1 图表进入 Git 仓库的目录规划我建议在仓库中专门建一个docs/diagrams目录按照图的用途而不是系统模块来组织。用途维度比模块维度更稳定因为系统模块会不停重命名和拆分而用途如“订单主链路”“部署环境”“接口时序”通常保持稳定。一个经过几个项目验证的目录结构大致是docs/diagrams/ ├── architecture/ │ ├── order-system-overview.dot │ └── payment-flow.puml ├── sequence/ │ ├── create-order.puml │ └── refund-callback.puml ├── deployment/ │ ├── staging.dot │ └── production.dot └── README.mdREADME 里写清楚每张图对应的代码模块、维护负责人、以及“改代码必改图”的约定。这个目录结构本身也是一种 diagram-design 的实践文档的结构和代码的结构保持对称读者想找哪张图凭直觉就能找到。5.2 图表评审关注什么语义优先于绘图技巧图表 Review 很容易变成“你觉得这个颜色不好看”之类的闲聊。为了避免低效我在 PR 模板里列了四个固定问题这次改动是否引入了新的节点或关系如果有是否与实际代码对应是否有节点或关系被删除这些删除是否和代码下线或重构保持一致改动会不会影响其他文档的引用如果会是否同步更新图的语义是否因为本次改动变得模糊比如箭头数量是否超过读者短时记忆的极限信息密度是否过高这四问把图表评审从主观审美拉回到事实核对。如果 PR 里只有绘图修改没有配套代码或文字说明我会直接打回因为那往往意味着有人在手工“美化”一张和现状脱节的图。5.3 与文档流水线的集成方式文本图表的另一个好处是可以被流水线自动处理。我们在 CI 里做了一个很轻量的步骤把指定目录下所有图源文件渲染成 SVG 或 PNG再上传到静态文档站。这样Markdown 里引用的是 SVG 文件而不是源代码本身。任何人提交了新的.puml或.dot文件文档站会自动更新。对于复杂度冲突我会把图拆成多个小图让每张图在 Markdown 中独立呈现。比如订单详情页的时序图拆成“下单时序”和“退款时序”两张中间用文字过渡指引。阅读体验会比一张巨型图好很多。还有一个小技巧在每张渲染图的底部用脚本自动生成一行版本信息生成时间2026-02-18 14:23 源文件docs/diagrams/sequence/create-order.puml这行信息能避免“读者看到一张旧图还以为是最新的”这种尴尬。版本信息是图表可信度的护栏。5.4 半自动化的边界别让生成脚本取代思考技术圈里有一股“万物自动化”的风气似乎不自动生成图就不够高级。我的态度是机器可以帮你把数据变成图但解决不了“这张图该表达什么”的问题。我在某些监控大屏上尝试过直接从指标元数据生成拓扑图说实话对于“发现新服务上线”“发现调用关系异常”这类异常检测自动图很有价值。但它生成的图通常没有经过语义筛选和风险标注信息密度极不均匀不适合作为架构评审的输入。所以我的结论是用脚本生成数据图用人工维护逻辑图和架构图。生成式图表的定位是辅助发现而不是替代人类的 diagram-design。6. 维护几年后的真心话6.1 图表不是洋葱越分层越没人看C4 模型提出分层视角是有价值的但很多团队把它理解成“必须画四层图”于是一张系统上下文图、一张容器图、几张组件图叠起来一大本最后除了画图的人自己谁也没看完过。我现在的原则是按需分层而不是按模型分层。如果团队只关心服务部署在哪里、谁调用谁两张图就够了。只有当你需要深入某个容器的内部结构时才为它单独画一张组件图。为分层而分层的架构图本质上是在用形式感掩盖思考的懒惰。6.2 删除不用的图比画新图更重要图表和代码一样是有维护成本的。我在仓库里看到超过一年没有更新、也没有链接指向的图时会毫不犹豫地删除。删除前我会做一次确认图描述的系统模块是否还在图中涉及的接口是否还存在有没有其他文档链接到这张图如果没有说明它已经成了噪音。删掉一张过期的图表不会让团队损失信息只会让剩下的人少一份“这张图可能是可信的”误判。我常说diagram-design 不只是怎么画图还包括怎么让图保持生命力而生命力的一部分就是适时地让它消失。6.3 一张诚实但粗糙的图胜过一张精致但说谎的图这几年我最大的体会是技术图表的最终价值是帮助团队建立一个共享的心理模型。这个模型应该和真实系统的行为一致否则图越漂亮危害越大。有不少非常精美的架构图颜色统一、箭头整齐、排版对称但仔细核对后会发现它缺少实际部署结构、没有标出单点故障甚至连服务名称都是错的。这种图的存在比不画图更糟糕因为所有人都基于一个错误的模型做决策。反过来说一张手绘的、带涂改痕迹的草图只要关键节点和关键链路是对的它对团队协作的贡献远大于一张空有其表的成品图。所以我把 diagram-design 这件事落地的核心原则很简单先保证图说真话再想办法让它好看。团队协作里没有比“可信”更重要的审美标准。