在没有做diagram-design之前我的日常里最烦的一件事就是画架构图。文字写了三屏图只有一张但那张图我可能改了六版。传统绘图工具的核心槽点在于存下来的是一堆绝对坐标和随机ID图一旦复杂别说让别人review自己隔一天再打开都晕。所以我决定换一条路子把图表的生成从“拖拽绘制”变成“文本定义自动渲染”。diagram-design就是这么来的。它是一个脚本化的图表设计系统核心能力是接收结构化的文本描述解析成图模型再自动布局与渲染成SVG或Canvas图。能做什么能快速绘制架构图、流程图、依赖关系图、组织架构图可以嵌入文档站或知识库也能在CI里自动生成和维护架构文档配图。适合谁后端文档工具链维护者、前端可视化开发者、知识库建设者以及所有经常需要给团队画系统图但又不想浪费时间拖拽的同学。这篇文章会把我的设计思路、核心实现、实操路径和踩坑记录全都摊开来讲。1. 整体设计聊一聊diagram-design的定位和取舍逻辑1.1 传统绘图工具为什么越用越痛苦先说一个很实际的场景。我之前维护一份系统设计文档里面有张模块依赖图总共二十个节点、三十条连线。用图形化工具画的时候光是把节点摆整齐就花了半小时连线的标签位置更是拖来拖去怎么都不满意。最让人崩溃的是第二天产品经理告诉我某个模块要拆分等于整张图重画。这类工具本质上是“所见即所得”但它保存的是最终画面的坐标快照不是结构描述。坐标快照有几个致命问题第一不可Diff。两个人同时改一张图合并冲突完全没法处理第二不可搜索。我想查“支付模块到底依赖了哪些服务”在画布上靠肉眼找第三不可复用。换一个项目基本要从零画起。diagram-design的出发点就是反着来我把图当作源代码来管理而不是当作画布来管理。所有节点、连线、分组、样式都以结构化文本形式存在想改就改文本想自动生成就拼字符串想审查就发Pull Request。图只是文本渲染后的结果不是事实本身。1.2 diagram-design用什么策略解决图表维护难题直接说结论用一套轻量级的DSL作为图的“源代码”配一个自研的自动布局引擎和双通道渲染器。具体收益有三个。第一是工程化能力。文本格式天然适配版本控制、CI检查和批量生成。团队里任何一个人改了DSL其他人都能在代码评审阶段看到图的变更而不是等着他截图发群里。第二是可编程能力。依赖关系可以从代码里自动解析并拼成DSL文本。比如扫描工程里的import语句自动生成一张模块依赖图。这在传统画布工具里几乎不可能实现但在diagram-design里就是几行字符串拼接。第三是表达与渲染分离。既然源文本独立于渲染器那么同一张源文本可以输出去年风格的静态图片也可以渲染成互动式的网页组件甚至生成给外部团队看的简化版图。主题和样式全部交给渲染层结构定义层保持纯粹。1.3 整体架构分层与每个模块的边界diagram-design从逻辑上拆成五个模块每个模块只管一件事模块职责输入输出DSL解析器把文本解析为语义化的数据模型源文本字符串GraphModel语义校验层检查节点重复、连线悬空、分组冲突GraphModel校验结果与错误定位布局引擎计算每个节点和连线的坐标GraphModelPositionedModel渲染器把坐标模型画到画布上PositionedModelSVG/Canvas画面编辑器适配层对接代码编辑器、双栏预览、自动补全底层模块组合交互工具链这里最关键的边界是GraphModel和PositionedModel的分开。GraphModel只描述“谁连谁、谁属于哪个组”完全不关心坐标布局引擎输出的PositionedModel才包含每个节点的x、y、width、height。这个分离看似多出一次数据转换但实际让整个系统变得非常灵活——组件库可以复用自定义布局可以替换不同渲染器也能共享同一套模型。2. 核心实现从语法解析到渲染器的三层架构2.1 DSL语法设计用最少的关键词表达一张图DSL语法设计是我最早动手的部分。参照常见绘图工具的使用习惯和文档场景的表达习惯我定了四个核心关键词graph声明图属性、节点定义节点、连线定义关系、分组定义逻辑归属。一段典型的DSL长这样graph 订单模块依赖 width: 900 height: 600 主题: 暗色 节点: A: 订单服务 B: 支付网关 C: 库存中心 D: 用户服务 分组: 中台能力: [B, C] 连线: A - B: 发起支付 A - C: 扣减库存 B - D: 查询用户每个节点用“标识符: 显示名称”表达标识符负责引用显示名称负责在图上展示。连线用箭头表达式表达冒号后面是连线标签。分组用列表表达成员归属。这套语法最大的特点是少用户只需要记住五个写法就能覆盖大部分架构图和流程图的表达。解析器我拆成了三层。词法层面按行扫描把每行归类成节点定义、连线定义、属性声明、分组列表在此基础上构建AST再把AST转换为GraphModel并做语义校验。这里最值得提的经验是语义校验不能省很多使用者第一次写DSL会出现引用不存在的节点、分组重复、箭头两边是同一个节点这类问题。校验器会把具体问题定位到某一行并输出友好提示这比渲染时莫名其妙少一条线要好排查得多。2.2 自动布局引擎层级、排序与坐标计算的关键取舍布局引擎是整个diagram-design里算法密度最高也最折磨人的部分。自动布局的本质是把一个抽象的图结构转成一张人眼看起来舒服的平面坐标图。所谓“舒服”其实可以拆解成几个硬指标节点不重叠、连线尽量少交叉、连线尽量短、层次方向一致。我的实现路径分四步走。第一步是分层在有向图里把入度为零的节点放在第一层然后逐步向下推导每个节点所在的层级。可以把分层类比成给公司里各部门排汇报层级没有人汇报的部门经理放最上面下面的普通员工一层层排下去。第二步是同层排序在同一层的节点之间做排序目的是让连线在跨越层之间时尽量竖直向下而不是斜穿整个画布。这步对交叉数影响最大。第三步是坐标分配根据层高、节点宽度、层内间距递推出每个节点的具体坐标。第四步是连线路由确定连线从节点的哪个锚点出去、从哪个锚点进来以及标签的位置。对于树形结构布局会退化成简单的递归排布很好处理。对于有环的图我会先做环检测提示用户确认是否要强制按某个拓扑顺序展示或者把环内的节点特殊标记。个人经验是自动布局不可能让所有图都完美“手微调”必须被设计成一等公民。为了让这张图允许用户微调我在PositionedModel里保留了一个override字段只要用户在DSL里显式给出了某个节点的坐标布局引擎就直接采用不再覆盖。2.3 渲染通道SVG和Canvas怎么选以及主题系统怎么搭渲染层最初只做了SVG通道后来补了Canvas通道原因是节点一多SVG就撑不住了。我的选择标准很简单节点数量在2500以下默认SVG。因为SVG有完整DOM结构事件交互方便而且缩放对文字清晰度无损。节点数量超过2500自动切换Canvas。Canvas走的是绘制即失忆路线没有DOM节点但批量绘制性能远超SVG。两套渲染通道共用同一个布局输出只是绘制指令不同。SVG直接生成节点rect、path、text、markerCanvas则用循环批量调用fillRect、moveTo/lineTo、fillText绘制。主题系统做得比较通用一个theme对象就定义了背景色、节点边框色、文字色、连线色、箭头样式、圆角大小、阴影。DSL里通过主题: 暗色这种声明去引用内置主题也支持用户在运行时传入自定义主题对象。配套做的导出能力也要提一句SVG图可以直接序列化保存PNG导出要先在Canvas上重绘再调用toDataURL完成下载。这里出现过的中文文字基线问题我放到后面避坑部分细说。3. 实操路径手把手跑通diagram-design的最小核心链路3.1 最小可行版本一段文本渲染出一个节点加一条连线我强烈建议任何人做类似项目都从“一条线”开始不要一上来就做主题和布局。diagram-design的第一步只做这样一件事把一段DSL解析成节点画出一个矩形和一条箭头线。核心流程就是一个管道const source 节点: A: 订单服务 B: 支付网关 连线: A - B ; const model parseDSL(source); // 转为 GraphModel const positioned layout(model); // 计算坐标 document.body.innerHTML renderSVG(positioned); // 渲染输出第一步parseDSL的实现逻辑并不复杂逐行读取遇到“节点:”就开始收集节点条目把“标识符: 名称”拆成id和label遇到“连线:”就开始按箭头符号拆分左右两端。第二步layout最简单的版本只需要返回每个节点固定坐标比如A在(20,20)B在(200,80)连线的控制点取两个节点中心点。第三步renderSVG把节点渲染为带文字的矩形把连线渲染为一条line元素和箭头终点。跑通这个最小链路之后再逐步加东西分组支持、多行标签、主题、缩放适配。这样的好处是每一步都有确定的验证点出了问题很容易定位是解析器、布局器还是渲染器的问题。我实际写的时候光是连续线标签在FAQ里就折腾了三天如果一开始就把所有功能铺开根本查不过来。3.2 编辑器侧集成双栏实时预览与增量计算diagram-design不是只能命令行单机使用配套的编辑器体验也是项目的一部分。我做的编辑器非常简单左侧是源代码区域右侧是渲染预览区。左侧输入内容变化后右侧在两三百毫秒内自动更新预览。实现细节上有个重要经验不要每次输入都做全量解析、全量布局、全量渲染。更稳妥的做法是做一个三层防抖机制。第一层是输入防抖监听input事件之后300ms才触发解析第二层是布局节流布局计算如果有上一次的结果可复用尽量复用未修改子图的坐标第三层是渲染分帧把节点数量多的图分批绘制避免一帧内完成全部绘制导致界面卡死。同时还要把错误信息展示在编辑器里而不是仅仅日志输出。解析失败时保留上一次成功渲染的画面并在左侧代码区用波浪线标出错误行。这个交互习惯来自我自己的体验一改代码就闪成空白页面那种挫败感是灾难性的。3.3 可扩展能力自定义节点、导出PNG与嵌入文档站一个工具类项目如果只能画固定几种矩形和圆很快就会撞天花板。diagram-design提供了节点类型注册机制使用者可以自定义一种新节点并绑定专属渲染函数。注册方式类似design.registerNodeType(database, { render(ctx, node) { // 圆柱体绘制逻辑 ctx.fillRect(node.x, node.y, node.width, node.height); ctx.ellipse(node.x node.width / 2, node.y, node.width / 2, 8, 0, Math.PI * 2); } });注册之后DSL里就可以写A#database: 用户数据库渲染器会自动按注册的类型来画。这个扩展机制把diagram-design从一个固定图表工具变成了一个可以定制视觉语言的设计系统。图片导出这边我做了三个入口界面上的导出按钮、调用API的编程式导出、以及命令行工具导出。命令行导出主要用于CI场景比如文档站构建时自动重新生成所有架构图。文档站嵌入则提供两种方式静态模式预渲染成SVG字符串服务端注入动态模式在浏览器加载DSL源码再实时渲染。博客和静态文档我建议用前者交互式知识库用后者。4. 避坑记录常见问题排查与性能优化实录4.1 排查图表渲染问题的速查表做diagram-design的过程中我攒了不少问题多数问题不是出在语法解析而是出在坐标计算和渲染交互上。把最典型的一批问题整理成速查表现象根本原因解决办法节点相互重叠图结构里存在孤立节点布局算法没有把它们纳入层级布局前先对所有节点做拓扑分组孤立节点单独成列放置连线穿过了无关节点连线路由使用了直线模型没有避障升级为正交路由让连线先竖向下移再横穿层级间走间隙中文标签在导出PNG时错位文字宽度按英文字符估算中文字符宽度不同统一用canvas measureText方法测量实际文本宽度用于计算节点尺寸浏览器缩放后图错位SVG坐标系统和DOM事件坐标混用所有坐标统一走viewBox相对坐标系事件坐标反向映射到viewBox空间大图拖动卡顿SVG节点过多导致DOM更新频繁超过阈值自动切换到Canvas渲染通道解析错误提示不够直观词法错误没有定位到行列解析器为每个token记录行号和列号错误对象统一带loc属性这些坑里最容易被新手低估的是中文字体宽度问题。所有需要自适应宽度的图形节点都不能用“字符串长度乘系数”这种粗暴方式估算必须用Canvas的measureText做精准测量。我在第一个版本里就吃了这个大亏所有英文图都正常一旦有中文节点文字就会溢出边框。4.2 千级节点图表卡顿的调优实录有一次我用diagram-design渲染一个系统全链路依赖图节点数量到了三千。那个版本默认走SVG结果页面直接卡到没法滚动。我的调优过程按下面几步推进。第一步是定位瓶颈。用浏览器性能面板记录渲染过程发现大部分时间耗在创建SVG元素节点上——三千个rect、三千个text、两千条path光创建DOM就得花好几秒。于是把渲染通道切到Canvas一次性绘制全部图形绘制耗时从秒级降到几十毫秒。第二步是解决交互反馈。Canvas模式下鼠标悬停和高亮需要自己做命中测试我实现了简单的空间网格索引把画布分成若干区域鼠标移动时只需要检测鼠标所在区域内的节点不用遍历全部节点。第三步是布局计算的卡顿。三千个节点的分层排序在主线程跑要一两百毫秒而且每次文本改动都要重新算。我把它挪进Web Worker主线程只负责接收计算结果再绘制。用户感受就是从“每次输入都卡一下”变成“输入完稍等片刻看到图形平滑更新”。调优完成后我把自动切换阈值定在2500节点。这个数字不是拍脑袋是在中低端笔记本上实测过SVG和Canvas各自流畅分界的经验值。4.3 从使用者反馈中总结的迭代心法diagram-design有一段时间只在我自己电脑上跑后来给团队里几个后端同事试用收获了不少意料之外的反馈。第一位同事说“语法记不住每次都要回来翻示例。”于是我加了语法提示。方式很简单编辑器拿到AST里的可插入位置弹出一个候选关键词列表例如在节点列表末尾提示“新节点写法: id: 名称”。第二位同事说“有些图自动布局已经很好了但我就是想微调一个节点的位置。”这个需求催生了“覆盖坐标”功能用户在预览图上直接拖拽这个节点系统自动把偏移量换算成DSL里的坐标属性写回。第三位同事说“想把这个图放进给客户的PPT里。”于是导出透明PNG功能上线同时把默认字号下限提升到16px保证导出后在PPT里不显得局促。这几次迭代让我意识到一个判断标准接到新功能需求时先问一句“这是不是源文本表达能力的缺失”。如果答案为是优先增强DSL和布局引擎如果答案是否再考虑加GUI交互。这个原则让diagram-design没有变成一个小而全的画图工具而是始终保持“文本定义优先”的清晰定位。如果让我重新做一次diagram-design我会把布局引擎的插件化接口放在第一天来抽象。布局算法是这类工具真正的核心竞争力语法、渲染、编辑器都是围绕布局结果工作的。现在补插件化接口需要做不少兼容改造早设计的话能省一个量级的时间。给也想动手做类似项目的同学一个建议先让一条文本变成一根线再让十行文本变成一张像样的架构图最后才考虑主题、导出和编辑器体验。这条路径我走下来是性价比最高的一条。
在没有做diagram-design之前我的日常里最烦的一件事就是画架构图。文字写了三屏图只有一张但那张图我可能改了六版。传统绘图工具的核心槽点在于存下来的是一堆绝对坐标和随机ID图一旦复杂别说让别人review自己隔一天再打开都晕。所以我决定换一条路子把图表的生成从“拖拽绘制”变成“文本定义自动渲染”。diagram-design就是这么来的。它是一个脚本化的图表设计系统核心能力是接收结构化的文本描述解析成图模型再自动布局与渲染成SVG或Canvas图。能做什么能快速绘制架构图、流程图、依赖关系图、组织架构图可以嵌入文档站或知识库也能在CI里自动生成和维护架构文档配图。适合谁后端文档工具链维护者、前端可视化开发者、知识库建设者以及所有经常需要给团队画系统图但又不想浪费时间拖拽的同学。这篇文章会把我的设计思路、核心实现、实操路径和踩坑记录全都摊开来讲。1. 整体设计聊一聊diagram-design的定位和取舍逻辑1.1 传统绘图工具为什么越用越痛苦先说一个很实际的场景。我之前维护一份系统设计文档里面有张模块依赖图总共二十个节点、三十条连线。用图形化工具画的时候光是把节点摆整齐就花了半小时连线的标签位置更是拖来拖去怎么都不满意。最让人崩溃的是第二天产品经理告诉我某个模块要拆分等于整张图重画。这类工具本质上是“所见即所得”但它保存的是最终画面的坐标快照不是结构描述。坐标快照有几个致命问题第一不可Diff。两个人同时改一张图合并冲突完全没法处理第二不可搜索。我想查“支付模块到底依赖了哪些服务”在画布上靠肉眼找第三不可复用。换一个项目基本要从零画起。diagram-design的出发点就是反着来我把图当作源代码来管理而不是当作画布来管理。所有节点、连线、分组、样式都以结构化文本形式存在想改就改文本想自动生成就拼字符串想审查就发Pull Request。图只是文本渲染后的结果不是事实本身。1.2 diagram-design用什么策略解决图表维护难题直接说结论用一套轻量级的DSL作为图的“源代码”配一个自研的自动布局引擎和双通道渲染器。具体收益有三个。第一是工程化能力。文本格式天然适配版本控制、CI检查和批量生成。团队里任何一个人改了DSL其他人都能在代码评审阶段看到图的变更而不是等着他截图发群里。第二是可编程能力。依赖关系可以从代码里自动解析并拼成DSL文本。比如扫描工程里的import语句自动生成一张模块依赖图。这在传统画布工具里几乎不可能实现但在diagram-design里就是几行字符串拼接。第三是表达与渲染分离。既然源文本独立于渲染器那么同一张源文本可以输出去年风格的静态图片也可以渲染成互动式的网页组件甚至生成给外部团队看的简化版图。主题和样式全部交给渲染层结构定义层保持纯粹。1.3 整体架构分层与每个模块的边界diagram-design从逻辑上拆成五个模块每个模块只管一件事模块职责输入输出DSL解析器把文本解析为语义化的数据模型源文本字符串GraphModel语义校验层检查节点重复、连线悬空、分组冲突GraphModel校验结果与错误定位布局引擎计算每个节点和连线的坐标GraphModelPositionedModel渲染器把坐标模型画到画布上PositionedModelSVG/Canvas画面编辑器适配层对接代码编辑器、双栏预览、自动补全底层模块组合交互工具链这里最关键的边界是GraphModel和PositionedModel的分开。GraphModel只描述“谁连谁、谁属于哪个组”完全不关心坐标布局引擎输出的PositionedModel才包含每个节点的x、y、width、height。这个分离看似多出一次数据转换但实际让整个系统变得非常灵活——组件库可以复用自定义布局可以替换不同渲染器也能共享同一套模型。2. 核心实现从语法解析到渲染器的三层架构2.1 DSL语法设计用最少的关键词表达一张图DSL语法设计是我最早动手的部分。参照常见绘图工具的使用习惯和文档场景的表达习惯我定了四个核心关键词graph声明图属性、节点定义节点、连线定义关系、分组定义逻辑归属。一段典型的DSL长这样graph 订单模块依赖 width: 900 height: 600 主题: 暗色 节点: A: 订单服务 B: 支付网关 C: 库存中心 D: 用户服务 分组: 中台能力: [B, C] 连线: A - B: 发起支付 A - C: 扣减库存 B - D: 查询用户每个节点用“标识符: 显示名称”表达标识符负责引用显示名称负责在图上展示。连线用箭头表达式表达冒号后面是连线标签。分组用列表表达成员归属。这套语法最大的特点是少用户只需要记住五个写法就能覆盖大部分架构图和流程图的表达。解析器我拆成了三层。词法层面按行扫描把每行归类成节点定义、连线定义、属性声明、分组列表在此基础上构建AST再把AST转换为GraphModel并做语义校验。这里最值得提的经验是语义校验不能省很多使用者第一次写DSL会出现引用不存在的节点、分组重复、箭头两边是同一个节点这类问题。校验器会把具体问题定位到某一行并输出友好提示这比渲染时莫名其妙少一条线要好排查得多。2.2 自动布局引擎层级、排序与坐标计算的关键取舍布局引擎是整个diagram-design里算法密度最高也最折磨人的部分。自动布局的本质是把一个抽象的图结构转成一张人眼看起来舒服的平面坐标图。所谓“舒服”其实可以拆解成几个硬指标节点不重叠、连线尽量少交叉、连线尽量短、层次方向一致。我的实现路径分四步走。第一步是分层在有向图里把入度为零的节点放在第一层然后逐步向下推导每个节点所在的层级。可以把分层类比成给公司里各部门排汇报层级没有人汇报的部门经理放最上面下面的普通员工一层层排下去。第二步是同层排序在同一层的节点之间做排序目的是让连线在跨越层之间时尽量竖直向下而不是斜穿整个画布。这步对交叉数影响最大。第三步是坐标分配根据层高、节点宽度、层内间距递推出每个节点的具体坐标。第四步是连线路由确定连线从节点的哪个锚点出去、从哪个锚点进来以及标签的位置。对于树形结构布局会退化成简单的递归排布很好处理。对于有环的图我会先做环检测提示用户确认是否要强制按某个拓扑顺序展示或者把环内的节点特殊标记。个人经验是自动布局不可能让所有图都完美“手微调”必须被设计成一等公民。为了让这张图允许用户微调我在PositionedModel里保留了一个override字段只要用户在DSL里显式给出了某个节点的坐标布局引擎就直接采用不再覆盖。2.3 渲染通道SVG和Canvas怎么选以及主题系统怎么搭渲染层最初只做了SVG通道后来补了Canvas通道原因是节点一多SVG就撑不住了。我的选择标准很简单节点数量在2500以下默认SVG。因为SVG有完整DOM结构事件交互方便而且缩放对文字清晰度无损。节点数量超过2500自动切换Canvas。Canvas走的是绘制即失忆路线没有DOM节点但批量绘制性能远超SVG。两套渲染通道共用同一个布局输出只是绘制指令不同。SVG直接生成节点rect、path、text、markerCanvas则用循环批量调用fillRect、moveTo/lineTo、fillText绘制。主题系统做得比较通用一个theme对象就定义了背景色、节点边框色、文字色、连线色、箭头样式、圆角大小、阴影。DSL里通过主题: 暗色这种声明去引用内置主题也支持用户在运行时传入自定义主题对象。配套做的导出能力也要提一句SVG图可以直接序列化保存PNG导出要先在Canvas上重绘再调用toDataURL完成下载。这里出现过的中文文字基线问题我放到后面避坑部分细说。3. 实操路径手把手跑通diagram-design的最小核心链路3.1 最小可行版本一段文本渲染出一个节点加一条连线我强烈建议任何人做类似项目都从“一条线”开始不要一上来就做主题和布局。diagram-design的第一步只做这样一件事把一段DSL解析成节点画出一个矩形和一条箭头线。核心流程就是一个管道const source 节点: A: 订单服务 B: 支付网关 连线: A - B ; const model parseDSL(source); // 转为 GraphModel const positioned layout(model); // 计算坐标 document.body.innerHTML renderSVG(positioned); // 渲染输出第一步parseDSL的实现逻辑并不复杂逐行读取遇到“节点:”就开始收集节点条目把“标识符: 名称”拆成id和label遇到“连线:”就开始按箭头符号拆分左右两端。第二步layout最简单的版本只需要返回每个节点固定坐标比如A在(20,20)B在(200,80)连线的控制点取两个节点中心点。第三步renderSVG把节点渲染为带文字的矩形把连线渲染为一条line元素和箭头终点。跑通这个最小链路之后再逐步加东西分组支持、多行标签、主题、缩放适配。这样的好处是每一步都有确定的验证点出了问题很容易定位是解析器、布局器还是渲染器的问题。我实际写的时候光是连续线标签在FAQ里就折腾了三天如果一开始就把所有功能铺开根本查不过来。3.2 编辑器侧集成双栏实时预览与增量计算diagram-design不是只能命令行单机使用配套的编辑器体验也是项目的一部分。我做的编辑器非常简单左侧是源代码区域右侧是渲染预览区。左侧输入内容变化后右侧在两三百毫秒内自动更新预览。实现细节上有个重要经验不要每次输入都做全量解析、全量布局、全量渲染。更稳妥的做法是做一个三层防抖机制。第一层是输入防抖监听input事件之后300ms才触发解析第二层是布局节流布局计算如果有上一次的结果可复用尽量复用未修改子图的坐标第三层是渲染分帧把节点数量多的图分批绘制避免一帧内完成全部绘制导致界面卡死。同时还要把错误信息展示在编辑器里而不是仅仅日志输出。解析失败时保留上一次成功渲染的画面并在左侧代码区用波浪线标出错误行。这个交互习惯来自我自己的体验一改代码就闪成空白页面那种挫败感是灾难性的。3.3 可扩展能力自定义节点、导出PNG与嵌入文档站一个工具类项目如果只能画固定几种矩形和圆很快就会撞天花板。diagram-design提供了节点类型注册机制使用者可以自定义一种新节点并绑定专属渲染函数。注册方式类似design.registerNodeType(database, { render(ctx, node) { // 圆柱体绘制逻辑 ctx.fillRect(node.x, node.y, node.width, node.height); ctx.ellipse(node.x node.width / 2, node.y, node.width / 2, 8, 0, Math.PI * 2); } });注册之后DSL里就可以写A#database: 用户数据库渲染器会自动按注册的类型来画。这个扩展机制把diagram-design从一个固定图表工具变成了一个可以定制视觉语言的设计系统。图片导出这边我做了三个入口界面上的导出按钮、调用API的编程式导出、以及命令行工具导出。命令行导出主要用于CI场景比如文档站构建时自动重新生成所有架构图。文档站嵌入则提供两种方式静态模式预渲染成SVG字符串服务端注入动态模式在浏览器加载DSL源码再实时渲染。博客和静态文档我建议用前者交互式知识库用后者。4. 避坑记录常见问题排查与性能优化实录4.1 排查图表渲染问题的速查表做diagram-design的过程中我攒了不少问题多数问题不是出在语法解析而是出在坐标计算和渲染交互上。把最典型的一批问题整理成速查表现象根本原因解决办法节点相互重叠图结构里存在孤立节点布局算法没有把它们纳入层级布局前先对所有节点做拓扑分组孤立节点单独成列放置连线穿过了无关节点连线路由使用了直线模型没有避障升级为正交路由让连线先竖向下移再横穿层级间走间隙中文标签在导出PNG时错位文字宽度按英文字符估算中文字符宽度不同统一用canvas measureText方法测量实际文本宽度用于计算节点尺寸浏览器缩放后图错位SVG坐标系统和DOM事件坐标混用所有坐标统一走viewBox相对坐标系事件坐标反向映射到viewBox空间大图拖动卡顿SVG节点过多导致DOM更新频繁超过阈值自动切换到Canvas渲染通道解析错误提示不够直观词法错误没有定位到行列解析器为每个token记录行号和列号错误对象统一带loc属性这些坑里最容易被新手低估的是中文字体宽度问题。所有需要自适应宽度的图形节点都不能用“字符串长度乘系数”这种粗暴方式估算必须用Canvas的measureText做精准测量。我在第一个版本里就吃了这个大亏所有英文图都正常一旦有中文节点文字就会溢出边框。4.2 千级节点图表卡顿的调优实录有一次我用diagram-design渲染一个系统全链路依赖图节点数量到了三千。那个版本默认走SVG结果页面直接卡到没法滚动。我的调优过程按下面几步推进。第一步是定位瓶颈。用浏览器性能面板记录渲染过程发现大部分时间耗在创建SVG元素节点上——三千个rect、三千个text、两千条path光创建DOM就得花好几秒。于是把渲染通道切到Canvas一次性绘制全部图形绘制耗时从秒级降到几十毫秒。第二步是解决交互反馈。Canvas模式下鼠标悬停和高亮需要自己做命中测试我实现了简单的空间网格索引把画布分成若干区域鼠标移动时只需要检测鼠标所在区域内的节点不用遍历全部节点。第三步是布局计算的卡顿。三千个节点的分层排序在主线程跑要一两百毫秒而且每次文本改动都要重新算。我把它挪进Web Worker主线程只负责接收计算结果再绘制。用户感受就是从“每次输入都卡一下”变成“输入完稍等片刻看到图形平滑更新”。调优完成后我把自动切换阈值定在2500节点。这个数字不是拍脑袋是在中低端笔记本上实测过SVG和Canvas各自流畅分界的经验值。4.3 从使用者反馈中总结的迭代心法diagram-design有一段时间只在我自己电脑上跑后来给团队里几个后端同事试用收获了不少意料之外的反馈。第一位同事说“语法记不住每次都要回来翻示例。”于是我加了语法提示。方式很简单编辑器拿到AST里的可插入位置弹出一个候选关键词列表例如在节点列表末尾提示“新节点写法: id: 名称”。第二位同事说“有些图自动布局已经很好了但我就是想微调一个节点的位置。”这个需求催生了“覆盖坐标”功能用户在预览图上直接拖拽这个节点系统自动把偏移量换算成DSL里的坐标属性写回。第三位同事说“想把这个图放进给客户的PPT里。”于是导出透明PNG功能上线同时把默认字号下限提升到16px保证导出后在PPT里不显得局促。这几次迭代让我意识到一个判断标准接到新功能需求时先问一句“这是不是源文本表达能力的缺失”。如果答案为是优先增强DSL和布局引擎如果答案是否再考虑加GUI交互。这个原则让diagram-design没有变成一个小而全的画图工具而是始终保持“文本定义优先”的清晰定位。如果让我重新做一次diagram-design我会把布局引擎的插件化接口放在第一天来抽象。布局算法是这类工具真正的核心竞争力语法、渲染、编辑器都是围绕布局结果工作的。现在补插件化接口需要做不少兼容改造早设计的话能省一个量级的时间。给也想动手做类似项目的同学一个建议先让一条文本变成一根线再让十行文本变成一张像样的架构图最后才考虑主题、导出和编辑器体验。这条路径我走下来是性价比最高的一条。
