项目排期表上横着一块难啃的骨头：五十多个服务模块的调用关系，要整理成一张能让全组看懂的结构图。我打开常用的绘图工具试了两个小时，节点一多画布就卡，连线经常从节点上“漂移”，最后生成的文件也没法直接嵌入我们自己的后台系统。那阵子我一直在琢磨 diagram-design 这件事——与其在通用工具里费力凑合，不如按自己的业务需求做一个图表设计器。这个想法后来真的落地成了一个可运行的模拟项目，这篇文章把从需求边界、数据模型到渲染选型的完整思路整理出来，给想在业务里自研图表编辑器的同学做个参考。

1. 对需求重新做减法：好用的图表设计器，核心只有三件事

1.1 通用工具满足不了的三个硬需求

先说清楚我为什么要自研，而不是继续用现成的绘图工具。当时我们手里有现成的可视化大屏组件库，也有内部沉淀的图形渲染封装，但面对“系统架构图”这个场景时，普遍存在三个痛点。

第一个痛点是结构化数据驱动。架构图不是手工一笔一笔画出来的，它是 CMDB 里上千条依赖关系的数据投影。我希望给定一份 JSON，图就能自动生成；数据变了，图跟着变。通用绘图工具虽然支持导入数据，但导入之后数据结构和渲染模型是割裂的，改一个节点属性要同步好几个地方，非常别扭。

第二个痛点是编辑和展示必须一体化。自动生成的位置往往不完美，需要人工拖一拖、把重要的链路摆到 C 位。通用工具要么偏展示（只能看不能改），要么偏手工绘制（完全不理解节点和连线的语义），两者很难兼得。

第三个痛点是可嵌入和可扩展。做出来的图最终要嵌进内部的运维后台、故障排查页面，甚至要支持二次开发。商用工具的嵌入能力始终隔着一层，导出的图片又丢了交互信息。

所以我的结论是：图表设计器不是一个“画图软件”，它是一个数据结构可视化编辑器。核心职责是把图数据模型映射到画布，再用交互手段让人修正映射结果。

1.2 明确不做什么，反而让进度更快

自研工具最容易犯的错误是需求越加越多。项目刚启动时，同事A提了一嘴“能不能支持思维导图布局”，同事B说“最好可以多人同时编辑”，还有人说“配色方案要多套主题皮肤”。这些需求听起来都有道理，但都会显著拉长开发周期。

我给这个阶段定了一条规矩：只做节点、端口、连线、标注四类元素，只支持单选、多选、拖拽、缩放、平移、连线、撤销重做这一组基础交互。第一版明确不做协同编辑，不做复杂美化和主题系统，不做移动端触屏适配。

做出这些取舍之后，项目边界一下子清晰了。整个系统被拆成四层：数据层负责维护图结构和快照历史；交互层负责把用户操作翻译成数据变更；渲染层负责把数据画到画布上；布局层负责给自动生成的图一个合理的初始排布。每一层之间用明确的数据接口通信，后面渲染方案想换掉，交互层和数据层都不用动。

1.3 功能边界划好之后，模块长什么样

这里放一张当时的模块划分思路，你可以直接参考：

• 数据层（model）：定义 Node、Port、Edge、ViewState 四个核心类型，提供 JSON 序列化和反序列化接口。
• 交互层（interaction）：封装画布事件派发、拖拽逻辑、缩放平移算法，不直接接触 DOM，只产出“意图操作”。
• 渲染层（render）：只做一件事——把 data + viewState 渲染成可见画面，内部决定用 SVG 还是 Canvas。
• 布局层（layout）：输入是无坐标的图结构，输出是带坐标的节点位置表，支持层级布局和力导向布局两种算法。

模块之间的依赖方向是单向的：交互层依赖数据层，渲染层依赖数据层，布局层也依赖数据层。谁都不依赖渲染层，这意味着渲染层完全可以被替换。这个设计在后来的阈值切换方案里帮了大忙，下面会详细说。

2. 数据模型定稿：先定义“节点-端口-连线”三元组，再谈其他功能

2.1 最朴素的图数据结构，一眼就能看懂

很多人在做图编辑器的第一个版本时，喜欢直接上复杂的数据结构，比如把节点坐标、样式、父子关系全塞进一个大对象里。我的建议是反过来：先用最朴素的 model，够用就行，后面需要时再扩展。

