立项做 diagram-design 这套方案起因特别直接我们团队每周都要产技术方案文档画架构图、时序图、流程图的时间加一起占比高得吓人。一开始大家用画图软件拖框连线后来嫌效率低试过不少文本即图表的方案但总有不顺手的地方——要么图长太丑要么布局调整起来还要写一堆声明要么跟代码仓库的版本管理根本融不到一起去。后来我干脆自己做了一套以文本驱动为核心的图表设计工具代号就叫 diagram-design。这篇文章就把这套东西的设计思路、核心实现、实操流程和我们踩过的坑完整盘一遍干货偏多适合要在项目中引入高效作图方案的技术负责人也适合一个人扛下文档产出的全栈开发。1. 内容整体设计与思路拆解1.1 文本驱动到底在解决什么问题diagram-design 的核心思路是把图表的一切——元素、位置、连线、样式——都写成领域特定语言的文本。这句话听起来简单但背后解决的是传统画图工具的本质上没法解的痛点图表跟代码一样需要版本管理、Review、复用和自动化生产而拖动式的图形工具在这些维度上天然都是残缺的。先说版本管理。拖拽式的图形文件存下来的基本是一大堆坐标和样式字段两份文件落到一起文本对比基本上没有任何可读性。就算你团队里用的是在线协作画图板能看历史版本但粒度通常只到“谁在什么时候改了一笔”根本没有办法像代码提交那样精确到“新增了A服务到B服务的链路”这种语义级别。文本图表就完全是另一回事代码提交的差异即图表的差异Code Review 可以直接在文本层面做使用者看到的改动是逻辑层面的改动这对工程化协作极其重要。再说复用。图形工具里的元素复制粘贴进程内可以换个文件基本就废了。文本图表可以写函数、可以套模板、可以定义公共组件而且所有复用最终沉淀成文本之后是用 Git 管理的是全团队共享的。我们后面做的组件库本质上就是一个代码仓库根本不是图形素材库这一点决定了这套方案在上规模之后依然能保持可控。最后是自动化生产。文本描述图表意味着图表可以由程序生成架构读取代码仓库的拓扑结构能自动画系统依赖图接口文档的变更能定时触发渲染出服务调用关系图。这类“图跟着代码长出来”的能力拖拽式工具根本做不到。1.2 工具选型的四个关键取舍在设计 diagram-design 之前我其实把市面上主流的文本作图方案都拿真实验证过一轮。老实说如果某个现成工具完全满足需求我不会去重复造轮子。做这个取舍的过程本身也值得拿出来聊聊。第一个关键取舍是要不要基于既有 DSL 还是自己设计。直接基于成熟的方案好处是生态、社区解析器齐全但问题也很明显——它们的语法设计面对复杂建模场景有局限尤其是要表达“节点内部嵌套结构”和“面向侧边连线的自动布局”时写出来的文本又绕又难读。自己设计 DSL 意味着解析器、渲染器、布局引擎全得自己扛投入大但换来的是语法完全贴合我们的场景所有复杂图型都能用很直观的文本表达。权衡下来我选了后者因为骨架固定下来之后后续所有能力扩展都是往一个稳定的底座上加东西长期收益更高。第二个取舍是渲染目标。我先确定要渲染成 SVG因为 SVG 是文本格式可以嵌网页、可以转图片、可以批量处理还能直接进代码仓库做可视化对比。另一点很重要SVG 天生容易做主题切换白天黑夜模式只需要换一套样式文件不用重新生成数据。第三个取舍是布局方案。自动布局省手但不可控手动定位精度高但写法重。我的选择是折中连线全部自动走路由节点位置支持手动坐标和自动布局两种模式混用。复杂图里关键节点手动定位保证阅读逻辑其余节点交给算法排这样两边的优势都拿到。第四个取舍是语法里要不要内置可控的排版能力。很多文本图表工具对“文本如何换行”“字体大小如何在局部调整”几乎没有控制力导致生成的图虽然信息对但排版很丑。diagram-design 从一开始就把排版当一等公民块级、行级、字级的样式能力全部做进 DSL 里这条在后面做复杂大图的时候被证明是绝对正确的决定。1.3 整体架构的几张关键切片这套系统的架构并不复杂从抽象层面分四层。第一层是语法层负责定义 DSL 的词法与语法规则。第二层是解析层把语法文本解析成中间表示中间表示是所有后续处理的核心数据结构。第三层是布局层负责把中间表示中的元素映射成具体坐标、尺寸、连线路径既有确定性布局也有自动布局。第四层是渲染层把布局结果转成 SVG 输出同时承担主题映射、样式计算、支持导出。四层各自独立带来的直接好处是调试路径特别清晰。图表出问题先看解析层有没有报错再看布局层的坐标是否合理最后才去查渲染层的样式计算。不用像调试图形工具那样瞎猜省下来的时间非常可观。2. 核心细节解析与实操要点2.1 DSL 设计的核心场景与边界diagram-design 的 DSL 第一版只有四类元素节点、连线、泳道、分组。节点是最基础的表达单元可以是方框、圆框、圆角框、棱形等基础形状也可以进一步由子节点组合。连线表达点对点的关系支持箭头类型、线型、标签、路径走向。泳道是横向或纵向的隔离带常用于表达角色职责、流程阶段划分。分组是纯视觉的组织单元用于视觉拢聚相关元素。设计 DSL 语法时我给自己定的核心原则是“图即缩进”什么意思呢就是图表嵌套逻辑尽量用缩进表述出来避免靠大量成对的显式语法符号来包夹这样写起来顺手读起来也直观。比如定义一个包含子节点的节点直接在下方缩进写子节点解析器通过缩进堆栈自动完成归属判断。DSL 同时应该能做到局部表达不强求全图完整。在做复杂业务图时经常是先在纸上划好主体结构再用文本把主体搭出来细节后面补。所以语法层面节点定义和连线定义是独立的节点可以先只给名字不配样式样式后续补充声明即可这样增量式作图很顺畅。目前语法覆盖的场景包括系统架构图、调用链路图、时序图、流程图、部署图基本涵盖了日常文档八成的需求。剩下两成属于数据流图这种对建模能力要求更高的场景语法也能表达只是没有完全推出快捷语法糖后续可以迭代加进去。2.2 布局引擎的自动定位策略自动布局这块我一开始用的是通用分层方案适合 DAG 类图表的流向和层级排布。后来发现实际画图的时候分层布局的结果常常出现长连线跨大片空白区域。看的人得在大脑里额外做一次视觉连接很费劲比手动定位差远了。后来我把策略改成基于力的引导与分层方案混合。流程是先用分层得到主干方向再用力的模型在局部做松弛化调整把不必要的长线尽量折叠让整体空间利用率、边交叉次数、节点对齐质量三个指标综合最优。实现之后明显感觉大图的可读性上了一个台阶。实现布局引擎的时候最容易被忽视的是“文本量对尺寸的影响”。节点内文本长度不同节点宽窄差异会很大。布局算法必须让每一条连线的路由感知节点实际尺寸不能让连线穿进节点内部。我们在布局前会先做一次文本尺寸预估把所有节点的焊点坐标求出来再交给路由算法。这步做早了后期渲染很舒服做晚了一堆穿模。2.3 主题系统与样式继承层次主题能力是这类工具最容易做弱的地方。第一版实现里主题只有颜色配对的切换结果就是换肤可以但整张图的视觉层级、间距体系完全没办法调。后来我重构了样式系统分层提前确定好全局主题基线定义基础字体、基础颜色、基础间距。元素类型默认样式定义节点类型、连线类型、泳道类型的默认呈现。实例级样式声明针对具体某个节点或连线做局部覆盖。运行时动态注入样式。继承规则从全局到实例层层覆盖实现在渲染阶段计算出最终样式而不是在解析阶段就结算。好处是你改一个全局主题变量所有图全部跟着变但个别要突出的节点可以单独提亮提醒。这套体系的实用价值在落地后特别明显。我们把各团队的架构图全部纳入统一主题体系之后整套文档的观感直接拉齐了。以前每一份图都有自己的审美标准有的花哨到读起来吃力的程度现在配色范围被主题系统锁死阅读负担小了很多。2.4 可扩展机制和插件候选点diagram-design 预留的扩展机制主要是节点渲染自定义和布局算法替换。我们内部做了一个组件库核心围绕某些基础组件展开基础节点支持分组嵌套资源节点形似服务器或者数据库的“带底座”形状决策节点做成六边形带两侧锚点时序相关节点带激活条。组件库定义在文本里只是一行声明渲染层则对应一套代码实现既能表达业务语义又能拖进任何一张图里去。做插件化主要看主渲染流程中哪些点允许外部介入。我们定在四个口子供外部扩展解析、布局、渲染、导出。解析阶段的插件可以做自定义语法糖布局阶段的插件可以做行业专用布局比如组织架构用的树状纵向布局渲染阶段的插件可以做自定义形状的绘制导出阶段的插件可以加滤镜比如暗色模式、高斯模糊、手绘风。3. 实操过程与核心环节实现3.1 从零搭建一个最小可用的文本图表项目这一节面向第一次接触文本生成图表的读者从零讲怎么做。我的实际经验是别急着研究架构先让“文本变出图”这条最短链路跑通在此基础上再去加深。搭建顺序建议是这样的先把 DSL 语法解析器和 SVG 渲染的最小版本跑起来再补自动布局最后做主题系统。解析器我用的是经典的递归下降一边扫描一边产出中间表示。那时代码量不大几百行就能覆盖基础语法。渲染器最初只做了基础形状和连线的 SVG 输出拿浏览器直接开 SVG 文件就能看效果。自动化布局和自定义主题都是后面才接进来的因为第一版最重要的是能有效果有正反馈。真正决定项目能不能继往开来的反而是个不起眼的点命令行工具。我建议所有这类工具都必须给一个短平快的 CLI 入口功能就是吃饭喝水两件事读 DSL 文件并输出 SVG 文件、监听文件变化自动重渲。很多同事对折腾代码不感兴趣但给一条命令就能让图表即时刷新他们才会愿意用到日常工作中。3.2 工程配置与关键算法参数工程级落地时需要关注几个配置项。输出画布尺寸还可以但我更建议按内容自适应只有极少场景才需要强制固定尺寸。字体建议做全局基线配置字号建议按层级区分比如大标题、块标题、正文、辅助说明至少分出四级这样图才谈得上排版。布局相关需要给三个可调参数节点间距、分层间距、边的弯曲程度。布局算法里有两个参数调优影响最大一个是迭代次数另一个是收敛阈值。设太小布局结果都是乱的设太大渲染耗时翻倍对超大图完全没必要。我的实际经验是迭代次数在能力范围内设小一点渲染出来的图足够自然即可不要盲目调高。老的经典方案经常为了最大程度压缩交叉数写过强的优化循环结果一张 200 节点的图烘了十几秒实际使用者根本等不起。连线路由参数里有个信息我在参数选型时最警惕连线拐角半径。默认折线连接质感硬改成带圆角的折线之后图的气质立刻大变。最初版本圆角半径统一是 4后来全局调到 8整张图肉眼可见地舒缓下来。这种细节虽然不写进需求文档但直接影响观感和方案汇报的体感。3.3 实操演示用 diagram-design 画一张系统架构图下面用一张典型的微服务系统架构图来走一遍实际流程。第一步是我在脑内把图的核心结构拆出来客户端、网关、四个基础服务、两个数据存储、消息队列、监控告警链路。第二步是用 DSL 把结构落成文本先定义节点再定义连线先不着急写样式。第三步是跑自动布局看整体分布顺不顺眼重点观察有没有刺眼的交叉线和过于紧密的邻接区域有就手动调个别节点位置。第四步是套主题、调整局部样式的强调比如热点链路改成高亮配色下游依赖系统做成灰度风格明确视觉层次。第五步是导出 SVG 放进文档里并把 DSL 源文件提交到代码仓库。实际遇到最多的问题集中在标签位置。自动布局把连线标签放在线段中点但两条线挨得近时标签会重叠。我一般做法是支持手动指定偏移量把标签往边上推一点更智能的做法是根据连线角度自动算偏移方向必要时微调。这块做到扰动少之后图才敢拿出门。3.4 渲染导出链路嵌入文档体系文本图表最终还得落在文档流程里。目前我们的做法是在文档工程里加一个渲染任务文档里的 DSL 代码块统一编译成 SVG 后引到正文中加上哈希校验源文件不变就不重复渲染。用的人只需要在文档中写代码块提交后资源自动更新。图跟文天然同源杜绝两张皮。导出方面除 SVG 外还支持 PNG、PDF 两种最常用的格式。PNG 走浏览器无头渲染再截栅格图密度按 2 倍和 3 倍两档PDF 用于画布特别大的图默认分页或缩放能选。目前对完整长图的处理是导出时按渲染画布整体输出尺寸非常大时先在源 DSL 里按区域切分控制复杂度比较好。4. 常见问题与排查技巧实录4.1 解析阶段最常见的三类报错与处理第一类报错是括号括号错配。DSL 不支持花括号包裹嵌套结构而是用缩进表达但有些元素定义仍然会用到中括号做修饰在列表式的写法下很容易出现写一半少写一个右括号的情况。我的排查建议是格式化时打印语法树层级能直接看出哪个节点层级不对修起来快。第二类报错是节点引用了未定义的连接点。连线的端点写错字或者节点名引用错在解析阶段并不会立即报错因为解析器把连线当字符串存了。真正渲染时才在 SVG 里出现没有落点的线。后来在解析器里加了一层引用检查所有连线端点必须在已声明节点集合里才把这个坑填上。第三类报错是泳道归属冲突。某些节点同时出现在两个泳道的缩进范围里这种冲突解析器无法自动纠正。早期处理比较粗暴直接报错后来改成以就近缩进优先让用户能够快速看清错位。换言之这种点多出现在复制粘贴后缩进错乱用编辑器做一次格式整理基本能解决。坑位总结一句话缩进类问题能防御就防御引用类问题能硬校验就硬校验。这两个原则守住之后解析阶段的维护成本立刻从反复迷惑变成开源可查。4.2 布局引擎效果不符合预期时的调参顺序自动布局跑出来不好看先别急着骂算法按这个顺序排查先看中间表示的结构对不对节点之间的逻辑有没有建错其次看有没有超大文本节点它们是布局变形的大头再看局部密度是不是过高太高就先手动指定关键节点位置最后一招才是调布局参数。哪些参数值得调首先试节点间距和分层间距这是影响最大的两个接着试边的弯曲系数过大过小都会让人眼累别轻易改迭代上限除非你有明确的性能问题数据支撑。如果这些调完效果还是不理想那大概率是图本身的结构不适合自动布局手动定位反而是更优解。自动布局从来不是万能的。我以前也迷信算法总想把所有工作交给程序。后来发现某些业务图比如强调整体生命周期的时序类图分层布局只会让人看不明白手动按阅读顺序一列一列摆才是对的。工具应该给使用者选择权而不是替你假设一切。4.3 部分节点样式不生效的诡异问题有一段时间遇到一个怪问题全局主题该生效的地方全生效但个别节点再怎么声明样式都不生效而且不报错。查了半天发现原因是这些节点在首轮渲染后被缓存了推理渲染更新时直接把缓存结果取出来了完全没走样重算。缓存键当时只取了节点标识没取样式版本所以永远拿到的是老样式。修掉之后我把缓存策略改成全局失效任何一个主题变更都会清掉全量缓存而不是局部清理。代价是渲染速度掉一点但解决了灵异问题。类似情况很可能在带深度嵌套的组里复现建议如果遇到样式不更新先怀疑这层缓存。4.4 常见问题速查表现象排查方向解决建议文本渲染成码解析失败但没硬报错检查缩进与括号闭合看中间表示结构连线悬空无终点端点引用错名开启解析期引用硬校验自动布局线路交叉严重主干节点无优先级手动固定中间路径节点让算法排枝叶全局主题改了但局部不变节点样式覆盖导致的层叠冲突检查实例级样式覆盖声明超大图渲染极慢迭代次数过高调低迭代上限优先保证可达性单独调一个节点位置后连线错乱该节点未重新解析邻接关系手动定位后强制刷新邻接路由导出 PNG 模糊像素比设置太低按 2 倍、3 倍像素比重新导出文档里的图片刷新不更新资源哈希未失效清理文档渲染缓存重新提交源文件5. 项目延展、工程化沉淀与个人经验补充5.1 从单机工具到团队协作平台的演进diagram-design 最早就是我自己本地写写用后来一个组的人开始围观接着干脆接进了文档工程。演进到这个阶段之后真正值钱的就已经不是渲染引擎本身而是围绕它沉淀下来的一整套协作规范哪些图一定要走文本 DSL哪些图可以直接用外部素材导入统一主题清单谁来维护新组件进组件库要走什么评审。这根线拉长后图表这件事就从“个人表达”变成了“团队资产”。各条业务线画出来的架构图、链路图、时序图可以在同一条规范下互相拼装拿来直接做跨团队方案合并不再是各画各的、完全连不起来的图。5.2 给后来者的一些体感建议如果团队里也想搞类似的方案我的体感是别追求一步到位。第一先锁定 80% 最高频的作图场景做深做透不要去覆盖所有图形类型第二把 CLI 体验放在绝对优先级命令跑通了全组才会真用起来第三样式系统和主题能力要在项目早期就定型。主题这玩意晚了再改很痛苦全图所有样式表都会跟着牵连早改早点稳定。还有一条容易被忽略但非常真实要想清楚这套工具在未来维护周期里由谁来维护。独立工具最怕做的人走了之后没人接手文档、测试、示例图全要同步沉淀下来。我们后期花了大量时间补回归用例有了这套用例之后每改一版渲染器都能快速发现有没有把已经调好的图打回原形这一点救了很多次大版本升级。5.3 最后分享两个实战技巧结尾前再放两个小技巧。一是 DSL 里定义模板比想象中更好用把常见的部署结构抽成模板之后新业务接入时整个团队从画图两小时下降到改参数十分钟模板直接带动生产成本下降。二是做 SVG 导出时给根画布加一层基础的统一标识比如生成时间和源文件哈希图表出问题时能快速定位是哪一版源文件、哪一次的渲染结果。踩过不少坑之后我最深的体会就是这类工具的成败往往不在引擎本身而在于它能不能平滑地嵌入到团队既有的工作流里。剃刀锋利的前提是刀柄顺手diagram-design 让我把这个道理实打实验证了一遍。如果你也每天在和图表缠斗不妨从一套最小可用的文本图表方案做起先让自己从拖拽的重复劳动里解脱出来再一步步完善它。