1. diagram-design 要解决的真实痛点为什么你的图画完就没人看先说个我观察很久的现象团队里画图的人不少但大多数图的生命周期很短——画的时候很认真评审的时候讲一遍然后就躺在文档库里吃灰。再过两个月连画图的人自己都说不清楚图里某个模块为什么这么放。这不是绘图技术的问题是 diagram-design 从一开始就没想清楚“这张图到底要为谁、回答什么问题”。我自己带过好几个项目最早也干过这种蠢事架构图画得漂漂亮亮颜色分层、图标精美结果开发拿着图去落地时发现图里画的负载均衡根本不在选型范围内图上标的三号服务早就被拆掉了。图没错错的是画图的人把它当成了“交付物”而不是“思考工具”。所以我想聊的 diagram-design不是教你怎么把一个方框画得更好看而是帮你把图解这件事重新理一遍什么时候该画图、画什么类型的图、用什么载体、怎么让图长期有用而不是一锤子买卖。这篇文章面向的读者主要是那些被各种文档拖累的开发、架构师、技术负责人也包括正在给团队搭建协作规范的平台组同学。先给一个结论diagram-design 的核心不是“绘制”drawing而是“设计”design。画图只是把设计好的信息结构落到视觉上真正的功夫在设计这张图的信息层级、抽象粒度、阅读路径和维护边界。你可以用最粗糙的工具画出一张极有价值的图也可以用顶级的绘图软件画出一堆没人愿意看第二次的废图。我见过很多团队在工具选型上反复折腾今天用这个、明天换那个但图的质量并没有因为工具升级而变好。原因很简单工具解决的是“怎么画”的问题而 diagram-design 解决的是“画什么”和“为什么这么画”的问题。这两件事不分开想清楚换多少工具都是白搭。2. 六类常见图的适用边界架构图、时序图、状态图、领域模型、部署链路、白板图很多人画图乱不是因为不会画而是因为没搞清楚不同图的天职。就像螺丝刀有十字有一字你不能拿一字螺丝刀去拧十字螺丝然后抱怨工具不好用。图解也是一种工具每种图都有它最适合回答的那个问题强行混用就会产生灾难。2.1 架构图回答“系统由哪些部分组成彼此什么关系”这是团队里出现频率最高的图。但也是被误解最深的一类图。很多架构图画成了“部署图 组件图 流程图的缝合怪”什么信息都想塞进去结果什么信息都表达不清。架构图的正确粒度是以服务或模块为单位展示的是静态结构和关键关联关系。它回答的是“这个系统有哪些组成部分各部分之间是调用关系还是数据依赖关系边界在哪里”。最常见的毛病是两个一是把类级别的细节画进架构图导致图面爆炸二是只有节点没有关系摆了一堆框但框和框之间的连线语义模糊甚至没画线。我建议在画架构图之前先写一句话“这张图要让谁看完之后能够指出系统的边界和主要模块”如果你的答案模糊那图也会模糊。架构图的上限不是覆盖全部信息而是在一屏之内让一个新人能够建立正确的系统地图。2.2 时序图回答“一次交互中消息按什么顺序流动”时序图是排查问题和设计接口时最趁手的工具。它擅长表达“谁在什么时刻向谁发了什么消息”这在异步调用、超时重试、回调链路里格外有用。我经常看到有人把时序图画得像泳道图把业务分支全部塞进去一条线分叉成五六条每条上面挂满判断条件。这不是时序图这是用时序图的壳画流程图。时序图的价值恰恰在于它克制一条主链路、若干关键分支即可。分支多了阅读者会在图里迷路。一个好的时序图应该能被快速验证拿一次具体的请求沿着每条消息走一遍能走通、没有自相矛盾的顺序这张图就是合格的。画时序图常用的方式是文本即图的 DSL改动成本低放代码库里还能做 diff 审查这个后面专门讲。2.3 状态图和流程/活动图回答“实体如何流转什么条件触发转移”状态图和流程图的区别很多人没有真正分清。状态图的主角是“一个实体”比如订单、任务、设备它描述这个实体有哪些状态什么事件触发它从状态 A 到状态 B。流程图的主角是“一组活动”它描述的是做事步骤的先后顺序和分支选择。一个典型的错误团队想表达“申请从提交到审批通过再到归档”的过程画出来却是一张状态图因为图里关注的是“申请”这个对象的生命周期。而如果是要表达“用户提交申请后系统依次执行校验、落库、通知”这些动作那才是一张活动图。分清这两类你的图才不会被开发同学拿着来反问“这个分支是并行的还是随机的”。2.4 领域模型图回答“业务上有什么概念概念之间怎么关联”这类图在业务复杂的项目中价值极高但也最容易被忽略。领域模型图不是数据库 ER 图它展示的是业务语义层面上的实体和关系比如“客户”和“订单”之间是“一对多”而“订单”和“商品”之间经过“订单明细”产生关联。画领域模型图有一个窍门名词来自用户的业务语言而不是开发的技术语言。你会发现很多团队的系统之所以难理解就是因为图上的术语和业务方对不上。零售部门叫“客单”技术图上写“OrderHeader”两套术语系统长期并存沟通成本居高不下。domain model 图恰恰是统一语言的抓手。2.5 部署链路图回答“服务跑在哪请求怎么走完物理路径”这类图在排查性能问题、做容量评估、规划多环境部署时是刚需。它展示的是网络分层的真实路径客户端到网关、网关到应用、应用到缓存/数据库以及各节点之间的协议和端口。我踩过一个典型的坑某次线上抖动排查了半天怀疑应用代码问题结果拉出部署链路图一看应用和数据库之间隔了一个未预期的代理层长连接在代理层被频繁回收导致连接重建风暴。那张部署图是画过的但画的人只画了逻辑链路没有把真实网络路径里的每一跳标出来。所以部署链路图的原则是画你实际部署的样子不要画你理想中的样子。2.6 白板图和心智图回答“想法如何生长与收敛”这类图不追求精确追求快。它出现在方案讨论的早期用来捕捉灵感和对齐认知。白板图不需要规范甚至不需要存档它的使命是在当下让一群人看见同一个画面。但白板图有个后遗症它太好用了以至于很多人把白板图直接拍下来塞进文档当作正式设计文档。这是 diagram-design 里最隐蔽的坑——白板图颗粒度粗糙、关系不严谨放久了会成为一种误导性文档。正确的做法是白板图只用于当下讨论随后必须决定它是否值得升级为正式的架构图或时序图如果不值得就让它随风去。下面这张表是六类图的一句话定位我整理出来贴在团队文档区最显眼的位置表格图类型回答的问题典型误区架构图系统由哪些部分组成关系是什么把部署细节和类细节混进来时序图消息按什么顺序在对象间流动分支塞太多变成流程图状态图单个实体的状态如何变化把活动步骤当状态画领域模型图业务概念有哪些、怎么关联画成数据库 ER 图部署链路图请求实际经过哪些物理节点只画逻辑链路不画真实路径白板图想法如何快速对齐当正式文档长期保存3. 从工具到方法文本图 DSL 与白板工具的真实分工选工具这件事团队里永远吵不完。我的观点很简单不要把工具之争变成立场之争把图分为“活的图”和“一次性图”两大类再根据团队协作习惯去选。3.1 文本即图的 DSL 为什么适合放代码库Mermaid 这类 DSLdomain-specific language领域专用语言这几年普及很快核心原因就一个字diff 友好。文本格式的图可以放进 git改动之后能清晰地看到哪个节点变了、哪条线删了。这在代码评审流程里价值巨大——架构图不是画完就算的它会随系统演进持续修改当每一次修改都能 review图的维护质量就会明显提升。我在项目里用文本 DSL 的典型场景是核心链路的时序图和系统模块的架构图。一个约 200 行的小型服务用 DSL 写架构图不到 60 行渲染出来一屏能放下maintainer 更新起来也没有心理负担。尤其是和代码放同一个仓库服务模块改名时顺手把图改了不会出现文档里还在写旧模块名的尴尬。但 DSL 的短板也很明显布局控制能力弱。你想表达“数据库在中间、两组服务对称分布在两侧”DSL 里往往要靠调整声明顺序和 invisible 节点去 hack。这种布局 hack 很脆弱升级渲染引擎版本后可能失效。所以我在文本 DSL 的使用规范里加了一条不要追求像素级布局接受“够用”的渲染效果把精力留给内容本身。3.2 白板工具适合什么自由布局和即兴表达反过来白板类工具以拖拽节点和自由连线为代表的一类产品赢在表达效率。方案讨论现场、头脑风暴阶段、跨角色对齐场景手绘般的自由布局完胜 DSL。你在讨论过程中随时加一个便签、拉一条虚线、在节点旁边写个问号这种灵巧度是文本 DSL 做不到的。我用白板工具时会主动建立一点纪律每一块讨论区域加一个标题框说明这部分的主题讨论结束时拍照并同步到议事记录里但不作为正式设计文档。否则一周后你打开那块白板满屏的线条和便利贴根本分不清哪些是结论、哪些是被否掉的尝试。3.3 一个务实的选择矩阵如果你正在给团队制定绘图规范可以直接参考我这个选择矩阵绘图形态使用场景维护载体更新频率文本 DSL核心架构、时序、状态、部署链路代码仓库随代码改动同步白板工具方案讨论、快速对齐、头脑风暴议事记录/白板存档仅当下有效专业建模工具领域模型、复杂关系建模文档库/知识库里程碑更新手绘/拍照现场讲解、临时示意不做强制保存用完即弃这个矩阵解决了一个很实际的问题不是所有图都需要一个正式的家。给每张图找到它该待的地方比逼着团队把所有图都画成同一标准的产出物要现实得多。4. 一套可落地的团队绘制规范图源、图元、连线、命名与配色有了工具和分类还需要一套团队内部共同遵守的绘图规范。规范不是用来限制创造力是让图在换人维护之后仍然能读懂。4.1 图源每张图必须能溯源我吃过最大的亏是某张关键架构图不知道是谁画的、什么时候画的、基于哪个版本画的。问题发生时想找人确认图上的决策依据结果本人也记不清了。所以现在团队里每一张正式图必须标注三样东西创建人、创建日期、关联版本或需求编号。这看起来老土但遇到问题回溯时这三样信息能省一整天的排查时间。另一个容易忽略的点是图必须和源文件放一起。很多人把渲染好的 PNG 贴在文档里源文件随手丢在个人电脑等要改图时找不到源文件只能重画。正确做法是文档里贴图仅作为预览源文件入库且源文件命名包含图类型和主题比如sequence-checkout-flow.dsl、architecture-payment-service.dsl。4.2 图元规定每个元素的含义团队绘图最容易跑偏的是同一个图形在不同图里表达不同含义。有人在架构图里用圆角矩形表示服务换一张图里又用圆角矩形表示数据库。这会让阅读者被迫反复看图例极大消耗耐心。我给团队定的图元规范很简单架构图里服务用矩形数据存储用圆柱体或者带图标标注外部系统用带虚线的矩形框区别。状态图里状态用圆角矩形事件用箭头上的标签。领域模型图里实体用矩形、关系线上标注多重性。这套规范不追求标新立异追求的是行业常识新成员进来不用重新学一套私有的图形体系。4.3 连线区分关系的语义很多图废掉是因为所有线都是一个样式。调用、依赖、数据流、事件通知全用实线箭头图上根本没有语义差别。正确做法是至少区分三种线型实线箭头同步调用或强依赖。虚线箭头异步事件、消息通知或弱依赖。无箭头线段关联关系或配置关系方向不关键。线型之外连线的标签也要规范。不要所有线都不写名字至少关键链路的线必须标注动作比如“调用下单接口”“推送库存变更事件”。否则读者只能靠猜而猜是产生歧义的根源。4.4 命名图上的每一个节点都有全名节点命名最怕缩写。某同事画的图里有个节点写“AS”所有人问了一圈才知道是“Account Service”。缩写在一个团队内部可能约定了但图的生命周期往往长于团队成员的任期三个月后新来的同事看这张图就是天书。我要求图上的节点名使用完整的业务名或服务名如果空间有限可以缩写但必须在图例里给出全称映射。比如图上写“US”图例要注明“US User Service”。这个细节看似很小长期积累的价值极大——一张不需要向人解释的图才是真正合格的图。4.5 布局与配色最少颜色原则配色是很容易被过度追求的部分。真正有经验的团队反而是控制颜色的数量。我给团队定的原则是最多不超过五种颜色分别用于表达不同层级或类别。比如架构图里一种颜色给基础组件、一种给领域服务、一种给外部系统、一种给数据存储剩余一种给强调/异常节点。颜色一旦超过五种读者就没法靠颜色快速分类了。布局上有一条铁律阅读顺序必须清晰。常见做法是让关键路径从左到右或从上到下流动。不要为了美观把节点排成环形或中心放射状除非你的核心表达意图就是中心节点。我看到过太多的图节点排布毫无方向性读者根本不知道从哪里看起只能靠连线在图上到处跳。图的方向感是引导读者理解的第一要素。4.6 一张正规图应有的信息块最后我要求团队里所有正式图右下角统一放一个信息块。这个信息块包含图的标题、这张图回答的问题一句话、创建人和日期、关联版本。这个信息块一开始大家觉得繁琐坚持一个季度之后团队读图和找图的效率明显上升因为每个人打开一张陌生图第一件事就知道自己该关注什么。信息块示例标题订单履约核心链路架构图回答的问题一笔订单从提交到完成主要经过哪些模块和消息创建某开发者2024年6月关联release-v2.3.15. 为变化而设计增量迭代、Review 机制与图表漂移的对抗图最大的敌人是时间。系统在变图不变就变成了一张博物馆里的历史遗迹。要对抗图表漂移图表内容与实际系统的偏差靠自觉是没用的必须有机制。5.1 把图当作代码的一部分来 Review我们团队的经验是正式图必须在代码评审里一同出现。改了一个服务的接口时序图如果涉及这个接口必须同步修改新增了一个模块架构图如果没更新评审直接打回。一开始大家叫苦觉得“一个图而已何必这么较真”但坚持两个迭代后所有人的共识都变了——因为曾经被旧图误导过的痛苦远大于顺手改几行 DSL 的成本。具体操作上我们是用 MR 模板里的一个强制 checkbox本次改动是否涉及架构图/时序图/状态图如果涉及必须附上更新后的图源文件。这个机制成本极低收益极高是团队图质量长期稳定在线的第一个保障。5.2 增量更新优先于整图重画很多图最后被放弃是因为维护者一想到“要改这张图”就头大要么从头画一张要么干脆不改。问题的根源在于图的粒度太大一张图装了太多内容任何一次小改动都牵一发动全身。解法是拆图。一张图如果超过七个主要节点我建议考虑是不是该拆成两张。不是所有系统都适合一张“全宇宙架构图”更可行的是分层系统级一张展示大边界服务级若干张展示每个核心域的内部关系链路级若干张聚焦具体交互时序。这样每次变更只需要改其中一两张负担小更新意愿就高。我常用一个简单的拆分法则如果一张图里存在“两个相对独立的子系统各自成环”那它就值得被拆成两张。比如电商系统里订单履约、营销优惠两套逻辑相互独立放一张图里反而互相干扰拆开后各自由对应的团队维护谁也不会偷懒不改。5.3 定期抽样检核每季度花半天查一次图账机制再完善也总有漏网之鱼。我建议每个季度做一次图账检核随机抽 20% 的正式图对照当前系统实际状态评估偏差程度。偏差分三级一级节点名称变了但图没改属于轻微过期。二级节点新增或删除未反映属于明显漂移。三级图的核心链路表达与实际系统不一致属于严重误导。季度检核的目的不是追责而是发现系统性原因。比如某类图总是漂移说明它对应的系统变动频率太高或者拆分的粒度过粗那就应该在流程上补机制而不是靠个人记得。5.4 图表资产地图把图组织成一个体系单张图画得再好如果团队不知道有这张图它的价值也发挥不出来。我们团队在知识库里维护了一份“图表资产清单”按系统域分目录每张图有负责人、最近更新时间、关联文档链接。新人入职不看枯燥的 PPT 文档直接按这张清单一张一张看图半个月就能把系统地图搭起来。这份清单的价值在跨团队协作时格外明显。别的团队想看你们的接口关系不需要找个人来问直接在清单里找到对应的时序图比去翻接口文档快得多。6. 实操案例一个典型业务链路的 diagram-design 全过程光讲原则可能还不好消化我拿一个实际拆解过的案例走一遍全流程。背景是模拟项目X某零售系统里“订单提交”这条核心链路团队希望把它画清楚用于新成员 onboarding 和线上问题排查。6.1 第一步确定图的使命我们开了一个很短的对齐会明确这张图要回答的问题“一笔订单从客户端提交开始系统内部依次经过哪些模块、产生哪些关键事件、最终如何完成库存扣减和支付通知。”这个问题定义本身就决定了图的类型组合——需要一张时序图标定消息顺序必要时附一张架构图展示模块位置。我们决定先画时序图为主因为核心诉求是消息顺序。6.2 第二步圈定参与者和消息清单对着真实代码链路我们把参与者列出来客户端、网关、订单服务、库存服务、支付服务、消息队列、数据库。消息则是提交订单、订单校验、扣减库存、锁定库存、发起支付、支付回调、更新订单状态、发送通知。这些信息全部来自代码和实际日志而不是靠记忆勾画——这是关键差异很多图画偏就是因为凭印象画而印象会美化现实。6.3 第三步用文本 DSL 落图并评审我们用文本 DSL 编写约 100 行代码渲染出来刚好一屏。评审时我们做了一件很较真的事拿一次真实订单的追踪日志沿着时序图逐条比对消息顺序。果然发现两处偏差一是库存扣减和订单校验顺序和真实代码不一致二是支付回调处理中有一个异步分支没画。这就是图的价值——它让设计的想象和系统的现实正面碰撞把问题暴露在评审现场而不是上线之后。6.4 第四步建立更新责任图完成后我们指定订单域的一位开发作为该图的负责人。以后凡是涉及这条链路的代码改动评审时必须同时更新这张图负责人在 MR 里进行复核。这张图到现在已经在团队里服役了三个季度仍然保持准确没有变成“历史遗迹”。7. 那些最容易忽略的 diagram-design 细节坑最后分享几个我在实践中反复遇到的细节坑这些坑很小但杀伤力很大值得单独拎出来说一下。7.1 图例不是可有可无的装饰我统计过团队里的图凡是让人看不懂的有八成缺少图例说明。画图的人天天看觉得一切不言自明但读者往往不这么想。虚线表示什么、颜色深浅代表什么、带星号的节点又是什么意思如果没有图例读者就只能靠猜。加一个图例只需要五分钟但能省掉无数个“这个虚线是啥意思”的问答。我建议所有正式图都必须有图例区域哪怕只有两三条。7.2 小心“一切都能画”的心理陷阱diagram-design 最大的陷阱是试图把所有信息都画成图。有些内容更适合用表格、文字或代码表达强行图形化只会让信息密度降低、沟通效率变差。比如接口参数说明、权限矩阵、配置项清单用表格远比用图清晰得多。我的判断标准很简单这张图能否比一段文字或表格传递更多的关系型信息如果答案是否定的就别画。图的价值在于表达关系而不是复述清单。7.3 删除比添加更需要勇气图的演化中删减往往比新增困难。人都倾向于保留自己画过的框线结果图越来越臃肿直到没人看得下去。我在团队里明确了一个动作每次更新图时必须同时检查是否有不再需要的节点或连线坚决删掉。把“删除”写进更新流程才能对抗图的自然熵增。7.4 注意远程协作下的图体验远程会议里共享图时有一个隐藏问题文字太小或者线条太细投到别人屏幕上根本看不清。我建议图的默认字号在渲染后不低于 14px线宽不要低于 2px。在 1080p 屏幕上全屏看图时最小文字高度至少占屏幕高度的 1.5%。这个标准听起来苛刻但真正投屏演示一次你就知道什么叫“看不清的痛苦”。8. 归档与传承让图从一次性交付物变成团队资产图作为协作工具它的生命周期不算画完就算。真正让图长期发挥价值的是把它纳入团队的资产体系进行归档和传承。我的做法是建立一套“图档三件套”源文件入库、导出图作为文档封面预览、图与设计文档在同一目录下存放。这个目录结构大致是docs/ diagrams/ architecture-order-core.dsl sequence-checkout-flow.dsl state-order-lifecycle.dsl design/ order-core-design.md目录固定下来之后知识检索非常顺手。新成员问“订单生命周期怎么设计的”直接指到state-order-lifecycle打开不用两分钟就能建立整体认知。这种组织方式不需要额外平台一个文档仓库就够轻量、无学习成本、可检索。传承环节里还有一个软性动作定期组织一次“图解评审会”。每次挑两三张重要的图让负责人讲讲图为什么这么画、最近一次改动是什么、有哪些决策依据。这个会名义上是评审图实际上是在传递系统的设计背景和决策脉络对新人极有价值也让老成员重新审视那些“理所当然”的架构选择。我做这个动作之后最大的体会是很多隐藏的设计约束只有在讲图时才会浮现出来而这些约束往往就是后来最容易踩坑的地方。归档和传承做到位之后图就不再是一张静态的交付物而是一个不断生长的知识载体。每个团队都应该让核心图“活”在文档体系里而不是死在某个人的本地磁盘中。这些都是我踩过一遍、又慢慢修正之后总结出来的做法希望能帮你在 diagram-design 这条路上少走弯路。