我最终定下的核心结构长这样：

{ "version": 1, "nodes": [ { "id": "node-a", "type": "service", "label": "订单服务", "x": 120, "y": 200, "width": 140, "height": 56, "ports": [ { "id": "node-a-out-1", "direction": "out", "relX": 1.0, "relY": 0.5 } ] } ], "edges": [ { "id": "edge-1", "sourceNodeId": "node-a", "sourcePortId": "node-a-out-1", "targetNodeId": "node-b", "targetPortId": "node-b-in-1", "waypoints": [] } ], "viewState": { "scale": 1, "offsetX": 0, "offsetY": 0 } }

节点坐标用的是世界坐标系里的绝对坐标，而不是相对坐标。这点我专门确认过：如果采用嵌套父子节点，相对坐标会带来一层层的累加偏移计算，很多 bug 都出在坐标转换上。我们第一版不做嵌套，所以全部用绝对坐标，简单直接。

2.2 为什么非要加“端口”，而不是让连线直接粘在节点上

这是整个数据模型里最重要，却也最容易忽略的设计。许多人做图编辑器，连线就是拖一条线从一个节点边缘连到另一个节点边缘。初期这样很爽，但很快会遇到三个问题。

第一，锚点不可控。直接连节点边缘时，连线落在哪个位置是由几何算法算出来的，经常压住文字或者扎进另一个节点里面；有了端口，锚点是手动指定的固定位置，视觉上非常稳定。

第二，语义表达不清。端口天然带有方向，一个输出端口可以表达数据流出，一个输入端口可以表达数据流入。后面要做类型校验的时候，比如数据库节点只能连数据服务节点，直接在端口上挂一个 type 字段就能完成。

第三，连线的路径计算更稳定。端口存的是相对于节点的比例坐标（relX、relY），节点移动时端口绝对坐标随时可以算出来，路径规划只要基于端口坐标即可，不会出现线从节点中间穿过的奇怪情况。

我当时把端口设计成挂在节点下面的独立子对象，而不是节点上的普通属性，就是为了将来端口能自己扩展状态，比如 hover 高亮、校验失败标红。

2.3 版本化和不可变快照，是给未来的自己留后路

数据结构里有一个容易被忽略但极其重要的字段：version。图表设计器一旦上线，本地保存的文件、后端存储的图数据都依赖于这个结构。如果哪天想加一个“节点圆角”属性，老数据里没有这个字段，渲染端要能兜底。

我的做法是：每次变更生成不可变快照，快照整体存入历史栈。整个结构支持向前兼容——读数据时如果发现 version 是 1，就用 v1 的解析器；如果 version 是 2，可以先升级到 v2 再解析。现在虽然只有一个版本，但这个设计让后面加属性毫无心理负担。

3. 渲染方案选型：SVG、Canvas 还是混合？我选了一条“先用再换”的路

3.1 三种方案的能力边界，先看一张对比表

渲染层是所有图表编辑器的地面。选错了，后期的性能优化会把人逼疯。我在项目启动前把主流方案过了一遍，画了这么一张对比表：

SVG 在处理几百个节点时完全没问题，DOM 事件模型让 hover、点击、拖拽的实现成本非常低。但 SVG 有个隐性坑：一旦节点数量上千，DOM 元素节点数也会上千，浏览器的布局和重绘开销会显著上升。Canvas 刚好相反，重绘性能好得多，但所有命中检测、事件坐标换算都要自己实现，文本排版也麻烦。

3.2 为什么默认走 SVG：编辑场景里，命中检测是刚需

做设计器有一个和普通可视化大屏非常不一样的地方：用户和元素之间高频交互。拖拽要命中节点，连线要命中端口，框选要计算包围盒。SVG 把这一整套命问题都替你解决了——事件直接绑定到元素上，天然保留“哪个元素被点了”这个信息。

Canvas 也不是不能做命中检测，常见做法是维护一份节点对象的反向索引，鼠标事件时遍历或走空间哈希找到命中的元素。这套方案我评估过，写起来并不难，但要做对边界情况很烦：比如两个节点重叠时该选谁，端口和节点同时命中时优先级怎么排。在交互不稳定的项目早期，这些额外成本会拖慢核心功能落地。

