1. 从“diagram-design”这个标题说起它到底在解决什么问题第一次看到“diagram-design”这个标题很多人会下意识觉得它是个纯设计话题——无非是画流程图、架构图、时序图选个好看的主题配色就完事了。但真正在项目里画过几十张图、被同事吐槽过“看不懂”、被领导打回过“逻辑太乱”的人会明白图的设计从来不是审美问题而是信息传递效率问题。一张图能不能让人三秒钟抓住重点取决于你在画之前有没有想清楚“这张图是给谁看的、要回答什么问题、哪些信息必须出现、哪些信息必须砍掉”。“diagram-design”这个标题背后我理解的核心诉求是如何系统化地设计一张图让它既准确又高效地传达信息。它可能涉及架构图、流程图、状态机图、数据流图、部署图、时序图等多种类型也可能涉及工具选型比如用代码生成图还是用拖拽工具、配色规范、布局原则、命名约定等一系列细节。关键词和摘要描述虽然为空但从标题本身可以推断这是一个偏实操、偏方法论的方向适合那些需要频繁用图来表达技术方案、梳理业务逻辑、做项目汇报的开发者、产品经理、技术写作者。我自己的经历是早期画图完全凭感觉觉得“把框框连起来就行了”结果做技术评审时被问得哑口无言——箭头方向反了、模块边界模糊、数据流向和调用流向混在一张图里。后来才慢慢总结出一套自己的画图流程先定图的类型和读者再定抽象层级然后才是布局和配色。这套流程让我画图的时间缩短了至少一半返工率也大幅下降。下面我就把这套东西拆开来讲尽量把每个决策背后的“为什么”说清楚。2. 画图之前必须想清楚的三件事读者、问题、抽象层级2.1 读者决定图的类型和详细程度很多人画图的第一步是打开工具但我现在的第一步是问自己这张图给谁看给开发同事看的架构图和给非技术背景的领导看的业务流程图完全是两种东西。给开发看的图可以出现具体的类名、接口名、中间件型号甚至端口号给领导看的图必须把技术细节全部隐藏只保留业务模块和它们之间的关系。我踩过的一个典型坑是给一个跨部门评审会准备了一张部署图里面标了每个服务的实例数、CPU配额、网络策略。结果会上业务方的人完全看不懂一直在问“这个框是干嘛的”。后来我学乖了同一套系统准备两张图一张业务视角图只画“用户、订单、支付、库存”这些业务概念一张技术视角图画服务、数据库、消息队列。两张图分开讲效率高很多。所以你在动手之前先花两分钟回答这几个问题这张图的读者是谁他们的技术背景如何他们看这张图的场景是什么是评审、汇报、文档、还是排错他们看完之后需要做出什么决策或执行什么操作这三个问题的答案会直接决定图的类型、粒度和标注方式。比如排错场景的图必须标注日志路径和监控指标汇报场景的图必须突出关键路径和风险点。2.2 一张图只回答一个问题这是我最想强调的原则一张图只回答一个问题。我见过太多人试图用一张图同时表达“系统架构 数据流向 部署拓扑 调用时序”结果就是一张密密麻麻的蜘蛛网谁看谁晕。正确的做法是拆图。比如一个电商下单流程可以拆成业务流程图用户从浏览到支付成功经过哪些业务环节服务调用图下单请求经过哪些微服务每个服务做什么数据流图订单数据在哪些存储之间流转哪些是同步写、哪些是异步写状态机图订单状态如何从“待支付”流转到“已完成”每张图只回答一个问题读者看的时候不需要在脑子里做信息过滤。拆图还有一个好处当某个环节发生变化时你只需要更新对应的那张图而不是重画整张蜘蛛网。2.3 抽象层级要统一不能混搭抽象层级混搭是另一个高频问题。比如在一张图里有的框代表一个业务模块比如“用户中心”有的框代表一个具体的技术组件比如“Redis缓存”有的框代表一个部署单元比如“华东区集群”。这三种东西不在一个抽象层级上放在一起就会让人困惑Redis缓存是属于用户中心的还是独立于用户中心的我的经验是同一张图里所有节点的抽象层级必须一致。要么全是业务模块要么全是服务要么全是部署单元。如果你确实需要表达跨层级的关系那就用两张图一张高层概览一张低层细节然后用编号或颜色对应起来。提示判断抽象层级是否统一有个简单方法——看所有节点的命名。如果命名里同时出现了“XX业务”“XX服务”“XX数据库”“XX机房”那大概率层级混了。3. 工具选型代码生成图还是拖拽工具我的实际取舍3.1 两类工具的本质差异画图工具大致分两类代码生成类比如用文本描述生成图和拖拽类比如用鼠标拖框连线。这两类工具没有绝对优劣关键看你的使用场景。代码生成类的优势是版本可控、易于修改、适合放进代码仓库。你改一个文本文件图就自动更新了而且 diff 清晰评审的时候能看出改了哪几行。缺点是布局控制力弱复杂图的自动布局经常不尽如人意需要花时间调参数。拖拽类的优势是布局自由、所见即所得、适合做一次性汇报图。缺点是版本管理困难改一个框的位置可能牵一发动全身而且很难在代码评审里体现变更。我自己的做法是混合使用架构图、流程图、状态机图这类需要长期维护、频繁变更的图用代码生成汇报用的业务示意图、一次性分析图用拖拽工具快速出图。3.2 代码生成图的实操细节以我常用的文本绘图方案为例核心是把图拆成“节点定义”和“关系定义”两部分。节点定义里写清楚每个节点的类型、名称、分组关系定义里写清楚谁指向谁、箭头类型、标签。一个容易忽略的细节是节点 ID 的命名。很多人用中文名直接当 ID结果改名字的时候要全局替换容易漏。我的习惯是用英文短 ID比如svc_order、db_user然后在显示名称里写中文。这样改显示名不影响结构改结构也不影响显示名。另一个细节是分组和子图。当节点超过 15 个时一定要用分组把相关节点框在一起否则读者会迷失。分组的原则是按“职责边界”或“部署边界”来分不要按“画图方便”来分。# 伪代码示意不是具体工具语法 group 订单域 { node svc_order [订单服务] node db_order [订单库] node mq_order [订单消息队列] } group 支付域 { node svc_pay [支付服务] node db_pay [支付库] } svc_order - db_order svc_order - mq_order svc_order - svc_pay3.3 拖拽工具的避坑经验拖拽工具最大的坑是对齐和间距。手动拖出来的图框与框之间的间距往往不一致箭头歪歪扭扭看起来很不专业。我的经验是打开网格和对齐辅助线所有节点吸附到网格统一节点尺寸同类节点用同一个宽高箭头尽量走直线或直角避免斜线交叉文字标签统一字号和颜色不要有的加粗有的不加还有一个坑是颜色滥用。很多人觉得颜色越多越好看结果一张图七八种颜色读者根本不知道每种颜色代表什么。我的原则是颜色只用来表达语义不用来装饰。比如红色表示风险或异常绿色表示正常蓝色表示主要流程灰色表示辅助或已废弃。如果一张图里颜色超过四种就要反思是不是语义没定义清楚。4. 布局与视觉编码让读者三秒钟抓住重点4.1 布局的三种基本模式图的布局本质上只有三种模式从左到右、从上到下、中心辐射。选择哪种模式取决于你要表达的关系类型。从左到右适合表达流程和时序因为人的阅读习惯是从左到右时间线自然展开。从上到下适合表达层级和归属比如组织架构、模块分层。中心辐射适合表达以某个核心节点为中心的关系比如网关和各个服务的关系。我见过最常见的布局错误是把流程图画成了从上到下但流程本身是循环的结果箭头绕来绕去读者要反复上下看。这种场景其实更适合从左到右循环的部分用回环箭头表示。4.2 视觉编码的四个维度视觉编码指的是用视觉元素表达信息的方式。常用的有四个维度形状、颜色、大小、线型。每个维度都应该有明确的语义不能随意使用。视觉维度常见语义使用建议形状矩形服务/模块圆柱数据库菱形决策圆角矩形外部系统同类节点必须同形状不要混用颜色红风险/异常绿正常/成功蓝主流程灰辅助/废弃颜色不超过四种且要有图例大小大核心/高频小边缘/低频大小差异不要超过两倍否则显得突兀线型实线同步调用虚线异步消息粗线关键路径线型语义要在图例里说明这里有个容易被忽略的点图例。如果你的图用了颜色或线型来表达语义必须在图的角落放一个图例。我见过太多图用了红绿蓝三种颜色但没有任何说明读者只能猜。图例不需要很复杂三五行就够了。4.3 文字标注的取舍图上的文字标注是最难取舍的。写多了图显得乱写少了读者看不懂。我的经验是遵循**“节点写名词连线写动词”**的原则。节点里写名词短语比如“订单服务”“用户数据库”“支付网关”。连线上的标签写动词短语比如“创建订单”“查询用户”“发送消息”。这样读者顺着箭头读就能自然理解成“订单服务创建订单写入订单数据库”这样的句子。如果连线上的标签太长可以用编号代替然后在图下方用文字说明。比如连线上标“①”图下方写“① 订单服务调用支付服务发起扣款请求”。这种方式适合连线密集的图。注意不要在节点里写大段文字说明。节点是视觉锚点不是文档。需要详细说明的内容放在图下方的文字段落里。5. 从零画一张架构图的完整过程以订单系统为例5.1 第一步明确图的边界和读者假设我要画一张订单系统的架构图读者是开发团队的新成员目的是让他们快速理解系统由哪些服务组成、服务之间如何交互。那么这张图的边界就是“订单系统及其直接依赖”不包含上游的网关和下游的物流系统那些可以用外部系统节点一笔带过。抽象层级定为“服务级”每个节点代表一个可独立部署的服务或存储。不出现类名、方法名、端口号这些更细的层级。5.2 第二步列出所有节点并分组我习惯先用纸或文本列出所有节点然后分组。订单系统的节点大概有订单服务核心订单数据库存储订单消息队列异步通信支付服务依赖支付数据库存储库存服务依赖用户服务依赖外部网关入口分组按职责边界订单域订单服务、订单库、订单消息队列、支付域支付服务、支付库、支撑域库存服务、用户服务、入口外部网关。5.3 第三步确定布局和连线布局选择从左到右入口在左订单域在中间支付域和支撑域在右侧。连线按实际调用关系外部网关 - 订单服务创建订单订单服务 - 订单数据库读写订单服务 - 订单消息队列发送订单事件订单服务 - 支付服务发起扣款支付服务 - 支付数据库读写订单服务 - 库存服务扣减库存订单服务 - 用户服务查询用户信息连线用实线表示同步调用虚线表示异步消息。订单服务到消息队列用虚线其余用实线。5.4 第四步添加图例和说明图例放在右下角说明实线、虚线、各颜色的含义。图下方用一段文字说明这张图的阅读顺序和关键路径。关键路径是“外部网关 - 订单服务 - 支付服务”用粗线或高亮色标出。5.5 第五步自查和迭代画完之后我会做一次自查所有节点是否在同一抽象层级连线方向是否和实际调用方向一致有没有遗漏的关键依赖图例是否完整新成员不看文字说明能不能大致看懂通常自查会发现两三个问题改完之后再找一位同事快速看一眼确认没有歧义。6. 那些年我踩过的画图坑五个真实教训6.1 箭头方向反了评审会上被当场指出早期画调用图我把“订单服务调用支付服务”画成了支付服务指向订单服务。原因是我想当然地觉得“支付是下游应该指向订单”。实际上箭头应该表示“调用方向”或“数据流向”而不是“依赖方向”。后来我养成了一个习惯画完箭头后顺着箭头读一遍看能不能读成一句通顺的话。比如“订单服务 - 支付服务”读成“订单服务调用支付服务”如果读不通说明箭头方向可能反了。6.2 模块边界模糊读者不知道谁属于谁有一次画微服务架构图我把“配置中心”画在了所有服务的外面但没有用分组框起来。结果读者以为配置中心是一个独立的业务域实际上它是基础设施。后来我学会了用背景色或虚线框来区分“业务域”和“基础设施”。业务域用实线框基础设施用虚线框或灰色背景一眼就能区分。6.3 颜色太多读者不知道看哪个我曾经在一张图里用了七种颜色本意是区分不同的业务域。结果评审时有人问“这个紫色是什么意思”我才发现图例里漏了紫色。后来我给自己定了个规矩一张图最多四种颜色且必须有图例。如果业务域超过四个就用分组框代替颜色区分。6.4 图太大打印出来看不清有一次做汇报我把一张包含三十多个节点的架构图塞进了一页 PPT。投影出来之后后排的人完全看不清节点里的字。后来我学会了拆图高层图只放五到八个节点细节图放在附录里。汇报时先讲高层图有人问细节再翻到附录。6.5 没有版本管理改乱了找不回用拖拽工具画图时我经常直接覆盖保存结果改了几版之后想回到之前的版本发现找不到了。后来我养成了习惯每次大改之前先导出一份 PDF 或图片存档文件名带上日期和版本号。如果是代码生成图就直接用版本控制工具管理每次变更都有记录。7. 让图长期可维护的几个习惯7.1 图和代码放在一起如果图描述的是系统架构最好把图的源文件放在代码仓库里和代码一起维护。这样代码变更时评审的人能顺便看到图有没有同步更新。我见过太多项目代码已经重构了三轮架构图还是两年前的版本完全失去了参考价值。7.2 给图加一个“最后更新日期”在图的下方或角落标注最后更新日期和更新人。这不是为了追责而是为了让读者知道这张图的时效性。如果一张图是半年前的读者看的时候就会多一分警惕知道可能有些细节已经过时了。7.3 建立命名约定节点命名、分组命名、连线标签都要有统一的约定。比如服务节点统一用“XX服务”数据库统一用“XX库”消息队列统一用“XX队列”。这样读者看到名字就能知道节点类型不需要看图例。7.4 定期清理废弃节点系统演进过程中有些服务会下线有些依赖会移除。这些废弃的节点如果一直留在图上会让图越来越乱。我的做法是废弃节点不直接删除而是移到图的边缘用灰色和虚线框标出标注“已废弃”。等下一个大版本再统一清理。7.5 用图来驱动讨论而不是用图来记录结论这是我最深的一点体会图的最大价值不是“记录已经想清楚的东西”而是“帮助你想清楚还没想清楚的东西”。在画图的过程中你会被迫回答“这个模块的边界在哪里”“这个依赖是否必要”“这个数据流是否合理”这些问题。所以我现在画图往往是先画一版粗糙的然后在团队讨论中不断修改图改完了方案也就清晰了。8. 关于 diagram-design 的一点个人体会画图这件事工具和技巧都是次要的核心是你想清楚了多少。一张逻辑清晰的图哪怕用最简单的工具画读者也能看懂一张逻辑混乱的图哪怕用最漂亮的配色读者也会迷失。我现在的习惯是画图之前先花五分钟在纸上列节点和关系想清楚了再打开工具。这五分钟的投入能省下后面半小时的返工。另外不要追求一次画到完美。图是迭代出来的第一版粗糙没关系关键是快速画出来然后找人看、找人问。别人的每一个“这里是什么意思”都是你改进图的机会。画得多了你会发现自己对系统的理解也在加深——这可能是画图带来的最大意外收获。