1. 一张好图是怎么诞生的：聊聊 diagram-design 的完整思路
做技术这些年，我越来越觉得画图这件事被很多人低估了。很多人以为 diagram-design 就是把几个框框连起来，用流程箭头串一串，看起来像那么回事就行。但实际工作中，一张架构图、一张时序图或者一张部署图，往往比几千行注释更能说明问题。评审会上，大家围着同一张图争论半天，最后发现是图里信息层级不清晰、边界含糊、细节和抽象混在一起，根本没画到点子上。
我自己经历过不少这样的场景：文档写得再详细，别人还是喜欢对着图提问；系统交接的时候，新同事最先看的也是图；方案评审的时候，评委们盯着图的时间远远超过看文字的时间。可以说，图的质量直接决定了沟通的效率。而 diagram-design 并不是简单地把组件摆放整齐，它背后是一整套关于信息组织、视觉层级、可读性和一致性的设计方法。
这篇文章算是我这些年画图踩坑、摸索、再总结出来的一套完整经验。我尽量讲清楚 diagram-design 的核心思路、实操细节和常见的坑，并且会给出可以直接抄作业的步骤和工具搭配方案。不管你是刚入行的程序员，还是要经常写方案、做汇报的架构师或者技术负责人，只要工作中需要画图，这篇内容应该都能用得上。
2. 画图之前先想清楚：从需求到草稿的拆解过程
2.1 明确图的类型和受众
拿到一个画图需求，我的第一反应不是打开工具，而是问自己三个问题：这张图给谁看？要传达什么信息？读者需要在什么场景下使用它？
这三个问题决定了图的类型。如果是给开发同学讲模块之间的调用关系，那画时序图或者流程图最合适；如果是给运维同学交代服务部署结构，部署图更直观；如果是给非技术背景的老板看系统概览，那架构图需要弱化技术细节，突出业务价值和系统边界。很多人一上来就画组件图，画到一半发现表达不清楚，往往就是因为最开始没想清楚受众。
我举个例子。同样是描述一个订单系统：
- 给产品经理看，他关心的是用户从下单到支付再到出库的完整流程，这时应该画业务流程图，节点是业务动作，而不是技术组件。
- 给后端开发看，他关心的是订单服务怎么调用库存服务、支付回调怎么通知订单状态，这时画时序图最合适。
- 给运维看，他关心的是订单服务部署在哪些节点、依赖哪些数据库和缓存，这时画部署架构图。
同 一个系统，三种画法。如果一开始就混着画，把业务节点、服务调用、部署机器全部堆在一张图上，结果就是谁也看不懂，图变成了装饰品。
2.2 梳理信息层级：抽象与细节分离
确定好图的类型之后，下一步是梳理信息层级。这是 diagram-design 里最容易忽视，却最重要的一步。
我自己的原则是：每张图只表达一层抽象。架构图就表达系统分层和模块关系，不要在框里写 IP 地址；流程图就表达业务路径，不要在节点上贴代码片段；时序图就表达消息交互顺序，不要在生命线上堆对象属性。如果你发现自己试图在一张图里塞进两个层级的内容，那大概率应该拆成两张图。
举个例子，画一个微服务架构图，主图可以画网关、业务服务、基础服务、数据存储这几个层次，组件之间用粗线条表示调用关系。如果担心读者不知道某个服务具体依赖哪些数据库，别把数据库画在主图的组件里，而是单独画一张部署视图，在视图里标注服务到数据库的映射关系。这样主图保持干净，细节图补全深度，两者配合才是完整的设计。
实际操作中，还有一个很实用的技巧：先画出信息骨架，再考虑样式。所谓骨架，就是确定有哪些元素（模块、节点、组件）、元素之间的关系（调用、依赖、包含）、以及整体的分组方式（按层、按域、按流程阶段）。先把这些东西用最简单的方框加箭头摆在画布上，连逻辑都不纠结位置，等骨架完整之后，再去做对齐、配色、标注这些视觉层面的工作。这样做的好处是，你不会在逻辑还没定型的时候就陷进样式细节里，避免了返工。
2.3 从草稿到终稿的三轮迭代
画图这件事，我很少一稿定型。就像写代码很少一遍通过一样，图也需要迭代。
我的迭代节奏是三轮。第一轮画粗稿：不关注美观，只求把逻辑表达清楚，所有节点先用文字占位，关系用箭头连上。这轮的目标是验证逻辑是否自洽，信息有没有遗漏。第二轮做结构：调整布局，分层分组，让层级关系、并列关系、先后关系一目了然，该对齐的对齐，该拉开距离的拉开距离。这轮的目标是让图具备可读性。第三轮做润色：统一配色风格、线宽、字体，添加必要的图例和说明文字，检查是否有歧义或者误导性的元素。
看起来很简单，但很多人只做了第一步就发布了，或者直接从样式开始做起，最后逻辑一改全部推翻。我见过不少初学者的图，画得很漂亮，配色高级、图标精致，但仔细看逻辑是错乱的：同一个节点出现两次、箭头指向反了、分层关系含糊。这就是本末倒置了。记住一个原则：先对逻辑，再谈美观。
3. 核心细节解析：不同图种的绘制规范与实操要点
3.1 架构图：层次、边界与依赖的表达
架构图是我画得最多的图种，也是信息密度最容易失衡的地方。好的架构图，核心在于让读者一眼看出系统的分层结构、模块边界和依赖方向。
分层是架构图的灵魂。我通常用横向泳道来分层，自上而下分别是接入层、应用层、服务层、数据层。每一层内部放对应的组件，层与层之间用统一的箭头表示调用方向。这里有一个常见的错误：箭头方向画反了。每次评审我都提醒，接入层的请求方向是自外向内，数据层的查询方向是应用层到数据层，不要把读取数据画成数据主动推给应用。虽然很多图工具提供双向箭头，但我还是建议明确单向箭头，一个箭头只表达一个方向，减少歧义。
依赖关系的表达也要克制。架构图上不要把所有互相调用的线都画出来，否则会变成一团乱麻。我一般只画主要依赖路径，次要依赖在文档里用文字说明。实在要表达复杂依赖，可以分区放大，而不是全部塞在主图上。比如支付链路复杂，可以单独画一张支付依赖明细图，主图上只画一条“网关 → 交易 → 支付服务” 的粗粒度链路。
边界表达也是架构图中容易被忽略的。系统内部和外部的边界要用清晰的包围框或者颜色区分，外部系统统一用灰色调，内部系统用主色调，这样读者一眼就能看清哪些是外部依赖，哪些是自研能力。很多公司画架构图喜欢把所有组件都用同一个蓝色，评审的时候大家对着图找某个外部系统找了半天，就是因为边界不清晰。
3.2 流程图：节点规范与分支处理
流程图是跨领域通用性最强的图种，也是 diagram-design 的入门必修课。流程图的绘制规范，行业里已经有比较成熟的标准，比如菱形表示判断、矩形表示处理、圆角矩形表示起止，但我观察到现在很多团队画流程图不怎么拘泥于这套符号体系了，更常见的是矩形统一表示动作，菱形表示关键判断。这倒没问题，比符号更重要的是分支处理的清晰度。
流程图最容易翻车的地方就是分支过多。一个判断节点分出三个分支，每个分支又有子流程，叠下来整个画布密密麻麻。我的处理方法是拆分子流程：主流程保持主干清晰，每个分支只展示关键动作，如果分支内部还有复杂逻辑，就在主干图上留下一个子流程入口节点，另起一页展开。
还有一个细节是关于循环。循环是流程图中容易画乱的地方，关键是把循环回路的起点和终点明确标出来。我见过不少人画循环，回程箭头飞过半个画布，读者根本不知道这个箭头要回到哪个节点。正确的做法是让回程箭头尽量短，并且指向明确的循环起点节点，必要时在箭头上标注“未满足条件则返回重试”之类的文字说明。
另外，流程图里的节点命名也需要花心思。动作节点的命名建议采用“动词 + 宾语”的格式，比如“发起支付请求”“校验库存数量”“更新订单状态”，而不是干巴巴地写“支付”“校验”“更新”。动词开头让动作语义更明确，宾语让范围更清楚，读者不用猜这个节点到底做了什么。
3.3 时序图：消息顺序与生命线的表达
时序图是表达系统之间交互细节的最好工具，尤其在接口设计和联调阶段。时序图绘制的核心是消息的先后顺序和消息的语义准确性。
画时序图时，我最重视的是生命线（Lifeline）的起始和结束。一个对象在什么时候创建、什么时候销毁，都应该在图上有所体现，否则读者容易误以为所有对象都是系统启动时就存在的。在工具里通常用 X 标记销毁点，顺手标注一下“该服务实例在此处销毁”之类的说明。
消息之间的嵌套和返回也是时序图中容易乱的。同步消息用实线加实心箭头，异步消息用实线加开放箭头，返回消息用虚线箭头，这是行业标准。问题是很多人返回消息不画箭头方向，导致读者分不清是请求还是响应。还有一个常见的小错误：消息编号不连续，或者编号层级混乱。如果一张时序图消息超过十条，建议用数字前缀标注消息的先后顺序（比如 1.1、1.2、1.3），这样即使布局上有些消息的纵坐标不严格递增，读者也能通过编号理解顺序。
时序图的另一个实用技巧是添加激活条（Activation）：在消息处理期间给生命线画一个细长的矩形，表示这个对象在这段时间内处于活动状态。看起来是个小东西，但激活条能直观表达同步阻塞和异步回调的区别，对理解链路耗时非常有帮助。
3.4 部署图：节点拓扑与依赖关系
部署图的核心是表达物理拓扑：服务跑在哪台机器上、机器之间怎么连通、外部依赖怎么接入。部署图的绘制规范有一个容易被忽视的点：区分“逻辑服务”和“物理节点”。
我见过很多人把服务名写在机器框框里，看起来像部署图，实际上没有表达任何部署信息。正确的做法是：机器节点用粗边框的方框表示，里面再嵌套部署在它上面的服务实例框，服务实例带上端口号和实例数量。这样读者一眼就能看出哪些服务共机部署、哪些服务独立部署、整体资源分配是否合理。
部署图里还应该标注关键的连接方式，比如“通过内网域名访问”“走公网负载均衡”“直连数据库主库”。连接方式的标注很实用，运维排查问题的时候最需要这些信息。用不同的线型和颜色区分内网、公网、数据库连接，可以大幅提升图的可用性。
4. 实操环节：从零到一绘制一套完整的技术图
4.1 工具选型：我用过的几套组合
画 diagram-design，工具是绕不开的话题。我这些年用过不少工具，这里分享一下真实体验。
最常用的免费工具是 draw.io（现在也叫 diagrams.net），它的优点是免费、支持本地文件、格式兼容性好。我最常用它画架构图和流程图，尤其是和代码仓库配套管理图纸的场景，非常适合。因为图纸本身就是 XML 文件，可以直接放在 git 仓库里做版本管理，比很多在线工具的导出图片方式可控得多。
如果画的是时序图，我更推荐代码驱动的方案。PlantUML 是我用了很多年的时序图工具，纯文本语法，用代码描述消息序列，然后生成图片。它最大的好处是时序图可以用 git 做 diff，评审的时候能看出每一版之间消息顺序改了什么。不过 PlantUML 的默认样式比较老气，需要用主题自定义一下配色。
Mermaid 则是更轻量的一种选择，和 Markdown 配合得很天然，我写技术文档的时候喜欢直接内嵌 Mermaid 代码块，这样文档的图可以直接更新和维护。Mermaid 的语法比 PlantUML 简洁，但复杂布局的表现力弱一些，适合画简单流程图和架构分层图。
绘图工具的选型原则其实很简单：你是“以图为主”还是“以码为主”。以图为主，用 draw.io；以码为主，用代码驱动的方式。不要既想要代码维护又想在画布上随手拖拽，两个模式来回切换很别扭，人的思路是连贯的，工具切换会造成语境割裂。
4.2 手把手：用代码驱动的方式画一张架构图
接下来我演示一下用 Mermaid 实现一张典型的三层架构图，画的是模拟项目 X 的交易链路饿架构。先看代码：
flowchart TB subgraph client[客户端层] app[移动端 App] web[Web 前端] end subgraph gateway[接入层] api[API 网关] auth[认证服务] end subgraph core[核心业务层] trade[交易服务] order[订单服务] pay[支付服务] end subgraph data[数据层] mysql[(MySQL 主库)] redis[(Redis 缓存)] mq[消息队列] end app --> api web --> api api --> auth api --> trade trade --> order trade --> pay trade --> mysql order --> mysql pay --> mq pay --> redis这段代码有几个设计点可以说一下。
第一，用subgraph把组件分组，四个子图对应四个层级，视觉上就形成了层次感。每个子图有一个明确的名称，即使不看连线，读者也知道系统的四大块是什么。
第二，箭头统一都是自上而下流动，符合依赖方向的视觉直觉。客户端先进接入层，接入层再进业务层，业务层再访问数据层。这里唯一需要留意的是pay --> redis和pay --> mq这两条线，可能有人会疑惑为什么支付服务直接访问缓存和消息队列，而不是统一走一个基础服务。实际上这取决于系统设计，但在图里可以加一个注释，说明冲正流程和回调通知的细节单独画图，不在这里展开。
第三，我没有把每个服务之间的所有互相调用关系都画出来。比如订单服务可能也调了支付服务的查询接口，交易服务可能直接读缓存，但这些都没画。刻意省略的目的是保持主图的可读性，把主干关系画清楚，次要关系留给文档细讲。
生成出来的图效果一般还需要调整，Mermaid 默认连线的弯曲程度、子图的边距这些可以设置。我通常会在代码块头部加一段配置，比如：
%%{init: {"theme": "default", "flowchart": {"curve": "basis"}}}%%curve: basis会让连线更平滑，避免默认的折线看起来太生硬。颜色方面，如果要区分部署环境和逻辑环境，可以用classDef定义不同的节点样式。
4.3 手把手：画一张严谨的时序图
接下来用 PlantUML 画一张下单场景的时序图，包含用户、网关、订单服务、支付服务和消息队列。
@startuml title 模拟项目 X 下单主链路 actor 用户 as U participant "API 网关" as GW participant "订单服务" as OS participant "支付服务" as PS participant "消息队列" as MQ U -> GW: 提交订单请求 GW -> OS: 转发创建订单指令 activate OS OS -> PS: 请求收银台 activate PS PS --> OS: 返回支付标识 deactivate PS OS --> GW: 返回下单成功 deactivate OS GW --> U: 返回支付跳转链接 U -> PS: 发起支付 activate PS PS -> MQ: 发送支付结果事件 activate MQ MQ --> PS: 确认已接收 deactivate MQ PS --> U: 展示支付结果 deactivate PS MQ -> OS: 通知支付结果 activate OS OS --> MQ: 确认已消费 deactivate OS @enduml这组时序图的细节表达有一些值得注意的地方。
激活条的运用很关键。订单服务收到命令后，激活条开始，处理完返回结果后，激活条结束。这样读者能直观看到每个服务的处理时长。Pay 服务的激活条从用户发起支付开始，到展示支付结果结束，中间和消息队列的交互都发生在激活条内，表达的是同步上下文。
消息名称的语义我做了刻意的处理。“转发创建订单指令，请求收银台，返回支付标识”，这些词不是随手写的。让读者即使不知道系统内部实现，也能从语义上理解每个消息的动作。最后一个消息“通知支付结果”来自 MQ 到订单服务，和前面的“发送支付结果事件”形成了天然的因果关系，读者一看就知道这是异步回调。
还有一个隐藏的细节：用户发起的第二次交互“发起支付”没有经过网关。这在真实系统里可能是前端直连支付服务跳转，也可能是先经网关再跳转。画在这里我选择了直连，为了表现支付环节的特殊性。但如果你画的系统实际是先走网关再进支付服务，图一定要匹配实际链路，画图最忌讳“理想化的链路”，因为别人拿着图去排查问题会走弯路。
4.4 从单张图到成套图：组织关系与一致性
实际项目中很少有单张图解决所有问题的场景，更多时候是一套图配合使用。这时候 diagram-design 的重点就变成了成套图的一致性和导航关系。
我一般在项目的 docs 目录里维护一个diagrams文件夹，习惯的目录结构长这样：
docs/ diagrams/ architecture/ // 架构图 overview.drawio.xml payment-detail.drawio.xml deployment.drawio.xml flows/ // 流程图 order-flow.drawio.xml refund-flow.drawio.xml sequence/ // 时序图 order-create.puml payment-callback.puml这个结构的好处是类型隔离：架构图归架构图，流程图归流程图，时序图归时序图。每次找图的时候直接按目录定位，不用在十几个文件名里猜。文件名也必须讲究，我推荐用“主题-图种”的组合，比如order-create-sequence.puml比new.puml强一百倍，这套习惯相似于代码命名规范，坚持下来收益很大。
成套图的一致性是另一件需要刻意维护的事。同一个组件在不同图里的命名要统一。在架构图里叫trade-service，到了时序图里就不要改叫tradeSvc；颜色风格也尽量统一，主服务一个色，外部依赖一个色，基础设施一个色，定下来后不要各个图各搞一套，读者切换看图的时候会很出戏。维护一致性的一个实用手段是：建立一份图例说明文档，把常用的颜色、线型、术语固定下来，团队内部共用。
5. 实操避坑：常见问题与排查技巧实录
5.1 布局错乱与溢出画布
draw.io 这类拖拽工具最常见的坑就是画布越画越大，组件分布越来越散，后期根本收不拢。我的经验是：每画完一个层级，顺手选中这层的所有组件，执行一次对齐和等距分布。draw.io 的工具栏里有对齐工具，左对齐、水平居中、垂直居中、等距分布，几乎每一个架构图都会用到，不要手动拖着组件慢慢调，既慢又不精确。
布局的另一常见问题是大图导出后文字太小，打印出来根本看不清。遇到必须输出大图的情况，我有两个可选项：第一，拆图。把大图按模块拆成细节图，主图只留导航性的大框，细节图再单独导出。第二，设置画布按照区域划分，导出时按区域裁剪。相比直接缩小整张图，拆图的可读性要可靠得多。
5.2 渲染问题：代码驱动方案的解决思路
用 PlantUML 或者 Mermaid 画图，最烦的就是渲染出来的结果和预期不符。
PlantUML 常见的问题是中文乱码和主题显示异常。中文乱码大概率是编码问题，PlantUML 默认读取文件的编码可能不是 UTF-8，建议在文件开头声明编码格式，或者确保编辑器默认以 UTF-8 保存。主题异常则多半是版本问题，老版本 PlantUML 对新语法兼容性不好，日常使用时尽量保持版本更新。
Mermaid 则容易遇到语法报错，特别是节点 ID 用了特殊字符，比如_或-有时候会被解析成特殊含义。保险的做法是节点 ID 只用字母和数字，显示文本放在[方括号]里，展示内容基本不受影响。
另一个实用排查技巧是：先用在线编辑器跑通语法，再回填到本地。本地环境可能有各种配置问题，而在线编辑器天然自带最新版渲染引擎，能快速判断是语法问题还是环境问题。在线跑通之后再回本地，可以大幅减少排查时间。
5.3 协作与版本管理：图也是代码资产
图和代码一样，属于项目资产，同样需要版本管理。
draw.io 的文件是 XML 格式，天然适合放进 git 做 diff。团队协作时，约定用 draw.io 的源文件提交到仓库，导出的 PNG 只作为文档里的展示用图，一律不入库。这样改图的时候只需要改 XML，评审时看 diff 能知道改了什么字段、动了什么连线，而不是覆盖一张图片后什么也看不出。
PlantUML 和 Mermaid 就更适合版本管理了，因为它们本质是纯文本，甚至可以直接在 code review 里发表评论到某一条消息上。我所在的团队现在的工作流就是：时序图和架构图的源文件都放在仓库里，文档系统构建时自动渲染成图片，全程不手工导出。整个链路是自动化的，省掉了不少重复工作量。
版本管理里有一个我踩过的坑：本地开发时改了图，忘记重新渲染文档里引用的图片，文档线上展示的还是旧图，容易造成信息不一致。后来我改进成 CI 流水线里加一步渲染任务，每一次提交都强制执行渲染，冲突的源头直接被堵住了。
5.4 评审时的常见反驳与处理
图的评审环节，几乎每一次都会有一些固定类型的反馈，提前准备可以省掉不少来回。
第一个常见反馈是“这张图太复杂了，看不懂”。应对的方式是提前分好主图和子图，主图的复杂度控制在“一分钟能讲完主要链路”的范围。如果五分钟还没讲完主图，那它基本就是太复杂了。
第二个常见反馈是“这个箭头是啥意思？这个是实线还是虚线？”。这说明图例缺失或者线型使用不一致。在图的角落放一个小图例，标明实线代表同步调用，虚线代表异步通知，箭头方向代表数据流向，基本可以消除多数歧义提问。
第三个常见反馈是“这里的命名跟代码对不上”。这通常是因为图中用了缩写或者中英文混编。我的习惯是图中的服务名、模块名、数据库名，尽量和实际代码里的命名保持一致，这样读者可以顺着图去代码里定位，而不是还要转换一次命名。
6. 把画图当成设计来做，而不是填空
画图这件事，最难的不是学会工具操作，而是养成设计的思维习惯。工具是腿脚，设计是方向。方向错了，腿脚再快也只是加速跑偏。
我自己画了这么多年图，最大的体会是：一张好的 diagram-design，核心在于信息本身足够清晰，视觉表达只是让清晰的信息呈现得更高效。逻辑混乱的图，不管美化到什么程度，最终都会被读者用脚投票。反过来，只要逻辑足够清晰，哪怕样式朴素一点，读的人也依然能顺畅理解。
最后分享一个小技巧：每次画完图，遮住图里的所有文字标签，只看形状和连线，试着猜一猜这张图大概在表达什么结构。如果只看骨架就能大概猜出分层和流向，那这张图的基本功就稳了。如果连自己都猜不出——不用怀疑，信息组织还需要重新理一遍。这个自检方法我已经用了很久，每次都能发现一些平时忽略掉的歧义点。
