diagram-design 这个名字听起来像是个画图工具但它真正解决的不是“怎么把图画得好看”而是“怎么让图不再过期、不再各画各的、不再无法复用”。我做这个项目的初衷很简单团队里的架构图永远比代码落后三个版本每次评审都要让某个人现场对着白板重新讲一遍图本身早就没人信了。所以我把它做成了一套“图解即代码”的工程化方案用声明式文件定义图结构由渲染引擎自动完成布局、样式和输出。这篇文章不聊概念只讲我在设计和落地这套方案时的真实取舍、踩过的坑以及一套可以直接照搬用的实操流程。适合正在做技术文档体系、想统一团队绘图规范、或者被手工画图折磨过的开发者参考。1. 定位拆解为什么“图解即代码”才是核心1.1 手动画图的四个痛点先说结论diagram-design 不是又一个画板工具它把图当成代码来管理。这个定位源自四个真实到不能再真实的痛点。第一是版本漂移。团队里画架构图通常用某种绘图软件画完导出一张 PNG 贴在文档里。代码改了三轮图还是三个月前那张。不是没人想更新而是改图太麻烦——打开文件、拖节点、改箭头、重新导出一套流程走完半小时过去了而代码评审只需十分钟。于是图就成了历史文物只有新人才会去看。第二是风格不统一。有人用土豪金配色有人画框用实线有人用虚线有人把箭头画成直线有人画成斜线。单看任何一张图都能看懂放在一套文档里就成了灾难。尤其是跨团队协作的时候一个系统架构图和一个数据流图摆在一起如果连图形语言都不一致读者根本没法建立统一的认知模型。第三是图是“死”的。手工画出来的图导出成 PNG 之后里面的节点、连线、文字全部变成像素没法检索、没法复用、没法自动校验。你想检查“这张图里有没有孤立的节点”“有没有环形的依赖关系”手动画图只能靠眼睛看图一多就废了。第四是协作困难。传统绘图格式是二进制文件或者某种私有格式多人编辑基本靠“谁改完谁另存一份”。想对着一张图画 review 意见做不到。想知道这张图上个版本长什么样只能凭记忆。这四个痛点指向同一个本质图也是一种需要版本管理、diff、评审和自动化的资产而手动画图让图成了游离在工程体系之外的一次性产物。于是我把图的设计过程“代码化”让图成为仓库里的一份文本文件。1.2 方案选型为什么用声明式 DSL 而不是拖拽画板选型时我考虑过三条路直接用现成画板、封装一个拖拽式编辑器、用声明式文件驱动渲染。现成画板的问题很明显它们解决不了版本管理也没法自动化。拖拽式编辑器体验确实好但开发成本极高而且本质上还是把图当成“画出来”的东西不是“描述出来”的东西。我最后选了声明式 DSL用户只描述图里有哪些节点、哪些连线、节点属于哪个分组至于节点摆在哪、线怎么绕、颜色怎么统一全部交给引擎。声明式的优势是结构完全可解析。有了结构我们就能在渲染之前做校验比如检查是否存在未连接的节点、边是否引用了不存在的节点、有没有重复的 ID。有了结构我们就可以在渲染之后做 diff图变成文本就能用 Git 来管理review 时看到的不再是“这里颜色变了”而是具体某条边加了 label、某个节点换了分组。说白了拖拽画板把图当成“画布上的像素”声明式方案把图当成“内存里的对象”。后者才是工程化该有的姿态。1.3 这个方案能做什么、不能做什么必须清醒地说一下边界。diagram-design 擅长的是结构化程度高的图系统架构图、流程图、时序关系图、部署拓扑图、领域模型图。这些图有一个共同特点——内容的核心是节点和它们之间的关系而不是视觉表现。图要传达的语义本质上存在于那张可解析的结构里而不是某个节点的阴影效果。它不擅长的是纯美术向的信息图、需要大量自由创意的海报式图解、强交互的白板协作场景。真要画那种天马行空的概念图你需要的还是手和笔甚至是一块白板。把工具用在对的地方方案才有价值。我见过很多人一上来就要求图能媲美专业设计师的手工图这是目标错位。自动布局引擎要的是稳定、清晰、可复现而不是每一次渲染都给你一个惊喜。2. 核心细节拆解diagram-design 的四层设计2.1 图模型节点、端口、连线和分组图模型是整个方案的基石。我设计时只保留了四个核心元素节点node、端口port、边edge和分组group。节点是最基本的实体可以有 id、label、type 等属性。端口是节点上的锚点决定边从节点的哪个位置连入或连出。这个设计很容易被忽略但实际价值非常大。没有端口概念的图边会直接从节点中心连到节点中心导致线穿节点、方向混乱。有了端口比如一个“数据库节点”只有顶部和底部两个端口那连线就只会从上下两侧进出视觉上瞬间干净很多。边是关系的载体必须完整地记录 from、to、label 和方向。这里有一个关键设计边永远不允许脱离节点而存在。我在解析阶段会做严格校验任何指向未知节点的边都会直接报错。这个约束保证了图的语义完整性也让后续的布局算法可以放心地遍历图结构。分组是表达层次的手段。一组节点可以归属于某个分组渲染时分组会变成一个带标题的背景框。这个框不是装饰它参与布局计算分组内的节点会被视为一个整体来安排位置避免出现“分组框一个在东、组内节点一个在西”的尴尬情况。这四层模型覆盖了绝大多数场景。我维护这个项目这么久很少遇到需要用第五种元素才能表达的图。2.2 自动布局一次性实现受益终身布局是 diagram-design 里面最值得投入的部分因为它直接决定了图的可读性。手工画图之所以贵贵在每张图都要人工调整位置。自动布局做得好这一步就省掉了。我采用的方案是组合式的先用分层布局layered layout处理大部分架构图和流程图再针对关系型的图提供力导向布局force-directed layout作为备选。分层布局的核心思想是把节点按拓扑顺序分配到不同的层。比如一个请求从“客户端”流向“网关”再流向“服务”这三个节点就会被放在从左到右的三个层级上。分层之后同一层内的节点在垂直方向上对齐层与层之间在水平方向上排列整个图呈现出一种从输入到输出的流动感非常契合“架构图”的阅读习惯。但分层布局有个绕不开的问题边会交叉。当层内节点顺序不合理或者连线跨越多个层级时交叉几乎无法完全避免。我在这里做了两个优化。第一个优化是层内排序算法尽量把有语义关联的节点放在相邻位置减少交叉。第二个是正交绕障路由边不走斜线而是按照横平竖直的方式绕开矩形节点。这样即使交叉无法完全消除视觉上也远比斜线穿来穿去清晰。力导向布局则是另一套逻辑模拟物理世界里的弹簧和斥力让节点互相推开、有边的节点互相拉近迭代若干轮后达到一个相对稳定的位置。适合关系网络、知识图谱这类没有明确流向的图。布局参数我建议暴露出来但必须有合理的默认值。比如节点宽度 160、高度 40、层间距 60、同层间距 24。这些数值不是拍脑袋定的它们来自大量的实际渲染测试间距太小图会挤成一团间距太大图会横向拉得特别宽导出到文档里反而看不清。2.3 主题系统用“变量”代替“调色盘”团队协作场景里图的风格不统一本质上是缺少一个统一的主题变量体系。diagram-design 里的主题系统参考了前端领域的设计令牌Design Token思路不直接写颜色值而是定义一组语义化的变量然后在渲染时去解析这套变量。我把主题拆成了几个维度节点样式、边样式、字体排版、分组样式、画布背景。每个维度都对应一组 token比如--color-node-bg控制节点背景色--color-edge控制连线颜色--font-family控制字体。不同团队只要切换一套主题文件整批图的观感就完全一致。这套设计最大的好处是“改主题不改图结构”。业务上新加一个节点你不需要关心颜色对不对团队品牌色换了你也不需要打开每张图去调色。结构是内容主题是表现两者彻底分离。这也是“图解即代码”的另一个含义连视觉风格都可以纳入版本管理。2.4 渲染管线布局、注入、导出的先后顺序渲染管线我踩过不少坑最终稳定下来的流程分三步先布局、再注入样式、最后导出。布局阶段只负责计算每个节点和每条连线的几何位置完全不关心颜色和字体。这个阶段得到的是纯坐标数据。第二步样式注入把主题系统里的 token 解析成具体的 SVG 属性比如颜色、线宽、圆角、阴影。第三步渲染输出生成最终的 SVG 内容再根据用户需要转换成 PNG、PDF 或者嵌入 HTML 的代码片段。顺序为什么重要如果把样式注入放在布局之前样式里的字体宽度会影响文字占位进而影响节点尺寸节点尺寸变了布局又要重新算。所以必须先用一套稳定的默认尺寸完成布局再在渲染阶段根据字体信息调整内部文字位置。这个顺序一旦搞反你会发现同样的图在不同机器上渲染出的布局不同因为字体不同导致文字宽度不同文字宽度不同导致节点大小不同节点大小不同导致布局彻底乱套。SVG 是核心的中间格式它无限缩放、可被文本解析、能被嵌入网页还能作为生成 PNG 的源。PNG 导出不是简单地把 SVG 像素化而是按目标 DPI 重新计算输出尺寸。默认 96 DPI 用于屏幕阅读文档印刷至少 300 DPI。很多人导出图片模糊不是清晰度的问题是导出逻辑里没用 DPI 而是用固定缩放比例这个细节我会在后面的常见问题里继续讲。3. 实操全流程从建模到输出一张架构图3.1 定义图模型先写“事实”再谈“样式”我用一个订单服务架构的案例来走完整流程。这是一张典型的微服务架构图客户端通过 API 网关访问订单服务订单服务依赖认证服务、数据库和消息队列。按照 diagram-design 的 DSL第一步是创建图定义文件。以一份 YAML 文件为例diagram: id: order-service-arch title: 订单服务架构 nodes: - id: client label: 客户端 group: outer - id: gateway label: API 网关 group: infra - id: auth label: 认证中心 group: infra - id: order label: 订单服务 group: app - id: db label: 订单数据库 group: data - id: mq label: 消息队列 group: infra groups: - id: outer label: 调用方 - id: infra label: 基础设施层 - id: app label: 应用服务层 - id: data label: 数据存储层 edges: - from: client to: gateway label: HTTP - from: gateway to: auth label: 鉴权 - from: gateway to: order label: 转发 - from: order to: db label: 读写 - from: order to: mq label: 发送事件写这个文件的时候脑子里只有一个原则只描述事实不描述位置。谁是谁的下游、谁依赖谁这些是事实某个节点画在左上角还是右下角这是表现层的事布局引擎会去处理。在写节点时要注意 id 的命名纪律。用语义化的短横线风格不能用中文不能有空格因为边是靠 id 来引用的。一旦图中的边多起来id 乱写就是给自己挖坑。我自己吃过这个亏某张图里有三十几个节点id 用过 client、client-1、client_new 这种乱七八糟的命名后来要加一条边根本分不清该指向哪个。3.2 配置布局与样式让图自己长出来图定义文件只描述内容下一层是布局参数和主题配置。这一步可以放在同一个工程目录下分开写之后的自动化能力全靠这个分离。布局配置我建议基于默认值做微调。还是以上面那张架构图为例默认的分层布局已经能把它排得不错但我通常会做三处调整把层间距从默认的 60 调大到 80给边的 label 留出空间。把组与组之间的边距调大到 30避免分组框边框和内部节点贴得太近。给auth节点单独设置一个固定层级让它不要和order出现在同一列因为从语义上讲它是旁路依赖不是主链路。这些参数怎么压到文件里在我们的配置模型里非常简单直接layout: type: layered direction: LR nodeWidth: 160 nodeHeight: 40 levelGap: 80 nodeGap: 24 groupGap: 30 style: theme: default fontScale: 1.0 watermark: 其中direction: LR的意思是从左到右布局。如果改成TB图会变成自上而下这是很多流程图的阅读习惯。选择哪一侧取决于读者习惯架构图我一般用 LR流程图用 TB没有绝对标准但必须全团队统一。样式这块我用一个主题文件来控制:root { --color-node-bg: #f8fafc; --color-node-border: #134e4a; --color-node-text: #1e293b; --color-group-bg: rgba(15, 118, 110, 0.06); --color-edge: #64748b; --color-edge-active: #0f766e; --font-family: Noto Sans SC, PingFang SC, sans-serif; }这里有几个经验。底色不要用纯白稍微带一点灰能减少长时间阅读的疲劳感。节点边框颜色要比正文文字颜色深一个色阶否则节点轮廓会淹没在连线里。分组背景用极淡的浅色透明度控制在 6% 左右重点是区分区域而不是抢眼。字体必须指定中文字体并且把它放在最前面否则导出 PNG 时中文大概率会变成方块。3.3 核心命令渲染与导出完成了图定义和配置第三步就是一条命令渲染出图。我习惯把渲染和导出拆成两个动作因为调试阶段要频繁看图没必要每次都导出高分辨率 PNG。# 预览渲染生成 SVG diagram build ./arch.yaml --layout ./layout.yaml --theme ./theme.css -o ./dist/arch.svg # 导出 PNG指定 300 DPI 用于印刷级文档 diagram export ./dist/arch.svg --format png --dpi 300 -o ./dist/arch.png # 导出 PDF适合放入离线手册 diagram export ./dist/arch.svg --format pdf -o ./dist/arch.pdf预览阶段重点检查四件事节点有没有超出画布边界、分组框有没有正确包住所有子节点、边的 label 有没有压到其他节点上、箭头方向是否符合语义。我见过太多人跳过预览直接导出 PNG结果图里文字互相遮挡最后又回来调布局。这个 debug 流程省不掉。如果发现节点重叠优先调大nodeGap。如果发现边交叉严重先看节点层级是否分配合理再调levelGap。如果发现整体图太宽可以考虑把布局方向切成TB这种垂直方向的图在文档页面里往往更友好。调参数不能凭感觉一次性堆很多每次改一个变量、渲染一次看效果这样你能清楚知道是哪个参数在起作用。3.4 与文档工作流整合图不再是“一次性产物”渲染出图只是第一步真正让这套方案发挥价值的是把 DSL 文件挂进文档构建流程。我把diagram build命令集成到了文档站点的构建脚本里每次文档更新图都会重新生成。集成的方式很简单在构建配置里加一个前置步骤先执行所有图的 build 命令再执行文档站点构建。这样图永远和文档里的其他内容同步生成。内容的修改入口变成了文本文件谁都可以通过提交一个 PR 来更新图里的节点关系而不是求着某个人帮忙改图。实际运行中我还往流程里加了一个校验步骤构建时自动检查有没有节点孤立、有没有边引用不存在的 id、有没有重复 id。这些都通过以后才允许构建继续。这么做的效果非常明显——曾经在一张几十个节点的大图里因为复制粘贴漏改了一个 id导致一条边指向了不存在的节点如果不是自动校验在构建阶段就拦住这张图会以“缺一条边”的状态发布出去而肉眼极难发现。4. 常见问题与排查技巧实录4.1 五大高频问题速查表这套方案实际跑起来以后我遇到最多的问题集中在字体、交叉、性能、协作和清晰度五个方向。整理成一张表方便大家直接对照排查。现象原因处理方式导出 PNG 中文变成方块渲染环境缺少中文字体在主题文件里显式声明中文字体并在操作系统中安装对应字体节点互相重叠间距参数过小调大nodeGap和levelGap每次只改一个参数边交叉严重分层顺序不合理检查是否有跨多层的长边给关键节点手动指定层级大图渲染卡顿节点数量过多一次性布局拆分子图或者启用分层懒渲染导出图片模糊使用了固定缩放而非 DPI导出参数改用--dpi 3004.2 中文字体变方块最隐蔽的环境杀手这个问题我要单独拿出来讲因为它在本地永远复现不了一到 CI 上就炸。本地开发机装了微软雅黑、苹方等字体图渲染出来一切正常。到了 CI 服务器上那是一个精简的 Linux 运行环境系统里只装了默认字体一渲染中文全部变成方块。而且这个错误不是直接报错只是默默输出一张难看的图构建流程还会继续走下去直到有人打开文档发现图毁了。排查方法很朴素在 CI 服务器上执行字体列表命令确认中文字体是否存在。解决方案有两种。一种是在 CI 环境里安装一个开源中文字体比如 Noto Sans CJK并把主题文件的--font-family里把这个字体放在第一位。另一种是把字体文件带到工程目录里运行时动态注册到渲染引擎不依赖系统安装。我推荐后一种因为团队里有人用 macOS有人用 Windows还有人用 Linux让每个人自己装字体迟早出问题。还有个细节SVG 里如果没有显式指定字体浏览器打开时会用本地的默认字体这通常没问题。但同样的 SVG 拿去转 PNG转图片的工具用的却是自己的字体环境所以一定要在主题文件里写清楚字体名不能依赖“系统默认”。4.3 大型图的性能治理分块、分层与懒渲染节点数一多任何自动布局方案都会变慢。我遇到过一个极端案例某张图有两百多个节点、三百多条边第一次渲染耗时接近半分钟而且布局结果非常乱因为全局布局算法要反复迭代才能稳定下来。这个问题的处理思路和前端性能优化很像分层。不要试图把两百个节点塞进一张图。把图按子系统拆成多张子图每张子图控制在四十个节点以内然后在总览图里用“聚合节点”代表每个子系统。子图之间通过聚合节点上的端口表达关系这样既保持了整体结构的可读性也把布局计算量降下来了。如果某些场景确实需要完整大图那就要用懒渲染的思路先只渲染当前视口内的节点拖动画布时再动态挂载新节点。但说实话这种做法对文档场景意义不大文档里的大图终究是要被整体查看的块化组织才是正解。4.4 协作冲突让图像代码一样可 review把图定义文件纳入 Git 之后冲突问题就来了。尤其是多人同时编辑同一个 DSL 文件如果节点 id 的命名规则不统一Git 合并时冲突会非常难解。我的经验是把图定义文件按模块拆分成多个小文件然后用 include 机制组合。比如订单模块一个文件、用户模块一个文件、支付模块一个文件这样两拨人同时改不同模块的图各自改自己的文件根本不会冲突。只有在跨模块加连线时才需要动到组合文件那个操作频率低、冲突概率小真要 conflict 也容易人工合并。这种体验其实很神奇传统绘图工具里“协作”意味着同一张画布上互相抢占元素而 diagram-design 里的协作回归到了工程对照和 code review我提交一条边你修改一个分组名称我们都能在 diff 里看到彼此改了哪里。图的质量在评审环节就被把关了而不是等发布之后被读者吐槽。最后再分享一个有价值的实操心得如果你只打算从这篇分享里带走一个经验我希望是这一点图的“设计”与图的“绘制”必须分离。我见过很多人花大量时间优化绘图工具的画布交互但真正让图长期保持正确和清晰的反而是模型定义和校验规则。把图的语义结构变成文本把视觉表现变成主题变量把布局交给算法把风格交给规则图才能真正融入工程体系。我自己在这套方案上最大的收益不是“作图变快了”而是“图终于敢被认真阅读了”。因为它不是某个人某天心血来潮画出来的临时产物而是一份经过校验、经过评审、和代码同步演进的结构化资产。如果你也在被团队里那些永远过期的架构图困扰可以试试这个思路先别急着找更强大的画图工具先把你最需要更新的那张图改写成一份文本描述让引擎替你完成剩下的工作。
