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. 最后分享一点个人体会
架构图设计这件事，说大不大，说小不小。它不像算法那么硬核，不像性能调优那么有挑战性，但它恰恰是团队协作中最频繁发生、也最容易被低估的环节。花在画图上的时间和精力，最终都会通过沟通效率的提升加倍省回来。
我个人在这些年最大的收获，是在画图过程中养成的分层思考习惯——拿到一个复杂问题，先分主次，再定层级，然后规范表达，最后反复检验。这个方法不仅适用于架构图，你在写设计文档、做方案汇报、甚至处理日常事务时都用得上。
如果你目前画的图还停留在“框加线”的水平，不用焦虑，按着这篇文章里的步骤一步一步来。先想清楚给谁看，再做信息分层，落布局，控符号，最后找到团队里一个信任的同事帮你走查一遍。坚持两三张图之后，你会明显感觉到图的清晰度和自己思考的清晰度在同步提升。
那句话说得好，画图不是画图，画的是思考过程。你的系统设计能力有多少，你的图只会告诉你——它们两者之间几乎是一一对应的。
