1. 为什么我决定重新设计团队里的每一张架构图过去两年我一直在做系统设计相关的工作经手过的架构评审少说也有四五十场。每次评审会上最尴尬的场景不是方案被质疑而是别人拿着我画的图问“这个框和那个框之间到底是什么关系”“这条线是同步调用还是异步消息”“这个模块为什么会出现在这一层”。我一开始觉得是大家没仔细看后来才发现问题出在我自己身上——我画的图只有我自己能看懂。“diagram-design”这个词听起来很宽泛但它背后其实是一整套被大多数人忽略的设计方法论。我们平时说“画个架构图”重点往往落在“画”上随手拖几个框、拉几条线、填上颜色就算交差。但真正有价值的图解决的是三个问题第一看图的人能不能在三秒内找到自己关心的内容第二图的逻辑结构是不是和系统的真实架构一致第三这张图能不能在团队里持续维护而不是画完就放在文档里吃灰。这篇文章不打算讲具体某个绘图工具怎么操作而是想分享一套我在实际项目中踩过坑之后沉淀下来的架构图设计流程。内容覆盖从目标拆解、符号规范、分层逻辑到评审验收的完整链路。无论你是后端开发、前端开发还是架构师只要你的工作里需要画架构图这套方法都能直接用。我会把每一步的思考过程、取舍依据和实际效果都讲清楚保证你看完就能在自己的项目里落地。需要说明的是文中涉及的很多细节是基于我在多个项目里的通用实践总结出来的。不同团队、不同业务场景会有些差异但核心思路是通用的。2. 画图前的三个关键决策比工具本身更重要2.1 先把读者搞清楚再谈怎么画我在指导团队里的新人画图时问的第一个问题永远是“这张图是给谁看的”这不是废话这是整张图设计的起点。同一套系统给研发看、给运维看、给业务方看、给领导看画出来的图应该是完全不同的。给研发看重点在模块划分、接口关系、数据流向术语可以专业细节可以丰富因为看的人就是天天写这些代码的人。给运维看关注的是部署形态、依赖关系、故障影响面你需要突出网络边界、中间件节点、可用性设计。给业务方看他们不关心你用了几台机器、中间件选了哪个版本他们只想知道“用户从下单到支付成功数据经过了哪些环节每一步是谁在负责”。给领导看图的颗粒度要粗颜色要清晰重点是体现系统的整体规模、关键链路和风险点。这是一个非常基础但在实践中经常被违背的原则。我见过很多架构师给业务方讲方案直接把研发内部用的详细部署图投到屏幕上结果满屏的POD、LB、读写分离把业务方看得一头雾水。不是图不好是画图的人没有想清楚读者是谁。所以拿到画图需求后的第一件事不是打开工具开始拖框而是先定三个参数读者是谁、读者关注什么、读者能接受的复杂程度上限是多少。这三个参数决定了整张图的信息密度、抽象层级和表达方式。我自己习惯先在文档里写一句话——“这张图要告诉XX角色关于XX系统的XX信息”写不清晰就不动手写清晰了再画。2.2 明确这张图的核心结论拒绝信息平铺第二个关键决策是你想让读者看图之后得出什么结论。很多人画图是在“平铺系统”——把所有模块从左到右、从上到下罗列一遍连上线配点颜色就结束了。这种图没有错但没有观点。举个例子。有一次评审一个订单系统的改造方案我拿到同事画的一张图上面有三十多个模块每个模块都画了每个模块之间的线也都画了但看完之后我完全不知道他想表达什么。他想强调的是“改造后引入了一个消息队列来削峰”还是想强调“我们把订单状态机抽成了独立服务”还是想强调“这套系统依赖外部接口太多存在稳定性风险”如果图的核心结论不清晰读者就会自己在图里找重点而每个人找到的重点都不一样。好的架构图应该是有“焦点”的。可以用层级对比来突出核心链路比如把主链路画在正中支撑模块弱化到两侧可以用颜色深浅来区分核心与非核心透明阻尼罩生活里面对中心部分的强调使得周边内容只重要程度降低等等。总之你要确保读者看完图的第一反应是你想表达的那个结论而不是“这系统东西真多”。在实际操作里我会在画图前先写一句话作为这张图的“主体陈述”就好比文章的中心思想。如果这句话写不出来说明我自己对系统还不够理解需要回到代码和文档里把业务理清楚。这个习惯让我少画了很多无效的图。2.3 统一符号体系让团队里所有人都说同一种语言第三个决策经常被忽略但影响最深远建立团队的统一符号规范。所谓符号体系包括形状的含义、颜色的含义、线条的含义。不要小看这件事我见过太多团队一个人把数据库画成圆柱体另一个人把接口画成圆柱体第三个人把外部系统画成圆柱体。图没画错但大家用的是不同的“语言”。我现在的团队里有一套约定俗成的规范这里分享一下你们可以参考实体框用矩形表示一个独立的系统、服务或模块。矩形内部写名称名称下面是简要职责说明字体比名称小一号。数据库用圆柱体这个几乎是行业通用符号不要创新不要画成别的形状否则一定会有人看错。外部系统用圆角矩形或彩色描边矩形只要内部系统用直角矩形、外部系统用圆角矩形一眼就能区分边界。虚线框用来表示逻辑分组或部署边界比如“内网区”“DMZ区”或“微服务边界”。实线箭头表示同步调用箭头方向就是调用方向。虚线箭头表示异步消息或事件通知。菱形只在流程图中表示判断架构图里尽量别用容易引起混淆。颜色的使用也要克制。我的习惯是最多不超过四种颜色一种强调核心一种表示外部依赖一种表示数据存储一种表示支撑性模块。超过四种颜色视觉上就开始嘈杂读者会失去焦点。这套规范不需要一开始就定得很完善可以在实践里逐步积累。但关键是一旦定了所有人在所有图里都要遵守。规范和工具无关和习惯有关。后面我会单独用一节来讲怎么在团队里推行这套规范这里先不展开。3. 架构图设计的四步法从信息收集到成品交付3.1 第一步做信息分层别试图一张图装下整个世界这是整套设计流程里最重要的一步也是最容易被跳过的。很多人打开绘图工具就开始画画到一半发现框太多了布局乱了然后删掉重来浪费大量时间。正确的做法是先做信息分层把系统里的元素按职责和抽象层级归好类再决定哪些元素进入图、哪些不进入。我的分类办法是按照“四个层次”来归类的这个办法适用于大多数后端系统。接入层负责接收外部请求包括网关、负载均衡、API入口、认证鉴权。应用层负责业务逻辑包括各个微服务、定时任务、消息处理服务。数据层负责状态持久化包括数据库、缓存、搜索引擎、消息队列里的持久数据。基础设施层负责运行底座包括注册中心、配置中心、监控系统、日志系统、CI/CD流程。拿到一个系统之后先把系统里所有组件往这四个层里放。放的时候你会发现有些组件是跨层的比如消息队列它既是数据管道又承担一部分业务解耦的职责。这种情况下我倾向于把它放在应用层和数据层之间用单独的区域表示不强塞进某一边。分层完成之后你还要做一次“取舍”。针对当前这张图的读者和目标判断哪些组件需要画、哪些不画。这不是偷懒而是必要的信息降噪。比如你画一张给业务方看的交易链路图就没必要把Kafka的topic分区策略画进去你画一张给运维看的部署图就没必要把业务层的类名和接口名写进去。我在实际操作中还会做一步给每个组件打标签标出它是“核心组件”还是“支撑组件”。核心组件是指如果它挂了主业务流程直接中断的组件支撑组件是指它出问题会影响体验但不会导致主流程完全不可用的组件。这个标签在后面决定布局和配色时非常有用。3.2 第二步设计布局用空间位置传递依赖关系布局是架构图设计里面最像“设计”的部分也是最体现功力的一部分。好的布局能让读者不费任何力气就理解系统的依赖方向和数据流向糟糕的布局则会把一张内容准确的图画成一团乱麻。我的布局习惯遵循一个基本原则数据流向为主轴依赖关系为辅助核心链路放正中支撑系统放两侧。以最常见的微服务系统为例我一般会用“从左到右”或者“从下到上”的方向来组织图。从左到右的含义是“用户请求从左进来穿过应用层最终落到右边的数据层”。从下到上的含义是“底层的基础设施在下上层业务逻辑在上”。两种方向都对但在一张图里不要混用。混用会打断读者的视线方向增加理解成本。在具体摆放组件时有三个小技巧非常实用相关联的组件要放在一起中间不要隔着不相关的组件。比如订单服务和支付服务如果存在调用关系就把它们画在一起而不是一个在左上、一个在右下中间连一条又长又歪的线。箭头的长度要尽量短。线越长越容易产生交叉和绕路读者追踪的时候就越费力。你可以在布局时反复调整框的位置让关键链路的连线尽量笔直。把有外部依赖的组件放在边界位置靠近外部系统那一侧。这样外部系统的图标放进来时不会跨过整个画布去连线。布局做完之后我建议你截一张图把眼睛眯起来看。眯眼之后看不清文字只能看到大块的形状和线条走向。如果这个时候你能清晰地感知到“数据从左边进来经过中间的处理落到右边存储”那这个布局就是成功的。如果眯着眼看觉得哪哪儿都挤在一起或者线条像蜘蛛网一样杂乱那不管细节画得多好都要返工。3.3 第三步统一细节规范把信息密度控制在舒适区布局确定了接下来就是填充每一个框的具体内容。这一步的坑最多因为细节最能暴露画图的人有没有认真想过。组件框里的文字怎么写是第一个要定的事情。我的规范是第一行写组件名称用14号以上的字体加粗第二行写一句话职责描述用12号以下的浅色字体。两行信息不多不少。不要往里塞接口名、版本号、部署实例数、负责人信息这些信息放进图里只会让框变得很大挤压空间而且大多数读者根本用不上。如果一定要补充这些信息可以在文档里单独建一个组件清单表格图里保持干净。关于线条设计前面已经提到了实线和虚线的语义。这里再补充三个容易忽略的细节线的粗细要有层次。核心链路的调用线可以加粗到3像素甚至更粗非核心链路的调用线用默认粗细。别小看这个细节加粗线会天然吸引读者注意力你可以利用这一点来引导视线。线不要画成直角弯折式。正交线是工具的默认选项但你如果看多了专业架构图就会发现环绕式曲线在表现复杂调用关系时更清晰。我常用的工具里都有“平滑曲线”选项打开它线的观感会好很多。每条线都要有语义而且语义要标注出来。如果一条线表示HTTP调用在线旁边写上“HTTP”如果表示异步事件写上事件名称。不标注语义的线跟没有画线没什么区别因为读者只能猜。颜色的使用在前面已经说了不要超过四种。但我还想补充一点关于配色的建议不要用饱和度太高的颜色作为大面积底色尤其是红色和纯蓝色看久了眼睛会非常累。我比较推荐用浅色调区分领域用深色调强调重点。比如整个应用层用浅灰色底核心链路涉及的组件用浅绿色底外部系统的框用浅黄色底数据库统一用浅蓝色底。这样既有区分度整体又和谐。3.4 第四步验收走查站在读者视角检查信息传达效率画完之后还有最后一步这一步是很多博主不会提但实战中极其重要的走查验收。一张图画完了不代表它可以进文档、上评审你需要用读者视角重新审视一遍。我的走查清单包括以下几个问题如果读者对系统完全不了解只看图能看出哪些重要信息核心链路是不是一眼就能识别出来有没有超过五个框的组件是读者无法从名字判断用处的有没有交叉的线条完全分不清方向图形符号是否符合团队的统一规范配色和字体大小在投影到大屏时是否依然清晰这里有一个非常实用的技巧把图缩小到原来的50%如果你还看得清所有的文字和线条说明信息密度是合理的如果缩小之后字糊成一团、线挤成一片说明图太密了需要删减内容或者拆分成多张图。我在实战中经常因为走查发现图太密不得不把一张图拆成两张一张逻辑架构图一张部署视图。这很正常不要有“一张图画完才算完”的执念。图是为清晰服务的不是为了追求大而全。拆开之后每一张图都更好读加起来的信息量反而更完整。这个走查的过程我的建议是找团队里没有参与这个系统开发的同事帮忙看一眼。自己画的图永远觉得哪里都清楚因为脑子里已经有上下文了外人看才能暴露问题。让同事花三十秒看图然后让他说出他理解的系统结构。如果他说出来的和你想表达的一致说明图过关了如果不一致那就按照他指出的迷惑点重新调整。4. 团队协作中的图规范落地怎么让所有人都遵守4.1 建立模板库把规范固化到工具里前面讲了很多个人画图的方法论但如果你在团队里要推行统一的规范光靠一份文档是远远不够的。人都是懒惰的打开工具时不会先去读规范文档然后严格按照规范去画。真正让规范落地的办法是把规范固化到工具的模板里。我的做法是在团队常用的绘图工具里做一套标准模板模板里已经定义好了各种组件样式、颜色方案、线型预设、字体大小。团队成员新建图的时候直接基于模板创建不需要重新设置样式自然就不会跑偏。这套模板应该包含的内容至少有以下几项组件样式库矩形、圆柱体、外部系统框、虚线分组框这些组件已经预设好正确的颜色和字体。线条样式库实线箭头、虚线箭头、加粗核心链路线使用方式在模板里用文字标注清楚。一个示例页面画一张标准的示例架构图放在模板里作为参考新成员只要照着示例的结构画就不会出大错。约束说明在模板的角落写一段简单的话强调“最多四种颜色”“所有线必须有语义标注”这类核心约束。别小看模板的力量。当打开一个工具看到的是一张已经预设好规范的空画布大多数人会下意识地遵循既有的样式。这比任何规范文档都有效。我一直觉得规范不是靠墙上的规章制度落地的而是靠工具和流程里的默认选项推动的。4.2 把图纳入代码评审流程当成交付物来管如果你发现团队里始终有人不遵守规范有一个办法非常有效把文档评审的“图质量”纳入正式评审的检查项。你可能觉得这有点小题大做但事实是只要评审的checklist里没有要求就没有人会为了一张图多花两小时去打磨。我经手的评审流程里架构图的海过程是这样的如果新系统有架构图评审时第一个环节就是让负责人带领大家过一遍图。负责人需要花五分钟解释这张图里的分层逻辑、核心链路、外部依赖和关键风险点。这个过程就是一次拷问如果你自己都讲不清楚图里的某个模块为什么放在那个位置、某条线为什么用实线那说明你还没想清楚。评审不通过反馈的情况我也遇到过这里分享一个亲历的案例。当时有一位新同事画了一张系统改造图整体的系统组件、调用关系都画了但有一个致命的问题他在图里把数据库画成了圆柱体同时把消息队列的topic分区也画成了圆柱体而核心业务服务的图标又是矩形。如果只是颜色或线型不统一问题不大改起来很快但数据库和消息队列的图标含义不同导致看图的人以为消息队列是存储系统差点误解了整个架构设计。评审会上直接就把这个问题提出来了他当场就意识到自己的疏忽。这就是规范的价值不是说规范本身有多神圣而是统一之后所有人都能在一套语言体系里对话误读的空间被大幅度压缩。自那以后我们团队里再也没有出现过同类问题。4.3 维护成本是真实的成本图需要持续更新最后这一点是关于图的长期价值。很多团队对文档的态度是“画完就完”图放在文档里系统迭代了七八个版本之后图还是最原始那一版。等到有人真需要查图的时候看到的是一张过期的、错误百出的图从此以后大家默认“文档都是不准的直接看代码吧”。这就是图的信任危机。要解决这个问题不能靠自觉要靠流程。我的做法是把架构图更新和代码提交流程绑定。具体来说如果一次代码变更涉及模块的新增、删除、改名或者依赖关系变化那么在提交代码的同时必须更新对应的架构图。流程上在代码评审的MR描述模板里加了一个字段——“本次变更是否影响架构图如果影响请附上更新后的图”。这个字段是必填的。实操下来这个字段的威慑力比想象的还要大。因为它意味着图不是可选的加分项而是和代码同级的交付物。一开始大家会觉得很麻烦但坚持三个月之后图的质量和维护状态就发生了质的变化。很多老图的错误被逐步修掉新的图也基本能保持准确架构文档库的信誉慢慢重建了起来。顺便说一句维护图不是那个“画图的人”一个人的事。谁改动了系统的结构谁就该负责更新对应的图。团队里没有专职的文档工程师大家都要有“对自己代码负责、对自己画的图负责”的意识。5. 实操中常见的五个坑和排查方法5.1 坑一图里全是功能模块看不到物理部署症状是一张逻辑架构图画得漂漂亮亮但读者完全不知道这些组件实际是怎么跑起来的。哪些服务是独立进程哪些是同一个进程里的多个模块哪些部署在同一台机器哪些跨了机房图里全都没有体现。排查方法看图时问自己一个问题——“如果我把这张图交给运维去搭建环境他能照着图把系统部署起来吗”如果答案是“不能”说明图缺少部署语义。解决方案是额外画一张部署视图或者在图里用虚线框把“同一个进程内”“同一台主机”“同一个可用区”边界标出来。我见过一些团队把逻辑架构和部署信息混杂在一张图里结果图变得巨复杂逻辑关系和物理关系相互干扰最后谁都没看懂。正确的做法是分开画除非系统非常简单、组件数量很少才适合合并到一张图上。5.2 坑二箭头方向混乱数据流向成了迷症状是箭头一会儿朝左一会儿朝右一会儿向上一会儿向下读者顺着箭头追两条线就晕了。还有一个常见问题图中居然出现了“双向箭头”但你问画图的人这个双向调用的真实语义他通常回答不上来。排查方法检查图中是否有超过三个方向完全相反的相邻连接如果有重新布局。检查是否有任何一个双向箭头如果有强烈建议拆成两条单向线分别标注语义因为异步回调和同步响应在架构设计中的含义完全不同混在一起是不允许的。方向混乱的根源往往是布局时没有规划好主链路导致连线跟着感觉走。解决的办法就是回到前面说的布局步骤先确定数据主轴方向再逐个摆放组件。主线清晰以后分支线再乱也不会乱到哪里去。5.3 坑三组件名称过于专业外部读者一头雾水症状是框里写的文字只有内部研发看得懂比如“hao-qian-archive-service”这种纯内部命名或者“XXX上下文”这种领域术语。对团队内部来说没毛病但如果这张图要分享给外部、新加入的成员或者业务团队就完全失效了。排查方法让一个不了解这个系统的人看图让他指出哪个框是做什么的。如果他连续两次回答“这个我猜不到”说明命名有问题。解决方案是把框里的名称换成业务视角的名称代码层面的完整名可以放在文档的组件清单表里图里不必体现。有一个例外如果图是纯技术评审用的参会人都是同领域的开发那内部术语完全可以保留因为那是共同语言。判断标准就是“读者是谁”这个第一决策。5.4 坑四图越来越“花”颜色和装饰淹没了信息症状是每个框都有不同的颜色填了渐变色加了阴影图标一个比一个大信息还没看眼睛先被样式轰炸了。这种图往往是最无效的因为读者的注意力全被视觉元素抢走根本不看内容和结构。排查方法把图改成灰度图看看。如果你在灰度状态下依然能清晰辨认层次和依赖关系说明图的结构是健康的如果在灰度状态下信息变得一片混乱说明你依赖的是颜色而不是结构来传达信息这是不牢靠的。我想说一个观点架构图不是海报它是工程文档。工程文档的第一优先级是信息传达的准确性而不是视觉美观。颜色、图标、排版都可以有但前提是它们服务于“让读者更快理解”而不是“让读者觉得好看”。说实话我在实战里见过太多被过度美化、信息传达效率一塌糊涂的图了。5.5 坑五只有一张图没有配套的说明文字症状是图虽然画得不错但没有任何文字解释。读者遇到疑惑的地方没有地方可查只能凭猜测脑补。这在评审会上尤其致命——负责人讲完图回头没有人记得他口头说的那些补充信息而图本身又承载不了这些背景信息。排查方法每次画图时给图配一个简短的说明文档。不用很长但至少要包含三个部分一是这张图的背景和核心结论二是图中核心链路的文字描述三是几个关键设计决策背后的理由。这样图和文档互相配合图负责展示结构文档负责解释“为什么”。如果要给一个建议的比例我个人倾向于一张图配半页到一页的说明文字。文字不要写流水账要写“这个系统最需要别人知道的几个关键信息”。说明文字的价值在三个月后重看这张图时最能体现——你真的会忘记自己当初为什么这么画。6. 工具选型适合不同场景的几款方案及横评聊了这么多设计方法论最后来谈谈工具。虽然我一直强调工具不是核心但选对工具确实能减少很多阻力。这里基于我自己的实践把常用的一些绘图方案分类对比一下大家可以按场景选。第一类是原生绘图工具适合画系统架构图、流程图、网络拓扑图。这类工具的特点是操作直观上手快内置丰富的组件库。对大多数团队的日常架构设计来说这类工具属于首选。第二类是代码驱动绘图工具适合模板化程度高、需要版本管理的场景。它的核心优势在于架构图是以代码文本的方式存在的可以方便地进行代码评审、版本对比和自动生成。如果你的团队已经有一套完善的代码评审流程而且希望把架构图纳入版本管理这类工具是很值得投入的方向。第三类是专业架构设计工具适合团队里有专职架构师、架构图数量多、需要长期维护的场景。这类工具支持复杂的建模能力可以定义组件属性和关系功能很强大。但学习曲线比较陡如果团队只是偶尔画几张图不建议一开始就上这么重的方案。我自己的实战经验是在中小型团队里原生绘图工具加统一模板已经能覆盖九成场景。如果团队规模大、系统数量多、维护压力大那就要认真评估代码驱动和专业化工具找到适合的那个组合方式。选工具我还想强调一点工具可以换但设计规范是通用的。你今天用A工具画图明天换B工具只要符号语义、分层逻辑、配色规范这些核心原则不变图和品质就不会因为工具的变化而崩坏。反之如果只追求工具的高级感忽略设计方法本身换再贵的工具也画不出来有说服力的架构图。7. 最后分享一点个人体会架构图设计这件事说大不大说小不小。它不像算法那么硬核不像性能调优那么有挑战性但它恰恰是团队协作中最频繁发生、也最容易被低估的环节。花在画图上的时间和精力最终都会通过沟通效率的提升加倍省回来。我个人在这些年最大的收获是在画图过程中养成的分层思考习惯——拿到一个复杂问题先分主次再定层级然后规范表达最后反复检验。这个方法不仅适用于架构图你在写设计文档、做方案汇报、甚至处理日常事务时都用得上。如果你目前画的图还停留在“框加线”的水平不用焦虑按着这篇文章里的步骤一步一步来。先想清楚给谁看再做信息分层落布局控符号最后找到团队里一个信任的同事帮你走查一遍。坚持两三张图之后你会明显感觉到图的清晰度和自己思考的清晰度在同步提升。那句话说得好画图不是画图画的是思考过程。你的系统设计能力有多少你的图只会告诉你——它们两者之间几乎是一一对应的。