所以我定下了一个原则：第一版只做 SVG，但在渲染层留好抽象接口，不做任何 SVG 专属逻辑。这样哪怕后面性能扛不住，把渲染实现换成 Canvas，交互层和数据层不用动。

3.3 阈值切换方案：什么时候从 SVG 切到 Canvas

项目做到后半段，我加了一个“大规模只读模式”。这个模式下，渲染层不是用 SVG，而是自动切换成 Canvas。

实现不复杂。我先定义了一个渲染接口，只有两个方法：

interface Renderer { render(data: GraphData, view: ViewState): void; destroy(): void; }

SVG 实现往容器里同步 DOM 节点，Canvas 实现走自绘。上层只需要在初始化时做一个规模判断：节点数量小于 500 用 SVGRenderer，大于等于 500 用 CanvasRenderer。因为只读模式下不需要精确到元素的 hover 事件，Canvas 的命中检测只需要支持“点击节点弹出详情”，用简单的坐标距离判断就够，成本可控。

当时测试下来，500 节点用 SVG 渲染加交互还勉强流畅，800 节点已经能感觉到拖拽掉帧，切到 Canvas 后 2000 节点也扛得住。这个阈值你可以根据自己的机器情况调，但方向是对的：编辑态用 SVG 保体验，展示态用 Canvas 保规模。

4. 画布交互里最容易出问题的三处：坐标变换、吸附判定、连线手势

4.1 坐标变换的原理，以及那个“放大后拖不动”的坑

图表编辑器最核心的交互是缩放和平移。这里有一个几乎所有新手都会踩的坑：鼠标在屏幕上的位置，和它在图里的世界坐标位置，根本不是一回事。

画布在任意时刻都维护着一个 viewState，里面有 scale 和 offset。屏幕上某个点对应的世界坐标公式是：

worldX = (screenX - offsetX) / scale worldY = (screenY - offsetY) / scale

反过来，把世界坐标画到屏幕上时：

screenX = worldX * scale + offsetX screenY = worldY * scale + offsetY

我调试交互时就遇到过“放大之后拖不动节点”的诡异现象。原因很简单：鼠标按下时记录的是屏幕坐标，拖拽时直接把鼠标移动的像素增量加到节点世界坐标上。在缩放率为 2 的情况下，鼠标移动 10 像素，节点只移动了 5 像素，体感就是“变迟钝了”。

修正办法是把鼠标的屏幕位移先换算成世界位移，再应用到节点坐标上。我封装了一个工具函数：

function screenDeltaToWorldDelta(dx: number, dy: number, scale: number) { return { dx: dx / scale, dy: dy / scale }; }

所有拖拽逻辑统一经过这个函数换算，之后再没出现缩放状态下拖拽手感异常的情况。

4.2 缩放锚点：为什么缩着缩着图跑没了

缩放还有一个经典 bug：默认的缩放是绕着画布原点进行的，放大后内容会“跑出屏幕”。正确的做法是以鼠标当前位置为锚点缩放，这样鼠标指向哪里，放大后哪里还是停留在鼠标底下，符合用户直觉。

锚点缩放的计算过程是：先记录缩放前鼠标位置对应的世界坐标，然后更新 scale，最后反推出新的 offset，让这个世界坐标仍然落在鼠标屏幕位置下。

function zoomAt(mouseScreenX: number, mouseScreenY: number, deltaScale: number) { const worldXBefore = (mouseScreenX - offsetX) / scale; const worldYBefore = (mouseScreenY - offsetY) / scale; scale *= deltaScale; offsetX = mouseScreenX - worldXBefore * scale; offsetY = mouseScreenY - worldYBefore * scale; }

这个逻辑本身不难，难的是记得在滚轮事件里不要直接改 scale，而是先算锚点、再更新 offset。我把滚轮、双击、按钮缩放三条路径都统一走这个函数，才彻底消除了“缩放后图飞到角落”的问题。

4.3 连线和吸附：从“勉强能连上”到“基本不会连错”

连接线操作是图表编辑器区别于普通画布的关键。用户从一个端口拉出一条线，拖到另一个端口附近松手，系统自动完成吸附连接。这里有两个体验细节值得展开。

