diagram-design 是我最近大半年一直在维护的一个内部项目简单说它是一套面向技术文档、架构评审和日常协作的图表设计系统。最初它只是某个工具里的几个 SVG 图元后来不断被同事复制到白板、文档、PPT 里颜色、线型、箭头口径越用越乱我才意识到需要把这一层抽出来当成一个正经项目做。这篇文章不聊理论定义也不放远景规划只讲我实际怎么拆解需求、定规范、写渲染层以及在落地过程中踩过的坑。如果你也在维护团队文档里的架构图、流程图、时序图或者想给自己的项目做一套“图的设计规范”这篇应该能给你一些能直接用的思路。先说结论diagram-design 不是又一个绘图工具而是一层很薄的“设计约束层”。它把图的构成拆成几个固定元素给每个元素绑定明确语义再提供一套从数据到图形的渲染路径。这样一来团队里任何人画同一类图出来的结果都是同一套语言更关键的是图能被结构化保存能被代码评审能随项目持续演进。下方我按完整的设计和实践顺序展开尽量把每一步的“为什么”也一起讲清楚。1. 为什么我决定从零写一个 diagram-design而不是继续用白板工具1.1 看起来大家都在画图其实大家画的是“不同的方言”最早让我决定动手的原因不是某张图画得不好看而是整个团队的图完全没有“共同语言”。同样一张系统架构图有人用矩形表示服务有人用圆角矩形有人直接贴一张产品图标同样是箭头有人用它表示数据流向有人表示调用关系还有人只是表示“下一步大概是这样”。当这些图出现在同一个评审文档里时读者每看一张新图都要先猜一遍图例评审时间被大量浪费在“这张图里这个方块是什么意思”上。这种问题在代码里很难出现因为代码有类型、有命名规范、有 linter 强约束到了图上一切约束都消失了。diagram-design 的第一个目标就是把代码里天然存在的“类型约束”移植到图里。每个节点得有明确种类每条边得有明确关系每种关系和种类对应唯一的视觉样式。这不是为了限制画图自由而是让读图的人不需要反复重新学习。我还发现很多团队不是不想统一而是没有地方统一。大家手里只有白板软件的画布和一套默认图形库默认图形库是为“通用绘图”设计的根本不知道你的矩形代表服务还是数据库。你可以在文档里写“图例蓝色矩形代表服务”但写归写下次画新图的时候大家还是会凭心情换颜色。所以必须有代码层面的强制映射而不是文档层面的建议。1.2 白板工具带来了两个假象白板工具给人两个错觉第一是“画得快”第二是“够用”。画一块、拖一根线确实快但要维护它就麻烦了。白板图画完之后导出成图片放进文档图的内容就和代码仓库断开了。下一次告警链路改了代码改完了图没人记得更新等下一次评审时图还停留在三个月前的状态。更隐蔽的问题是协作。几个同事在同一张白板图上改来改去最后到底哪个版本是对的没人说得清。图一旦不是文本就无法 diff无法 review无法追溯。而 diagram-design 把图表模型定义成结构化数据导出 SVG 只是其中一个产物。图源本身是 JSON是 TypeScript 对象是可以进 Git 的文本文件。图改了什么谁改的为什么改全都能在提交历史里看到。这个差异用下来之后才知道有多重要。我并不是说白板工具不能用我自己也用它做头脑风暴画一些探索性的草图。但一旦图要进文档、进评审、进长期维护就必须有“确定的表达方式”和“可管理的源文件”。diagram-design 解决的就是从“画完一次丢一边”到“像代码一样持续演进”的转变。1.3 设计系统的定位不是工具而是“规范渲染器模板”如果只做一套规范那又回到了写文档的老路没人会严格执行。如果只做一个绘图工具那和现成白板软件没有区别团队不会因为多了一个内部工具就统一表达。我最终把 diagram-design 定位成一个三层结构最底层是一套设计规范定义颜色、形状、线型、间距的取值中间层是一组渲染器负责把结构化的图模型转换成 SVG最上层是模板系统针对架构图、流程图、时序图等场景预置好图元和关系类型。这样设计有一个直接好处改动规范时不需要改每一张图。以前某个同事把所有“外部系统”画成灰色块另一个人画成带边框的方块现在只需要在规范里定义external节点长什么样所有引用这个节点的图都会自动更新。规范是唯一事实来源渲染器只是执行者。正如一个组件库里统一了 Button 的样式自然也应该统一 Diagram 的节点、连线、标注diagram-design 就是把组件库的思路用在图上。有人会问这样是不是限制了创造力我的回答是图是给人看的首先得能看懂。在“能看懂”的前提下再谈美观和自由。内部使用场景里我们对一张图的评价应该是“信息是否清楚”而不是“画得是否独特”。这套三层结构能同时保证下限和可演进性。2. 图元体系与视觉语义让每一根线都有明确身份2.1 先把图元收敛到五类而不是追求一百种画法很多绘图工具喜欢提供大量图形圆角矩形、六边形、平行四边形、圆柱、云朵、星形……看着丰富用起来全是负担。人脑对图形记忆有限图里出现超过十种形状读图就要频繁查图例。我把 diagram-design 的基础图元收敛成五类节点Node、容器Container、连接线Edge、端口Port、标注Annotation。每一类承担一种基础语义。节点的视觉形态按业务类型再细分比如服务用矩形存储用圆柱侧方带一条曲线外部系统用圆角矩形决策用菱形标注用椭圆。这些细分不是随便拍的而是尽量遵循人们读图的直觉习惯存储像硬盘决策像岔路外部系统不强调内部结构所以用圆角。五类图元覆盖了技术文档里绝大多数场景真遇到特殊场景可以在模板层临时扩展而不是一股脑堆进核心库。我给五位图元做了固定映射表平时的使用频率极高图元类型常见视觉形态核心语义典型使用场景节点矩形、圆角矩形、椭圆表示一个独立实体或处理步骤服务、模块、步骤、数据源容器大圆角矩形、虚线大框表示逻辑边界或分组子系统、业务域、部署环境连接线实线/虚线、带箭头表示实体之间的关系调用、数据流、异步消息、依赖端口小方块、短线段表示连接线的挂载点组件对外接口、服务监听端口标注矩形折线引线补充解释性信息说明、异常分支、备注这种收敛带来一个很大的好处读图者只需要理解五个抽象概念具体形态只是这五个概念在不同场景下的投影。团队新成员看到一张陌生图先找“哪些是节点哪些是连接线”就能快速拆解。2.2 连接线是图表里最容易被忽略的语义层节点画错了一眼就能看出来连线画错了却经常被忽略。但真正传递图的信息的往往是连接线。diagram-design 对连接线做了三组硬性规则线型、箭头、颜色。线型决定关系强弱实线表示强关联比如同步调用虚线表示弱关联比如异步消息、可选路径、未来计划。箭头决定方向但方向不仅仅是“指向”还包括“单向还是双向”以及“箭头附近是否需要语义标注”。颜色只能来自语义色板不能用于纯装饰。举一个实例在告警链路图里同步 API 调用用蓝色实线箭头指向被调用方异步消息用绿色虚线箭头指向消费者失败回退用红色实线并在靠近起点处加一个X标注。如果只用颜色区分图纸打出来是黑白的或者团队里有色弱成员信息就丢了。所以线型和箭头承担第一层区分颜色只承担第二层增强。这是很重要的可访问性考虑。我还规定了一条“连接线禁则”不允许在一条线上同时表达两种关系。比如“调用且回传数据”这种语义不能画一条线拍脑袋解决必须拆成两条边或者使用双向箭头并标注清楚。否则读者会产生“到底是调用还是数据流”的疑问。凡是让读者犹豫的地方都是图要返工的地方。这条规则在评审时非常好用每次只要有人画了一条混合语义的线我都会请他把语义拆开。2.3 布局和间距好的图应该不用解释就能读图元定义解决“是什么”布局和间距解决“看起来怎么样”。我在布局上定了几条基础规则网格基数是 8px所有节点坐标、宽度、间距都取 8 的倍数节点最小宽度设置为 120px最小高度 40px同级节点之间水平间距不小于 40px父子容器之间垂直间距不小于 60px容器内部节点距容器边界至少 20px。这些数字不是玄学而是来自一个朴素的目标文字不拥挤、箭头不叠加、放大缩小不碎掉。不同类型的图布局策略完全不同。系统架构图通常采用自上而下的层次布局上层是入口下层是依赖流程图也适合线性布局强调步骤顺序而服务依赖关系图在探索阶段可能用到力导布局但正式文档里我不会用。力导布局每次渲染出来的位置都可能不一样造成 diff 噪音评审时很难看清“这次到底改了什么”。所以我把力导布局定位成“探索辅助”把层次布局定位成“文档标准”。布局参数统一收进设计令牌design token而不是散落在代码里。我在 renderer 里不写死任何间距所有尺寸从 token 表里取。这样换主题、改密度时只要改 token 文件所有图会同步变化。实测下来这么做最大的好处不是“省事”而是“敢改”。以前我改个间距要翻很多文件现在改 token 一个地方跑一遍快照测试就知道影响范围。3. 从规范到代码diagram-design 的模型、渲染与模板3.1 用 TypeScript 类型把图形语义钉死规范要落地第一步是把它翻译成类型定义。我在 diagram-design 里定义了一个最核心的图模型节点、边、布局三者分离。节点的kind字段绑定图元种类边的relation字段绑定关系语义渲染层根据这两个字段决定形态和样式。下面是简化后的模型type DiagramNodeKind | service // 服务/模块 | storage // 存储 | external // 外部系统 | decision // 决策 | annotation; // 标注 interface DiagramNode { id: string; kind: DiagramNodeKind; label: string; x?: number; y?: number; width?: number; height?: number; parentId?: string; // 容器归属 } type DiagramEdgeRelation | call // 同步调用 | data // 数据流 | async // 异步消息 | fallback; // 失败回退 interface DiagramEdge { id: string; source: string; target: string; relation: DiagramEdgeRelation; direction?: forward | bidirectional; label?: string; } interface DiagramModel { nodes: DiagramNode[]; edges: DiagramEdge[]; layout?: layered | flow | force; title?: string; }有了这个模型之后一张图就是一个 JSON 对象。节点的位置可以手动给也可以交给布局算法算但 kind 和 relation 是必填的不允许出现“未定义关系”的边。这个约束看着简单却把团队从“画得爽”拉回了“表达清楚”每创建一条边都要先选择它到底属于哪种关系犹豫本身就是信息不足的表现。3.2 渲染层一图一 JSON多场景复用模型定了渲染层就相对机械。我在渲染层维护了一个 kindConfig 表每个 kind 对应一个 shape 生成函数和一套默认样式一个 relationConfig 表每个 relation 对应线型、箭头、颜色。核心渲染流程非常短就是遍历模型、查配置、生成 SVGfunction renderDiagram(model: DiagramModel): string { const adapter resolveLayout(model); const nodeShapes model.nodes.map((node) { const shape kindConfig[node.kind].createShape(node); return shape; }); const edgePaths model.edges.map((edge) { const path relationConfig[edge.relation].createPath(edge, adapter.pointOf); return path; }); return serializeToSVG({ nodes: nodeShapes, edges: edgePaths }); }我把输出格式定为 SVG而不是 Canvas。原因有几个文档里的图要能被选中、复制、导出高清 PNG 或 PDFSVG 是矢量缩放不糊SVG 还能嵌入链接和可读性描述对无障碍更友好。Canvas 在复杂交互场景有性能优势但我们内部图的规模大多在几十到几百个节点以内SVG 完全够用。如果你的图规模到了几千个节点那应该先拆分图而不是换渲染引擎。另外我在渲染层做了一个非常重要的决定输出结果必须是确定的。同一个 DiagramModel不管渲染多少次生成的 SVG 字符串必须完全一致。这让我们能对渲染结果做快照测试每次改动规范或布局逻辑跑一遍测试就知道哪些图的输出变了。这个能力对持续演进很关键否则没人敢重构布局代码。3.3 业务接入不同图不是不同工具而是不同模板团队里常见的架构图、流程图、时序图表面上是三种图其实它们共用同一套核心图元和渲染路径只是“允许出现的元素”和“布局方式”不同。我把这种差异建模成模板模板定义允许的节点种类、边关系、默认布局和常见配置。系统架构图模板只允许service、storage、external节点关系只允许call和data默认布局是自上而下。流程图模板允许decision节点关系允许data但额外要求每一步有明确的顺序。时序图模板比较特殊它需要垂直 lifeline 和消息线我在五类基础图元里加了“端口”来承载 lifeline 的端点消息线复用连接线语义。这样做避免了为每种图单独实现一套渲染器新增图类型只需要新增模板。接入业务场景时使用方不会直接接触 SVG而是写一份图数据。以系统架构图为例{ title: 告警链路总览, template: architecture, nodes: [ { id: producer, kind: service, label: 告警产生器 }, { id: queue, kind: storage, label: 消息队列 }, { id: consumer, kind: service, label: 告警消费者 } ], edges: [ { id: e1, source: producer, target: queue, relation: data, label: 写入 }, { id: e2, source: queue, target: consumer, relation: async, label: 消费 } ] }这份 JSON 既是一张图又是一段可评审的数据。它能进 Git能 diff能写单测能挂在文档站点上动态渲染。使用方完全不需要知道图长什么样只需表达业务语义diagram-design 负责把它变成符合规范的一张图。4. 实操过程复盘从手工调 SVG 到自动布局我踩过的坑4.1 先手工打磨三张标准图再回头抽象规范我一开始犯过很多“从零造轮子”的人都会犯的错想直接写一个通用引擎支持所有图。结果模型设计得越来越复杂渲染器迟迟没跑通。后来换了个方法我先用手工 SVG 打磨三张标准图一张系统告警链路架构图一张订单处理流程图一张认证时序图。这三张图覆盖了内部 80% 的文档场景我把它们画到自己满意为止然后开始“逆向提取”规范。逆向提取的过程很朴素。我反复问自己三张图里哪些元素是重复出现的哪些样式是“感觉对了”但我说不清理由的比如告警链路里服务节点都是矩形存储节点都是圆柱这是因为它们语义不同时序图里的消息线全部是水平实线因为位置本身已经表达了顺序线型不需要再加强。这些观察最终变成了 kindConfig 和 relationConfig 的初始数据。所以我的建议是不要一开始就做通用框架先做出几个高质量样例再从样例里抽规律。样例还不够多时宁可暂时用硬编码写死某张图也不要急着扩展模板。等第二个相似场景出现时再考虑提取公共配置。这个节奏能避免过度设计也能让项目最早期的使用价值跑起来。4.2 自动布局最大问题不是算法而是约束自动布局是我在这个项目里投入时间最多、也最有收获的部分。最早我天真地以为接一个成熟的力导布局库把节点坐标扔进去图就自动好看了。结果力导布局每次跑出来的位置都不一样同一张图在两次渲染里节点位置漂移严重评审时的 diff 几乎没法看。于是我把力导布局降级为“仅探索模式”真正用于文档的是分层布局。分层布局听起来简单但要做对约束并不容易。比如同一层节点必须顶部对齐而不是中心对齐拿到坐标后所有数值必须取整到 8px 倍数否则导出到高 DPI 图时会出现半像素虚边跨层边不能穿过第三层节点否则图会变得像一团乱麻。我花了不少精力处理“边绕障”最终方案是允许边在某些情况下走“容器边缘通道”而不是强行从节点中心穿过去。自动布局的参数也需要和设计 token 联动。节点间距、层间距、对齐方式的变动都会影响整个图的观感。我在布局模块里设置了默认参数层间距 60px同层节点水平间距 40px容器内边距 20px边沿对齐误差不超过 1px。这些参数通过 token 暴露出来模板可以覆盖核心渲染器不感知具体数值。这样做之后不同模板即使布局风格不同底层样式依然一致。4.3 三个印象最深的坑第一个坑是虚线导出变实线。当时渲染层用 CSS class 控制虚线浏览器里显示正常但导出 PDF 时部分阅读器不支持外部 CSS 的解析虚线和实线全混在一起。后来我把所有图形属性直接序列化到 SVG 元素的style上不再依赖全局样式表。问题解决了但也让我意识到图表输出要考虑“最终消费者”PDF、图片、打印都是消费场景渲染结果不能依赖宿主环境。第二个坑是节点文字过长。布局算法先算节点位置再接文字内容结果文字一长就把节点撑大撑大之后相邻节点就碰撞。修复方式是做两件事文字测量必须在布局前完成计算节点实际尺寸时提前考虑字体、字号、最大宽度超长内容允许自动换行或截断但不允许无限制增加节点宽度。这个顺序看着不起眼但一旦反了几乎所有布局 bug 都会冒出来。第三个坑是深色模式漏色。我一开始把节点颜色换成了深色背景下的浅色但连接线的颜色没有走 token仍然是硬编码的深蓝色。结果深色模式下整条线几乎看不见评审到一半大家才发现。从那以后我立下规则渲染器里禁止出现任何硬编码颜色所有颜色必须从调色板 token 取。我还在 CI 里加了一个简单检查直接扫描代码里是否出现十六进制颜色文本出现就报错。这个检查救了很多次场。5. 日常使用中的排查技巧与一个长期建议5.1 从图表现象快速定位问题图不会像代码一样抛异常出了问题往往很安静但在评审时突然暴露。我整理过一张排查速查表团队碰到类似问题可以直接照做现象大概率原因排查手段节点重叠布局时没有考虑文本宽度检查节点尺寸是否在布局前计算箭头指向模糊关系类型语义重叠确认使用的是 call 还是 data导出 PDF 后虚线变实线样式依赖外部 CSS改为内联属性并跑一次导出测试深色模式下线条看不清存在硬编码颜色全局搜索十六进制颜色值用模板生成的图与预期偏差大模板里覆盖了默认参数查看模板的 token 覆盖范围一张图渲染超过 2 秒节点数过多或力导布局未收敛拆图或改用分层布局排查的顺序也有讲究先看数据再看配置最后才看渲染器。因为大部分问题不是渲染器写错了而是图模型里的语义没对齐。我给团队定的习惯是看到一张“怪图”第一步打开它的 JSON 源文件检查 id 是否对应、节点 kind 是否合理、边 relation 是否和描述一致。数据没问题再去看布局参数和 token。5.2 把图谱纳入代码评审因为 diagram-design 的图源是 JSON它天然适合进入代码评审流程。每次有人改了图提交里会有清晰的 diff新增了节点、改了关系类型、移动了坐标。评审图时我很少看“好不好看”而是看三个问题节点种类对不对语义类型合理不合理坐标变化是否必要。这套标准比主观审美靠谱得多。我还要求每张图附带一个“图说明”字段记录这张图的阅读目标和维护人。比如readme: 展示告警从产生到消费的主链路不含降噪逻辑这个字段不会渲染出来但会跟着 JSON 进仓库。很长时间之后有人翻到这张图即使不清楚上下文也能从字段里知道它想表达什么。这也是我最建议大家抄走的一个实践成本极低回报极高。5.3 我最舍不得删的一个小技巧最后分享一个很小但非常实用的技巧在没有精力做完整自动布局之前先给业务方提供“显式坐标 对齐辅助函数”。也就是说允许使用者手动指定节点坐标同时提供alignLeft、alignCenter、distributeVertically这类辅助操作。大部分中小型团队的图节点数量没那么大手动摆位置完全可接受辅助对齐函数能保证“看起来整齐”但不会像力导布局那样位置漂移。我一开始总想一步到位做自动布局后来才意识到稳定可控的“手动坐标 辅助对齐”比不稳定的自动布局更适合日常文档场景。自动布局当然要加但应该作为增量能力逐步引入。先把展示结果做确定再把坐标计算做智能这个顺序反过来很容易失控。diagram-design 现在支持两种模式默认用显式坐标加对齐辅助只有当图规模明显偏大时才启用分层布局自动计算。我现在的习惯是遇到任何稍微复杂的逻辑先打开一个空白的 DiagramModel把节点和关系写出来。写的过程其实就是整理思路的过程很多时候图画完问题已经解了一半。diagram-design 最终给我的不是一张好看的图而是一套能把“想不清楚”变成“看得明白”的表达框架。