说实话我第一次被架构图气到想砸电脑不是因为图画错了而是因为同一套系统在五个不同文档里被画成了五种完全不同的样子。有的用深蓝表示服务有的用浅蓝表示服务有的干脆用形状区分——圆形是服务、方框是数据库、菱形是消息队列。单独看每个文件都像那么回事放到一起就是一场视觉车祸。这个名为 diagram-design 的项目最初就是冲着这个痛点去的。它不是一个跟通用绘图软件抢饭碗的工具而是一套带约束的图表设计系统把节点样式、配色、字体、间距、连线规则都定义成一套显式的规范再配上渲染引擎和交互层保证团队里任何人画出来的架构图、流程图、时序图从结构到观感都像出自同一人之手。这篇文章把这件事从头到尾讲透为什么图表设计不光是审美问题设计规范到底怎么定才不会被一线工程师当成教条渲染方案选型时我踩过哪些坑自动布局和连线路由的核心思路是什么以及系统跑到生产环境之后暴露出来的三个隐蔽问题。无论你是在做技术文档体系、可视化平台还是内部运维大屏这份经验应该都能用得上。1. 为什么我决定做 diagram-design被架构图折磨之后的自救1.1 源头一份图纸五种画法项目启动的导火索很具体。某次系统重构需要把改造前的服务拓扑整理成一份交接文档我拉了好几份历史材料发现同一个模块在不同文档里的呈现方式完全对不上。有同事习惯用颜色区分环境生产环境用红色、测试环境用绿色另一个同事恰好相反绿色是生产、红色是告警。有同事用虚线表示异步调用有同事用带箭头的粗线表示调用关系还有一位直接在截图上用箭头乱画。等到要把这些图合并成一张总图的时候光统一符号语义就花了三天更别提重新排版对齐的时间。这让我意识到一个反直觉的事实画图工具从来不缺缺的是画图之前先定下的规矩。大部分团队用的绘图软件已经足够强大真正让图表变得混乱的是没有一个所有人都愿意遵守的视觉语法。1.2 这不仅是审美问题更是信息可信度问题很多人觉得图表难看只是品味差实际影响比这严重得多。图表的本质是一种信息压缩协议看的人默认遵循一套隐含规则颜色、大小、位置都是有含义的。如果同一个颜色在两张图里分别代表正常和告警读者的大脑就要额外花力气去做上下文切换更糟糕的是会产生误判——以为某个服务还活着其实颜色含义早就反了。所以 diagram-design 从第一天起就不是把图画好看的项目而是把图画一致的项目。一致的图表让团队沟通的成本显著下降审查架构方案时不再需要反复追问某个图例到底是什么意思。一张图值不值得信先看它是不是有自己的语法体系。1.3 明确边界diagram-design 不做什么项目启动前我列了一个不做清单这比功能清单更重要。首先不做自由画布式的绘图工具那样等于把规范问题又抛回给用户。其次不做复杂的建模功能不支持 UML 的完整语义只聚焦在架构拓扑、流程图、时序图这三类最常见的技术图表上。最后不做云端协作第一版就专注在渲染正确、布局稳定、交互顺手三件事上。把边界划清楚之后很多设计决策变得简单了不需要开放无限的样式自定义因为规范本身就是约束不需要支持任意形状因为常见的技术节点就是矩形、圆角矩形、圆柱、菱形、圆这几类。约束不是限制约束是让别人不需要重新思考。2. 设计规范先行一张图要讲清楚一件事先得约束它的视觉语言2.1 五层信息优先级我做的第一件事不是写代码而是把一张图里什么东西最重要排了个序。这个优先级排序决定了后续所有视觉规则。排在最前面的是结构关系——谁依赖谁、谁调用谁这是架构图的第一信息。其次是节点身份——这个方块是服务、数据库还是队列。再次是状态与告警然后是环境归属最后才是装饰性信息。这个排序对应到视觉层级上信息层级视觉手段原因结构关系线的粗细、箭头人眼对线条方向最敏感节点身份形状轮廓形状可以在不依赖颜色的情况下区分类型状态告警颜色颜色是强信号适合表达异常不能滥用环境归属背景色块分组大面积底色是弱信号适合做分区装饰信息字号、圆角、阴影全部弱化避免干扰前四层这个优先级直接影响配色总量越靠上的层级能用的视觉变量越少但越醒目越靠下的层级变量越多但必须克制。2.2 颜色体系保守是对的颜色是最容易出问题的部分。我一开始拟了一套八种强调色用来区分子模块后来在真实场景里一测就发现完全行不通——一张 50 个节点的架构图里出现八种彩色视觉上直接爆炸。最后定下来的是弱化 单点强调策略所有节点的默认状态都是同一种中性色比如浅灰底加深灰边框只有出现告警、异常、版本迁移这类少数状态时才上彩色。整张图里同时出现的高饱和色不超过两种。这样做的好处是读者扫一眼就能知道图里有什么不对劲而不是被一片彩虹色淹没。另一个必须考虑的是色盲可读性。红绿色盲是最常见的情况所以告警和正常的对比不能只靠红绿必须叠加形状或图标。我在规范里定了一条死规则任何仅依赖颜色的信息都必须有第二重编码。这一点在技术评审时被挑战过但真实用户里的反馈几乎一边倒——没人愿意为了一张图去分辨两种难以区分的红色。2.3 形状、字体和间距的硬规则形状语义我定成了一张对应表矩形组件矩形加底部分隔线表示存储圆柱形是数据库菱形是消息队列圆角矩形是外部系统圆形是网关或入口。这套语义一旦定下来就不再允许任何人随便改动连我都不能。因为它要成为团队的公共语言。字体规则的颗粒度比想象中细。不止是字号还包括节点标题用什么字重只有一级节点才允许加粗标签超过一定长度自动截断加省略号但不允许缩小字号来硬塞进节点连接线上永远不放文字调用名放在连线中部的偏移侧避免影响线段走向。间距规则我参考了栅格设计里的 8pt 系统。画布上的基础网格是 8 像素节点间的默认间距是 16 或 24 像素连线拐弯处的圆角半径统一是 4 像素。这样整套图在视觉上会有一种不太容易察觉但非常舒服的整齐感——因为所有尺寸都在同一个等差数列上。3. 渲染方案选型SVG、Canvas 还是混合方案设计规范只是第一步真正工程化的难点在渲染层。我在做的过程中把三种主流方案都实测了一遍结论可能跟不少人的直觉不太一样。3.1 三种路线的实测差异方案500 节点渲染耗时交互实现成本缩放清晰度适用场景纯 SVG首屏约 180ms低DOM 事件天然支持矢量无限清晰中小规模图、需要丰富交互纯 Canvas首屏约 60ms高要自己算碰撞和拾取位图放大需要重绘大规模图、重性能场景SVG Canvas 混合视分配策略而定最高但灵活性最好分层处理大型图且需要细节交互纯 SVG 的问题是节点数量一上来就卡。我用一个开源图编辑库做了个原型500 个节点、800 条边的时候拖拽已经明显掉帧原因不在于绘图本身而在于 DOM 节点太多事件绑定和样式重算都在抢主线程。纯 Canvas 性能好得多但所有命中检测、选区框、吸附逻辑都得自己实现工作量翻倍还多而且放大到边界时文字会糊。3.2 为什么我选了 SVG 为主、Canvas 为辅最终方案是一个分层混合结构静态背景层和数量庞大的连线用 Canvas 绘制节点和交互热点用 SVG 承载。这样做的理由很朴素——节点是用户点击、拖拽、编辑的主要对象用 SVG 可以免费获得一套完整的事件系统和样式能力连线只是视觉辅助用 Canvas 画能省下大量 DOM 开销。这个选择的代价是架构复杂度上了一个台阶。两个渲染层需要共享一套坐标系和更新机制任何一个层的滚动、缩放、偏移不同步画面立刻就会撕裂。所以我在设计时把所有坐标变换统一收敛到一个 Camera 对象里SVG 层和 Canvas 层各自读取同一份 transform 数据避免出现两个世界的状态。3.3 节点渲染的最小实现渲染层里最核心的代码其实是节点绘制这一个函数。SVG 版的最小实现大概是这个思路function renderNode(node: DiagramNode): SVGElement { // 所有节点都挂在一个统一命名空间下便于后续批量查询 const g document.createElementNS(svgNamespace, g); g.setAttribute(data-node-id, node.id); // 形状由类型决定但尺寸、圆角来自设计规范对象 const shape document.createElementNS(svgNamespace, rect); shape.setAttribute(x, String(node.x)); shape.setAttribute(y, String(node.y)); shape.setAttribute(width, String(node.width)); shape.setAttribute(height, String(node.height)); shape.setAttribute(rx, String(style.cornerRadius)); // 填充色统一走主题系统业务代码不许直接写死颜色 const fill getThemeColor(node.status); shape.setAttribute(fill, fill.background); shape.setAttribute(stroke, fill.border); shape.setAttribute(stroke-width, String(fill.borderWidth)); g.appendChild(shape); // 标签 const text document.createElementNS(svgNamespace, text); text.textContent node.label; text.setAttribute(text-anchor, middle); text.setAttribute(dominant-baseline, central); const cx node.x node.width / 2; const cy node.y node.height / 2; text.setAttribute(x, String(cx)); text.setAttribute(y, String(cy)); g.appendChild(text); return g; }这段代码看起来简单但埋了两个重要设计一是所有样式都从主题系统读取业务层永远不写具体色值二是每个节点挂上>