第一个细节是吸附的判定区域。端口本身在屏幕上可能只有 8 像素宽，让用户精确命中它太难了。我给每个端口设置了一个 20 像素的“磁吸半径”，鼠标进入这个区域后，临时连线的终点自动吸附到端口中心，并高亮提示可连接。同时判定优先处理端口吸附，其次才是节点边缘吸附，避免端口和节点同时命中时行为不确定。

第二个细节是类型校验前置。如果两个端口语义上不允许连接，比如输出端口接输出端口，我会在吸附阶段直接拒绝，连线终点变红色并给出提示。这个能力数据模型里端口的 direction 字段天然支持，不需要额外维护。

连线过程中还有一个隐藏问题：拖出一条线后，鼠标经过其他节点时，线可能被节点元素挡住。SVG 模式下，我给临时连线设置了很高的 z-index，同时给它加一个pointer-events: none，让临时线不参与任何事件捕获，底层节点照常响应 hover。

5. 自动布局的工程取舍：算法不复杂，复杂的是“人和机器各让一步”

5.1 先跑通层级布局：BFS 分层加层内排序

架构图大多是 DAG（有向无环图），服务 A 调用服务 B，服务 B 再调用服务 C。对这种图，最合适的是层级布局：把节点按拓扑顺序排成一层一层，连线从上层往下层走，一眼能看出调用链。

我用了一个相对简单的方案，核心三步。

第一步，BFS 从所有入度为 0 的根节点出发分层，每个节点记录它所在的 layer 序号。第二步，同层节点按某种启发式顺序排列，比如按出度从大到小排，让分支多的节点靠近中间，连线交叉会少一些。第三步，根据 layer 和层内序号换算节点坐标。层与层之间垂直间距固定，同层节点水平间距固定。

function layoutByLayers(nodes, edges) { const layers = bfsAssignLayers(nodes, edges); for (let layerIndex = 0; layerIndex < layers.length; layerIndex++) { const nodesInLayer = sortByDegree(layers[layerIndex]); nodesInLayer.forEach((node, i) => { node.x = startX + i * horizontalGap; node.y = startY + layerIndex * verticalGap; }); } }

这个算法对树形结构效果极好，但对带环的图会失效——环导致 BFS 分层矛盾，节点可能出现依赖回边。我的处理方式是：先做一次强连通分量缩点，把环缩成一个“虚拟组节点”，布局完成后再展开。

5.2 再补一个力导向布局，用于无向图和有环图

层级布局解决不了无向图，比如数据血缘图、社交网络图。这类图我加了一个经典的力导向布局。

思路也很直白：节点之间互相有斥力，就像同极磁铁；相连的节点之间有弹簧拉力，把它拉向对方。每次迭代计算所有节点上的合力，按合力方向移动节点，多次迭代后图会自然展开成比较清晰的结构。

简化后的迭代核心长这样：

function forceLayout(nodes, edges, iterations = 300) { for (let iter = 0; iter < iterations; iter++) { for (let i = 0; i < nodes.length; i++) { for (let j = i + 1; j < nodes.length; j++) { applyRepulsion(nodes[i], nodes[j]); } } for (const e of edges) { applySpringForce(e.source, e.target); } } }

复杂度是 O(n²)，几百个节点没问题，上千个节点要引入空间索引优化。我这里没做深度优化，因为第一版的使用场景就是几百节点的图，力导向算法跑 300 次迭代也就几百毫秒，完全可接受。

5.3 “半自动布局”：给机器一个初始解，把微调权交给用户

纯自动布局有一个尴尬：算法排出来的结构虽然合理，但用户往往有自己的业务习惯，比如希望订单服务永远放在左上角，故障概率高的服务放中间。让用户去手动调每次自动布局的结果，体验很差。

我的做法是引入layout 状态标记。每个节点除了 x、y 之外，还有一个可选字段layout: "auto" | "manual"。自动布局运行时只移动layout: "auto"的节点，已经被用户手动拖过的节点保持不动。

界面上的呈现是：点击“自动布局”按钮时，系统重新计算未固定节点的位置，手工调整过的节点原地不动。如果用户想重新参与自动排布，可以选中节点再点击“解锁位置”，把它重新放归自动布局的管辖范围。这种“人和机器各让一步”的半自动方案，实际使用中的接受度比纯自动高很多。

