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核心在于信息本身足够清晰视觉表达只是让清晰的信息呈现得更高效。逻辑混乱的图不管美化到什么程度最终都会被读者用脚投票。反过来只要逻辑足够清晰哪怕样式朴素一点读的人也依然能顺畅理解。最后分享一个小技巧每次画完图遮住图里的所有文字标签只看形状和连线试着猜一猜这张图大概在表达什么结构。如果只看骨架就能大概猜出分层和流向那这张图的基本功就稳了。如果连自己都猜不出——不用怀疑信息组织还需要重新理一遍。这个自检方法我已经用了很久每次都能发现一些平时忽略掉的歧义点。 
长河君 · 2026/10/19 5:17:35 · 阅读 1.2k 技术绘图设计全指南：从架构图到时序图的完整实践
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核心在于信息本身足够清晰视觉表达只是让清晰的信息呈现得更高效。逻辑混乱的图不管美化到什么程度最终都会被读者用脚投票。反过来只要逻辑足够清晰哪怕样式朴素一点读的人也依然能顺畅理解。最后分享一个小技巧每次画完图遮住图里的所有文字标签只看形状和连线试着猜一猜这张图大概在表达什么结构。如果只看骨架就能大概猜出分层和流向那这张图的基本功就稳了。如果连自己都猜不出——不用怀疑信息组织还需要重新理一遍。这个自检方法我已经用了很久每次都能发现一些平时忽略掉的歧义点。