diagram-design 这个内部代号承载的是我最近半年做的一个自研图表引擎。起因是在某内部平台做架构设计时团队需要一个能承载流程图、架构图、数据链路图的可视化组件。当时的第一反应是找现成库但接了两天就发现问题大多数工具都是画布 形状的思路图的结构语义、节点与节点之间的业务关系、数据和坐标的联动几乎都要自己额外维护。与其继续打补丁我决定从图的内核重新设计。这篇文章会把从数据模型、布局算法、渲染选型到序列化设计的完整取舍记录下来适合正在纠结要不要自研可视化能力的开发者也适合想理解图表引擎核心瓶颈的人。需要提前说明这篇里的很多方案来自工程上的妥协不一定是最优解但每一步都是踩过坑、能落地的做法。1. 动手之前通用画图工具到底卡在哪先明确一个前提这不是否定现成工具的价值而是说明一套通用绘图工具和以数据为中心的图表设计系统之间的本质差异。搞清楚这个差异后面所有设计决策才有依据。1.1 图是画出来的不是算出来的绝大多数绘图工具对一张图的理解就是一堆矩形、线和文字的集合。用户对着画布拖一个方块再画一条线本质上是在摆照片——工具并不知道这个方块代表服务 A那条线代表调用关系。所以当数据变化时所有内容都要人肉调整。做静态配图没问题可一旦图的来源是接口、数据库、配置文件这种模型就撑不住了。diagram-design 从一开始就把图定义成一份有语义的数据结构节点、边、分组都是显式对象图上所有改动最终都落到这份数据上渲染只是数据的投影。这个思路在后面的自动布局、数据对接、多人协作里都帮了大忙。1.2 数据量一上来前端画板先投降我最初用现成绘图库做的 demo30 个节点拖动很顺畅结果接真实数据一上来就是几百个节点。问题迅速暴露拖动节点时整个屏幕都在闪工具栏操作有延迟导出图片要等几秒。原因不是库写得不好而是它们默认把每个图形都当成一个独立对象来管理节点一多事件注册、命中检测、坐标计算的成本就线性增长。在浏览器里用最朴素的 DOM/SVG 方式渲染几百个元素还能对付上千个就开始吃内存。这个阶段让我下决心放弃直接把别人的画布当内核的路线改成自己设计渲染与数据之间的边界。1.3 没有合适的序列化格式图就只是一张图更隐蔽的问题出现在和后台系统对接的时候。团队希望每次改图都能对比版本、走评审流程甚至让脚本能自动检查图中某个节点是否缺失、依赖关系是否合法。这要求图必须能存成结构化的文本格式能做 diff能重新加载还原。而通用工具往往只提供了私有格式或者一把梭的 JSON 导出字段不表意、不通用。后来我们把节点、边、分组、布局信息全部整理成一份带版本的 JSON Schema这才让图真正变成了可以被代码审查和自动化校验的数据。1.4 diagram-design 的定位和三句话原则于是 diagram-design 的定位就清晰了一个以数据模型为中心、渲染层可替换、布局算法可插拔的图表设计内核。三个原则贯穿了整个项目。第一数据与渲染分离所有渲染器只是消费图模型的投影第二布局是可选能力布局结果落回模型但模型不依赖布局第三序列化从第一天就设计而不是最后补。这三句话几乎解决了后续 80% 的架构争论。2. 图内核的数据模型为什么不能从矩形开始不能从矩形开始的意思是不要一上来就给每个图形对象定义样式和坐标而要先定义语义对象然后让坐标、样式作为属性挂上去。顺序反了后面所有逻辑都会拧巴。2.1 节点语义、几何和样式分开节点是图的顶点数据模型大概长这样id、type、position、size、style、data、ports。id 在整个图内唯一建议直接生成 UUID 而不是用数组下标后面做增量同步和引用时会省很多事。type 表示节点的业务类型比如服务、数据库、函数它决定了形状模板、图标、引脚位置。position 我用左上角坐标不用中心点坐标原因是布局算法和前端 CSS 对齐都更直接计算层级坐标时少一层换算。style 存外观但不要让它和 type 纠缠在一起同一个类型可以有多套主题。data 是业务自定义字段核心引擎不解析它只是透传保存。这样画一个节点时引擎关心的是它是什么、在哪、连向谁外观反而是最不重要的部分。2.2 边、锚点与端口连线不是一条线段很多人第一次写图模型会把边定义成起点坐标到终点坐标甚至把拐点坐标直接存成数组。这在静态图上怎么都能用但只要节点一移动边就变成一笔断线必须手工重画。正确做法是把边定义成从哪个节点的哪个端口连到哪个节点的哪个端口。端口是节点上可连接的锚点有方向比如输入端口和输出端口。边记录 sourceNodeId sourcePortId、targetNodeId targetPortId再加上 optional 的拐点列表 points。渲染时起点和终点由端口在节点上的相对位置实时计算节点拖走边自动跟着走。拐点列表只在用户手动拖过折线时才写入。2.3 分组与子图布局的嵌套边界节点还会面临嵌套。比如一个微服务下面有多个接口模块一条链路上有多个泳道分区。我们可以给节点加一个 children 字段表示它是一组子节点的父容器。这样做的关键收益是布局的嵌套边界外层布局算法把父节点当成一个整体内层布局在子图内部运行两者互不干扰。父节点的尺寸可以手动固定也可以设置为根据子图大小自适应子图变化时父节点自动撑大。实际使用中我发现如果不提前设计这个嵌套边界后面遇到把一组节点打包成一个模块的需求时你会被迫在渲染层做很多外挂逻辑非常难受。2.4 画布视口与自定义数据别塞进图模型容易犯的错是把视口信息写进图 JSON。zoom、pan x、pan y 属于用户此刻在看哪不是图本身的属性。两个人同时打开同一张图视口可能完全不同把视口序列化进去等于把个人状态混进共享数据同步和协作都会出问题。所以视口状态单独存一份 UI 状态和引擎隔离。自定义数据则统一约定一个 data 字段核心引擎只负责保存和返回不参与结构运算。业务上想记录作者、更新时间、配置参数都不用改引擎只改 data 的约定即可。3. 布局引擎让节点自己排队有多难布局引擎是整个项目里最数学的部分也是最容易做过头的地方。我的经验是先想清楚要哪些布局再动手不要一上来就实现一个通用的布局宇宙。3.1 先想清楚要哪些布局布局类型适用场景特点层次布局流程图、分层架构图节点按层级一列列排边尽量少交叉树形布局组织架构、类目树清晰的父子关系逐层展开力导向布局拓扑关系、集群关系模拟物理斥力引力自动聚团正交布局总线式、泳道式边只在水平/垂直方向拐弯一开始不需要全部实现。我建议先做层次和树形这两个覆盖了 80% 的内部工具场景其余按业务需求遇到一个加一个。把布局做成一堆参数塞给一个万能算法只会得到一个所有场景都不满意的结果。3.2 层次布局的最小实现层次布局的核心是把有向图转换成一层一层递进的坐标。简化的实现分三步。第一步计算节点的层数。从入度为 0 的节点出发做拓扑遍历节点所在层等于其父节点最大层加一。对有环的图先做一次破环或者把环上某条边临时忽略。第二步同层排序减少交叉。反复交换同一层内相邻两个节点的位置统计跨层边的交叉数朝交叉数变小的方向交换几次。这一步不做会很惨不排序的层次布局边会乱成一团。第三步分配坐标。层与层之间按固定间距排开同层节点按排序后的宽度累计排布。为了处理跨多层的一条长边可以把长边中间的虚层拆成虚拟节点这样边就变成逐段折线整体结构清爽很多。完整的 Suigiyama 系列算法更复杂但上面这套简化版本在大多数内部场景下已经够用。3.3 布局约束与固定节点布局引擎最怕的是你刚拖好几个节点它一跑全图又全给你重排了。必须支持锁定语义。节点带一个 locked 字段布局算法遇到 locked 节点就直接跳过不参与位置计算它周围的未锁定节点在分层时把它当固定锚点。另外局部刷新也很重要拖动一个节点时不要把整个图重排而是只重排它所在的子图或受影响区域的节点不然用户每次拖一下其他地方就全变了体验很糟糕。可以给布局引擎引入一个 dirty 子图的概念只有标记为受影响范围内的节点才重排。这样自动布局才能作为兜底而不是搅局者。3.4 布局动画让变化不吓到用户当布局从旧位置切到新位置时粗暴地直接更新坐标会导致所有节点瞬间跳走用户根本看不清哪个变了、哪个没变。我们后来加了补间动画给新旧坐标之间做几百毫秒的过渡并且按层分批让节点移动先移动第一层再第二层。视觉上会有一种流动感而不是乱成一团的跳动。坦白说这个细节一开始没做后来被团队反复反馈太突然了才补上属于看起来小但影响很大的体验点。4. 渲染层的三分边界SVG、Canvas 与缓存层渲染层的选型不是一道单选题更准确的说是按节点数量和数据特征做分层混合。我把它分成三条边界来讲。4.1 小图用 SVG 很舒服但别贪心SVG 作为默认渲染方案有几个天然优势节点就是 DOM 元素可以挂事件命中检测由浏览器代劳缩放后图形是矢量不模糊文字样式可以直接复用 CSS开发效率很高。对追求开发效率的人来说SVG 能省掉大量底层代码。在节点数 500 以内时SVG 方案的性能完全可接受我早期所有功能迭代几乎都跑在 SVG 层上。这个阶段不要过早考虑 Canvas先让业务逻辑跑通。4.2 600 个节点之后Canvas 接管主场景当真实数据突破 600 个节点时SVG 方案开始明显喘气。问题来自三个方面大量 DOM 节点导致初始渲染慢每次位置更新要重新设置大量元素的属性事件监听器数量也涨上去了。实测拖动时主线程持续满载帧率掉到个位数。这时候只能上 Canvas。Canvas 整个图就是一张位图渲染 1000 个节点也就一帧几百毫秒级但代价是命中和交互全部要自己实现。我们的做法是把渲染层拆成两种适配器SVGRenderer 和 CanvasRenderer 共用同一个图模型节点数超过阈值就自动切换。因为前面强制了数据与渲染分离这个切换做起来很快没有牵扯到业务逻辑。4.3 Canvas 的命中检测与网格索引Canvas 没有 DOM 概念拿到鼠标坐标后就必须自己回答这个点是否落在某个节点上。最朴素的做法是遍历所有节点做矩形碰撞判断1000 个节点每次 mousemove 跑一遍还能忍但再大就吃力。我们加了一层简单的网格索引画布按 100px 一格切分每个节点注册到覆盖它的网格槽里命中测试只查鼠标所在网格槽内的节点。实测 5000 个节点时也能维持可用帧率。注意在 Canvas 上做端口命中时要把坐标先换算到节点的本地坐标再判断否则节点有旋转或缩放时会错位。4.4 坐标变换与视口换算无论是 SVG 还是 Canvas都绕不开坐标变换界面上的坐标等于模型坐标经过平移和缩放。核心公式就一个renderX (modelX - viewportX) * zoom renderY (modelY - viewportY) * zoom反过来鼠标事件拿到的 client 坐标要转回模型坐标才能做命中modelX clientX / zoom viewportX modelY clientY / zoom viewportYSVG 里可以用 viewBox 自动帮你处理一部分换算但我更推荐自己维护一个 viewport 对象。原因很简单Canvas 没有 viewBox统一维护一套坐标换算逻辑可以避免两种渲染器各自实现导致行为不一致。minZoom、maxZoom 也一定要设好比如 0.2 到 2.5不然用户很容易缩到图找不见的地步。5. 交互层的工程细节拖拽、连线和撤销交互层的核心不是炫酷动效而是可预测、不丢数据。这里记录几个很容易被忽略的工程细节。5.1 鼠标事件的归属判定点击画布上的某个位置到底是拖节点、拖端口连线、框选还是平移画布mousedown 时先做一次命中检测按端口 节点 画布的优先级判定。命中端口进入连边模式命中节点准备拖动命中画布空白处则准备框选或拖动画布。mousemove 再根据当前模式执行对应逻辑。事件委托这时候很重要SVG 版本不要让每个节点各自绑定监听而是在容器上统一监听再通过命中检测分发。这个习惯越早养成越省心等节点多了再改事件架构会很痛苦。5.2 连线交互临时线、端口高亮与合法性校验从端口拖出的临时连线用虚线渲染拖到目标端口上方时目标端口高亮。线最终落定时要做合法性校验方向是否匹配、节点是否允许自连、重复边是否允许。校验不通过时不要静默拒绝最好给一个红闪反馈让用户明白为什么连不上。这个交互看着小但直接影响图上数据结构的健壮性——不合法的边一旦存进 JSON后续所有分析逻辑都会出问题。宁可交互上多一步确认也不要在数据里埋雷。5.3 undo/redo命令模式还是快照最初我想用经典命令模式每个操作记录逆操作很优雅但实现成本极高。特别是布局操作逆操作几乎要存整张图。后来采用了一个折中方案针对显式用户操作做快照。快照存的是整个图 JSON 的一份不可变副本每次操作完成后压入历史栈撤销时直接回退到上一个快照。快照在 1000 节点量级下一份 JSON 几 MB压缩后在可接受范围内。关键教训是撤销的粒度要对应一次明确操作而不是每帧 mousemove 都记录否则历史栈会瞬间爆炸。5.4 键盘、框选与手感除了鼠标还有几个手感细节。框选用矩形选择区按下 Shift 变成追加选择Delete 键删除选中节点时要先把相关边的引用清掉否则会留下悬空边。快捷键映射要做成可配置避免和浏览器原生快捷键冲突缩放步进建议用 25% 一档不要用连续缩放连续缩放带来的惯性很难看精细操作也不方便。6. 序列化设计图数据怎么写才能长久序列化是图表系统里最容易被低估的部分。很多人画图功能做完了才补导出逻辑结果图数据结构已经零散分布在多个渲染器里改起来动一发而牵全身。我们把序列化放在和渲染同等重要的位置。6.1 先定 JSON Schema 的基础结构序列化的核心是一个带版本号的 JSON Schema。顶层字段大致是version、nodes、edges、groups。nodes 是一个数组每个节点包含 id、type、port、data 等字段edges 数组里的每条边引用 source 和 target 的 id 与端口。用 id 引用而不是内嵌对象是铁律——否则同一个节点出现在多条边里时会重复序列化diff 和迁移都很难搞。version 字段从第一天就要有后面任何字段变更都靠它驱动 migrator。没有版本号的图数据就是一次升级一次事故。6.2 布局信息该不该存很多布局引擎的观点是布局是运行时计算出来的不用存。实际项目里这个观点会被用户教育用户手动挪过的位置就是宝贵的布局结果你不保存下次打开就丢了。我们的最终方案是布局结果也落进 JSON但带一个 layoutVersion 标记表示这个坐标是哪个版本的布局算法生成的。如果算法版本变了加载后自动标记需要重排由用户决定是否触发自动布局。这样既保住了手动调整的坐标又不让陈旧布局锁死新算法。这个设计在后来的布局算法升级中帮了大忙老图没有被强制重排也没有因为版本不一致而崩溃。6.3 文本化导出让图可以进代码仓库评审图 JSON 能驱动渲染和编辑但不适合人类阅读。我们又加了一类文本化导出把节点、边、分组压缩成一种可读的图表 DSL——用文本缩进表示分组、用箭头表示边的那种语法。这样做的好处是图可以作为一个代码文件放进仓库可以 diff、可以评审甚至可以被脚本检查。我们团队后来不少自动化检查就是直接跑在 DSL 上的比解析 JSON 直观得多。不过双向转换有信息损失颜色、位置微调、事件备注这些都会丢。所以 DSL 只作为只读快照和轻量导入完整编辑还是走 JSON。别试图做一个完美的双向转换器那是个无底洞。6.4 数据迁移与增量保存一次字段重构老数据全部加载失败我花了一整天才把转换脚本补上。自那以后所有字段变更都必须走 migrator读取 version如果版本旧按迁移链逐级升级字段结构。增量保存方面大图全量写入代价太大。我们采用操作日志模式正常编辑只追加变更记录定时做全量 checkpoint崩溃恢复时只需要重放未 checkpoint 的日志。这套组合让序列化从最容易被忽略的角落变成了最可靠的子系统。7. 性能优化实录从卡顿到流畅的三个转折点性能问题解决得好不好直接决定了这个引擎能不能上真实业务。我们把 700 到 1000 节点量级作为压测基线前前后后经历了三个关键转折点。7.1 布局计算挪到 Worker主线程先喘口气某次联调一张 700 个节点的图跑自动布局布局算法同步执行大约耗时 900ms。900ms 看着不多但加上随后的渲染更新主线程被阻塞了将近两秒界面直接卡成 PPT。解决方案很直接把布局算法塞进 Web Worker。主线程提交图模型Worker 算完后把节点坐标 postMessage 回来主线程只做渲染。这里有个细节postMessage 传大对象默认是结构化克隆700 个节点没问题但上万节点时会明显变慢。可以研究一下 transferable 对象把缓冲区所有权直接转给 Worker能省一大截拷贝时间。7.2 事件绑定从泛滥到委托早期 SVG 版本给每个节点实例绑定点击、拖动、双击等事件。节点多了以后不只是内存占用还有事件注册与解绑的生命周期问题——重渲染一次就可能留下一批僵尸监听器。后来全面改成事件委托在画布容器上绑定统一事件事件对象里用>