6. 发布前踩过的三个坑：撤销栈深拷贝、图片导出白边、节点文本溢出

6.1 撤销重做：不可变快照的指针陷阱

撤销重做是编辑器的地基功能，实现时我踩了当天最刻骨铭心的一个坑。最初我把历史栈设计成保存“操作前”和“操作后”两个对象引用，结果因为 node 对象在拖拽时是原地修改的，历史栈里保存的引用指向同一个对象，一撤销就发现内容根本没变回去。

后来我改成不可变快照方案：每次操作完成后，把整个图数据的深拷贝压进历史栈。拖拽结束、连线完成、删除元素都会压入一次快照，撤销时直接恢复上一个快照。

这里要提醒一个性能点：对上千节点做全量深拷贝，每次可能耗时几十毫秒，连续拖拽时频繁压栈会让界面卡顿。我的优化是合并连续操作——拖拽过程中不压栈，只在鼠标松开后压一次；连续 3 秒内多次拖拽不同节点，可以合并成一个历史记录。这样历史栈既不会爆炸，用户撤销时也能达到预期。

6.2 SVG 导出 PNG 的白边和字体问题

导出图片是上线前临时加的需求，结果成了最折磨人的一块。第一版导出 PNG 时，生成的图片周围莫名其妙多了一圈白边，而且导出图中的文字和我画布上显示的字体不一样。

先说白边问题。SVG 转图片时，外层画布的尺寸和内部内容区域尺寸不一致是常事。我的 SVG 画布存在负坐标区域（节点可能在偏移后的原点左侧），但导出工具默认从 (0,0) 开始截图，于是空白区域被当作白色背景带进了图片。解决方法是导出前先计算所有元素的包围盒，把 SVG 的 viewBox 设置成包围盒，并统一将背景色设置为画布的背景色。

字体问题的原因则是浏览器在图片生成瞬间，还没来得及加载字体文件。我在导出前先写了一个字体加载检查：

await document.fonts.ready; await document.fonts.load('14px my-font');

等待字体准备完毕后再执行导出，文字样式就和画布一致了。如果你在别的场景遇到导出字体不对的情况，八成是这个原因。

6.3 文本宽度计算：节点长宽的“先有鸡还是先有蛋”

最后一个是细节问题，但直接影响初版体验。节点默认宽度是 140px，但业务数据里的服务名长度差异巨大。“订单中心”四个字放进去绰绰有余，“前端网关-生产环境-灰度流量入口”这种名字直接就会溢出节点边界，连端口位置都被挤乱。

最理想的方案是节点宽度根据文本自适应，但文本在哪里渲染取决于节点宽度，形成了一个依赖循环。我的解决办法是：文本渲染前先用离屏 canvas 测量文字实际宽度，根据宽度动态设置节点宽度，再执行布局和重绘。测量代码很短：

const canvas = document.createElement('canvas'); const ctx = canvas.getContext('2d'); ctx.font = '14px sans-serif'; const textWidth = ctx.measureText(label).width; node.width = Math.max(140, textWidth + padding * 2);

节点创建、文本变更、缩放级别变化三者都触发宽度重算。到现在我依然觉得这是性价比最高的一个功能——看起来不起眼，但对谁做编辑器的第一印象影响极大。

7. 结尾：给准备自研图编辑器的你一句实在话

整个项目做下来，我最深的体会不是渲染技术多难，也不是布局算法多复杂，而是数据模型的设计几乎决定了后续所有功能的难度。上线后回头审视，当时花费最多时间的三个细节——端口语义、不可变快照、半自动布局，全都是在数据模型阶段打下的基础。如果你也在筹划 diagram-design 类型的项目，我的建议是别急着写 UI，先用两天把数据结构聊透，把 JSON 协议定死，后面会顺很多。

最后再分享一个小技巧。图编辑器的画布一定要尽早暴露一个“开发者模式”，用来快速导入随机生成的大规模测试数据。我后来用这个模式跑过一次 2000 节点的压测，当场暴露了渲染卡顿和内存泄漏的问题。没有这批压力测试数据，这些问题可能拖到上线后才会炸出来，那时候代价就大得多了。