diagram-design 这个名字我第一次看到的时候第一反应是“这不就是画图嘛”但真在项目里跑过几轮之后才发现它远不是“画图”两个字能概括的。做架构设计、写技术方案、出产品原型说明甚至平时做汇报PPT只要涉及梳理关系、描述流程、展示层级背后都需要一套系统的图表设计能力。这篇内容我不打算只讲某个具体工具怎么点按钮而是想从“diagram-design”这件事本身出发聊聊图表设计背后的思路、工具选型、实操步骤以及我踩过的坑和总结出来的方法希望对正在做技术文档、方案设计或者想提升图表表达力的朋友有实际帮助。1. 先想清楚图表设计的本质是什么到底在解决什么问题很多人在做图表设计时第一反应是打开工具、拖几个框、连几条线然后就开始调颜色结果往往画到一半发现结构不对、信息层级混乱最后推倒重来。所以我在动手画任何图之前都会先强迫自己回答一个问题这张图到底要解决什么沟通问题。1.1 一个图表设计需求背后到底在表达什么图表设计diagram-design的本质不是把文字变成图形而是把复杂的信息关系用视觉语言重新组织一遍。我举个例子。你在技术方案里写一大段文字描述系统调用流程读者得逐字读、反复对照上下文才能在脑子里拼出调用关系但如果换成一张时序图箭头方向、调用顺序、返回结果一目了然沟通成本瞬间降下来了。所以做图表设计首先要定义清楚的是信息关系类型。是讲流程先后是讲模块归属是讲数据流向还是讲时间线上的状态变化图表的类型本质上是由要表达的关系决定的不是由“哪个好看”决定的。我把常见的图表信息关系归纳成三类结构关系强调层级、归属、组成典型如组织架构图、系统模块图、目录结构图。流程关系强调先后顺序、条件分支、循环流转典型如业务流程图、状态机图、时序图。关联关系强调节点之间的依赖、通信、映射典型如网络拓扑图、依赖关系图、ER图。搞清楚这一点之后图表设计的方向就清晰了。结构关系重在“层次清楚”流程关系重在“顺序明确”关联关系重在“链路直观”。不同的表达目标直接决定了你后面所有的布局、连线、配色和标注方式。1.2 图表设计的三条基本原则准确、简洁、可维护我做了这么多年图表相关的工作发现好图表都是有共性的我总结为三条基本原则准确、简洁、可维护。准确是第一位的。图里的每个节点、每条连线、每个箭头方向都必须和真实逻辑完全一致。图表最大的杀伤力不是“丑”而是“看起来说得通实际上容易误导”。一个错误的箭头方向可能让读图的人对整个系统的理解产生偏差。简洁意味着“能少画一个框就少画一个框”。很多人在做图表设计时恨不得把所有细节都塞进去结果主次不分读图的人根本不知道先看哪里。真正好的设计是克制设计把核心链路突出次要细节折叠到附录或作为备注说明。可维护这一点很多人容易忽略。图表不是一次性交付物后期会有大量的需求变更和逻辑调整。如果图表设计从一开始就没有考虑“如何方便地修改”那么半年后你去更新这张图花费的时间可能比重画一张还长。可维护性最直接的体现就是你画图时所采用的“载体”。这里多说一句如果你用的是一张静态图片在维护架构图每次修改都得用画图软件重新编辑再导出上传时间久了必然版本混乱、没人愿改。这条我后面在“工具选型”和“文档化”部分还会展开讲。2. 工具选型思路不同场景下怎么挑顺手的“画笔”工具是图表设计绕不开的一环。我不推荐“一招鲜吃遍天”的做法因为不同场景对工具的需求完全不一样。选错工具往往是图表项目痛苦的开始。2.1 图形化拖拽工具diagrams.net 这类方案的优势与局限先说说图形化拖拽工具代表就是 diagrams.net也就是原来的 draw.io、Visio、ProcessOn、Excalidraw 这一类。这类工具最大的好处是上手门槛低所见即所得鼠标拖拖拽拽就能画出一张图适合快速画草稿、画一次性流程图也适合处理结构比较复杂的图形化编排。比如画网络拓扑图需要摆放很多设备图标图形化工具直接提供素材库拖进来就能用效率确实高。但是图形化工具在“可维护性”上天然吃亏。举个例子你用拖拽工具画了一张系统架构图画完导出 PNG 放到文档里。过了三个月系统加了一个组件你需要更新这张图这时候你得找到原始工程文件如果没有保存或者文件被团队成员改过版那就麻烦了。即便你找到了文件每次更新还得手动调整布局、对齐、重新导出这些重复劳动成本累积下来非常可观。所以我的建议是图形化工具适合画“一次性交付”的图或者作为快速探索想法的草稿工具但不适合作为长期维护的核心文档配图方案。2.2 文本化图表语言Mermaid、PlantUML、Graphviz 等方案的取舍文本化图表语言就是用代码来描述图表结构然后通过引擎渲染成图。常见的有 Mermaid、PlantUML、Graphviz还有这两年比较火的 D2 和 Structurizr 这类更偏架构领域的 DSL。这类方案最大的核心优势就是“图表即代码”这句话说起来简单但价值极大。用代码描述图表意味着图表可以进 Git 仓库做版本管理。每次修改都有 diff谁改了什么、为什么改全部可追溯。团队里任何一个人拉下代码都能用同样的文本文件渲染出完全一致的图表再也不会出现“你电脑上打开没问题我电脑上全是乱码”这种尴尬。Mermaid 我的使用率是最高的。它的语法足够简单基本 10 分钟就能上手。举个例子你想画一个简单的流程图代码是这样的graph TD A[接收请求] -- B{参数校验} B --|通过| C[调用业务逻辑] B --|失败| D[返回错误] C -- E[返回结果]这段文本渲染出来就是一张标准的流程图。最关键的是你可以直接把它内嵌到 Markdown 文档里很多文档平台原生支持 Mermaid 渲染文档和图表天然融合维护成本非常低。PlantUML 在 UML 图的绘制上非常成熟时序图和用例图的支持尤其好。如果你需要画比较规范的 UML 图PlantUML 比 Mermaid 更合适。Graphviz 则擅长处理复杂的图结构尤其是节点多、关系密的图它通过算法自动排布布局虽然上手曲线平缓但遇到大规模图表它的自动布局能力能帮你省掉大量手工调整的时间。2.3 我的选型建议按团队和项目阶段来定工具选型没有标准答案但我可以根据自己的实践经验给出一个比较稳妥的判断逻辑。如果你只是自己画一张快速草图、流程图用来和同事沟通想法那么完全可以打开 Excalidraw 或者 diagrams.net 快速画一张不用考虑可维护性。如果你要写技术方案、架构设计文档这些文档需要长期维护、多人协作那强烈建议使用文本化方案Mermaid 是性价比最高的起点。如果你的团队对 UML 有硬性要求并且有标准化建模流程那 PlantUML 会更容易和流程融合。如果你要画的图规模很大节点上百个那么 Graphviz 这类自动布局工具更合适手工拖拽布局在这种规模下会画到崩溃。总结一下就是优先级从“一次性沟通”到“长期维护”不断变化工具也从“图形化拖拽”向“文本化描述”迁移。一句话越是要长期维护的图越值得用文本化描述。这个经验在我自己的项目里反复得到验证。3. 实操过程从需求到成品的完整图表设计步骤说了这么多理念接下来进入实操环节。我拿一个最常见的场景来举例给一个微服务系统画一张架构图。这个过程中我会完整展示从拿到需求到最后渲染成图的每一步包括我怎么思考、怎么设计、怎么避坑。3.1 第一步明确图表的使用场景与受众很多人画图失败不是因为工具不熟而是因为一开始就没想清楚“给谁看”。同一套微服务架构给技术团队看的图和给老板看的图设计逻辑完全不同。给技术团队看要突出服务之间的调用关系、数据存储、中间件依赖信息可以密一点专业术语直接用给老板汇报看要突出业务闭环、系统边界、核心价值技术细节要弱化甚至可以用业务模块的方框去概括底层服务。我在实际执行中会先问自己三个问题这张图的读者是谁是研发、测试、运维还是产品、管理层读者需要从图中重点获得什么信息是排查问题时看依赖关系还是评审方案时看模块划分我期望读者看完图后采取什么行动是确认方案、还是定位故障这三个问题想清楚了图表的内容取舍、抽象层级、信息密度就基本确定了。3.2 第二步梳理信息层级确定图表的“主骨架”明确了受众之后下一步是梳理信息层级。这一步我强烈建议不要直接在工具里画而是在纸上或者思维导图里先列出所有参与元素然后分层。拿微服务架构图来说我一般会分成这么几层接入层Nginx、API Gateway、负载均衡器应用层各个微服务比如用户服务、订单服务、支付服务数据层MySQL、Redis、MQ、ES 等基础设施层K8s 集群、日志采集、监控系统分好层之后图表的“主骨架”就出来了。主骨架在视觉上的表现通常是一张图里最显眼的横排或竖排分区读者第一眼看到的就是这张图的整体结构。所以这一步的关键不是画得好看而是“元素归类”是否合理。我在给团队 review 架构图草稿时最常见的问题就是元素归类混乱比如把 Redis 和微服务放在同一个视觉层级上读者就会误以为它们是“并列”的关系。要尽量避免这种误导。3.3 第三步布局与连线细节图表好读的关键骨架确定后进入最耗时也最体现功力的环节布局与连线。布局上我有几个实操原则方向统一主流程方向要一致要么自上而下要么从左到右不要一会儿从上往下、一会儿从下往上读图的人会很晕。边界清晰不同的层级用不同颜色的区块背景区分或者用虚线框圈起来让读者一眼就能看出系统边界。减少交叉连线交叉不可避免但能避免就尽量避免。我常用的办法是调整节点位置的顺序让有连线的节点尽量靠近同时避免连线穿过无关节点。连线上有几个细节需要特别留意箭头方向必须准确指向数据流向或调用方向不要含混。必要的地方要加连线标注例如“HTTP 调用”“异步消息”“数据库读写”这些文字信息能极大降低读者的理解成本。避免连线直接穿过文字如果确实避不开可以通过调整节点位置或增加连线拐点来规避。如果你用的是 Mermaid 这类文本化方案布局不是手动控制的而是渲染引擎算法自动计算的。这时候也有技巧Mermaid 支持通过定义节点的相对位置来影响布局比如把同一层的节点放在同一组或者用 subgraph 明确边界引导渲染器生成更合理的结构。看一段实际的 Mermaid 示例我设计一个简化的架构图描述graph TB subgraph 接入层 A[Nginx] B[API Gateway] end subgraph 应用层 C[用户服务] D[订单服务] E[支付服务] end subgraph 数据层 F[(MySQL)] G[(Redis)] H[(MQ)] end A -- B B -- C B -- D B -- E C -- F D -- F D -- G E -- H这段文本渲染出来三个 subgraph 自动形成视觉上的分组层次感非常清楚。这就是文本化方案的好处结构本身就通过 subgraph 写清楚了后续维护时只需要增删节点行即可布局会自适应调整。3.4 第四步配色、字体与标注规范最后一步是视觉规范和标注这决定了一张图“专业感”的上限。配色上我的建议是克制。一张图里主色调最好不超过三种同色系深浅可以用来表达层级对比色只用来强调异常或核心路径。比如我常用“蓝灰色表示正常层级”“橙色或红色表示核心调用链路”“绿色表示新增或变更的内容”这套逻辑在需要频繁更新的架构图上很实用——每次变更review 的人一眼就能找到改动点。字体上中文环境优先选择无衬线字体例如微软雅黑、思源黑体字号上标题可以 14~16px正文 12px 左右注释文字 10~11px。如果用 Mermaid可以在配置里统一设置主题字体这样所有图保持一致风格。标注规范包括统一图例、统一缩写、统一命名风格。图里出现缩写时在图的左下角或备注里给出全称。命名风格一致比如所有模块都用“名词短语”所有动作都用“动词短语”不要混用否则读图的人会在心里反复纠结是不是同一个概念。这里还要提一个很多人忽略的点图表里的文字要按“标题、正文、注释”三级来控制信息密度。主标题说明这张图是什么正文节点名称简洁准确注释区补充必要的说明条件或说明索引。很多图之所以看着累就是因为没有文字层级所有信息一个字号密度堆在那里读者根本找不到重点。4. 图表融入到文档体系版本管理、自动生成与团队协作图表设计做得好不只是单张图画得漂亮更关键的是它能不能顺畅地融进整个文档体系和协作流程里。这一节我重点讲讲“图表即代码”在团队协作中的实战价值以及围绕它建立起来的一整套工作流。4.1 文本化图表的核心优势diff 友好传统图表协作最大的痛点就是没法做有效的 diff。你说你改了架构图别人根本不知道你改了哪里只能打开两张图片反复对比效率极低。换成文本化方案之后这个痛点直接消失了。Mermaid 源码就是普通文本在 Git 里做代码评审时每次改动能清晰地显示出增删了哪个节点、哪条连线。举个例子我在代码评审里看到这样的 diffgraph TB A[Nginx] -- B[API Gateway] B -- C[用户服务] B -- D[订单服务] B -- E[积分服务] C -- F[(MySQL)]新增了“积分服务”节点和对应连线评审人一眼就看明白变更内容了。这种可追溯、可评审的能力是静态图片完全没法比的。所以如果你们团队的技术文档还在用图片维护架构图我真诚建议往文本化方案迁移。成本很低收益却非常持久。4.2 图表文档化让图表活起来文本化图表的另一个重要价值是它天然可以嵌进 Markdown、GitBook、VuePress、Docusaurus 等文档体系里实现文档与图表的一体化维护。比如我用 MkDocs 维护团队内部的技术文档直接用代码块写 Mermaid构建时自动渲染成图文档拉下来是文本网页打开是漂亮的图形一套内容多种展示形态。更进一步如果项目用的是持续集成我还可以在 CI 里加一步校验确保仓库里的 Mermaid 语法始终是合法的有语法错误就构建失败并阻止合并。这样从机制上就避免了“文档已经烂掉了没人维护”的情况图表也会跟着架构演进持续更新。4.3 团队协作中的图表Review机制最后说团队协作。引入图表即代码之后图表的评审流程可以自然进入常规代码评审的轨道。我建议团队里做这么几件事架构图、流程图的源文件进代码仓库随代码变更一起提交、一起评审。重要图表指定负责人可以是架构师或技术负责人避免多人同时改产生冲突没人整体把关。评审时除了关注图本身的正确性还要关注“图的表达是否符合规范”命名是否统一、层级是否清楚、是否有无关紧要的装饰元素。这套机制跑顺之后图表和代码一样成了有生命、持续演进的项目资产而不是写完就扔的一次性交付物。5. 常见问题与排查技巧实录图表设计过程中实际操作里有一堆文档里不怎么会写、但特别容易踩的坑。我把自己这几年遇到的典型问题整理了一遍做成一个速查表再挑几个有代表性的重点讲讲排查思路。5.1 常见问题速查表问题现象可能原因解决方法中文渲染成乱码或方块工具/渲染引擎默认字体不含中文字形配置字体为系统含中文的字体如微软雅黑、思源黑体图太大导出模糊导出分辨率设置过低优先导出 SVG需要位图时按目标尺寸放大导出Mermaid 渲染报语法错误节点文本里有特殊字符未转义处理节点文本包含特殊字符时用引号包裹文本连线交叉严重、图很乱layout 方向设置不合理节点顺序需要调整尝试改变图的渲染方向或利用 subgraph 强制分组多人改同一份图表源文件冲突频繁缺乏负责人或改动粒度过大细分图表文件指定 owner降低改动冲突范围图表更新后还在用旧图静态图片无法追溯版本迁移到文本化方案配合 CI 校验更新情况5.2 中文字体问题最容易被忽略的“小麻烦”如果你在本地画图表一切正常一放到服务器端渲染或 CI 里构建中文就变成方块了那大概率是字体原因。解决方案分两步。第一步在图表配置里显式指定一个包含中文字形的字体名称比如%%{init: {theme: base, themeVariables: {fontFamily: Microsoft YaHei}}}%% graph TB A[接收请求] -- B[处理响应]第二步如果是在 Docker 或 CI 环境里构建要确保环境里安装了对应的中文字体。比如在 Ubuntu 镜像里需要安装 fonts-noto-cjk 这类中文字体包否则指定了字体名也没用环境里压根没有这个字形文件。这个问题排查起来不难但第一次遇到时确实容易一头雾水毕竟本地渲染和线上结果不一致让人非常费解。5.3 导出图质量差SVG 是架构图的默认选择我见过很多人在文档里贴架构图导出一张 1920 宽的 PNG以为够清晰了结果放到高清屏上或者缩放查看时字还是发虚。这里我的经验是架构图、流程图这类以文字为主要信息的图SVG 是默认选择前提是你用文本化方案导出 SVG 是一件非常顺手的事情。SVG 是矢量格式无论怎么缩放都清晰而且文件体积非常小嵌入网页也不会带来加载负担。如果使用的渲染平台不支持 SVG那至少要按目标展示大小的 2 倍尺寸导出位图保证高清屏下的显示效果。5.4 图结构太复杂怎么办拆分永远比硬塞明智遇到复杂的系统很多人会陷入“一张图想把所有内容都表达出来”的执念结果画出来的图密不透风看着就头大。这种时候我建议的行动是拆分而不是缩小。拆分有两种思路一是按层级拆总览图只画主要模块和核心链路子模块单独画一张详细的架构图用链接把两张视图串起来。二是按关注点拆架构图管静态关系时序图管交互流程状态图管状态流转各司其职。我在做大型项目方案时一般会先画一张“总览图”然后每个重点模块再附一张“模块细节图”两张图通过相同的节点命名相互对应读者从总览图里定位模块再到细节图里看实现。这个做法比把所有内容塞进一张图更能有效传达信息。6. 最后再分享一点实际经验做图表设计这几年我最大的体会是真正难的从来不是工具操作而是想明白这张图要传达什么、给谁看、怎么组织信息结构。工具只是最后的呈现手段。新手容易沉迷在“把图调得好看”这件事上花大量时间调颜色、调阴影、调图标结果核心表达却一塌糊涂。我的建议是先重视逻辑和信息层级把图的结构理顺了视觉规范自然水到渠成。另外如果你们团队还在用截图 图片文件的方式维护架构类图表我真建议先拿一个小项目试试文本化方案用 Mermaid 画一张现有架构图放进文档仓库跑一次评审你很快就能感受到“图表即代码”带来的差异性。这个迁移成本很低但它对文档维护效率和团队协作体验的提升是立竿见影的。希望这篇内容对正在做技术方案、架构文档或者推进图表规范化的朋友有帮助。