1. 从“diagram-design”这个标题里能读出什么
第一次看到“diagram-design”这个标题，我脑子里蹦出来的不是某个具体工具，而是一类非常典型的需求场景：有人想把脑子里那张“说不清楚但就是存在”的结构图，变成一张能直接放进文档、能给别人讲明白、还能反复修改的图。这个需求听起来简单，但真正动手做过的人都知道，它比写代码还折磨人。
我接触过不少做技术文档、产品方案、教学材料的朋友，他们最常抱怨的一句话就是：“画图两小时，改图一整天。”为什么会这样？因为大多数人在画图这件事上，一开始就选错了路径。有人用绘图软件硬拖控件，有人用代码生成但不会调布局，有人干脆截图拼贴，结果就是图能看，但没法维护，更没法复用。
“diagram-design”这个标题，我理解它指向的核心是图的设计与生成，而不是单纯地“画一张图”。它涉及三个层面：第一，图的语义结构怎么定义；第二，图的视觉呈现怎么控制；第三，图的维护和迭代怎么低成本完成。这三个层面缺一个，最后都会变成“一次性图”，用完就废。
这篇文章适合谁看？如果你正在做技术方案、写论文、整理知识体系、做产品原型说明，或者你是一个需要频繁输出结构化图表的开发者、产品经理、技术写作者，那这篇内容应该能帮你省下不少时间。我会从实际踩坑的角度，把“diagram-design”这件事拆开讲清楚，包括工具选型的逻辑、布局控制的技巧、以及我实测下来最稳的一套工作流。
提示：本文不涉及任何具体商业工具的推广，所有提到的方案都是基于通用能力和实际使用体验的总结，你可以根据自己的环境灵活替换。
2. 为什么“画图”这件事总是变成“改图地狱”
2.1 大多数人把“画图”当成了“画画”
我见过太多人打开绘图工具的第一反应是：先拖一个矩形，再拖一个箭头，然后手动对齐。这种做法在画第一版的时候没问题，但一旦需求变了——比如要加一个节点、改一个层级、换一种布局方向——整个图就崩了。因为你画的是“像素”，不是“结构”。
真正高效的 diagram-design 思路是：先定义图的语义结构，再让工具去计算布局，最后只调样式。这就像写代码，你先定义数据模型，再写渲染逻辑，而不是直接操作 DOM。图的语义结构通常包括：节点、边、分组、层级关系、方向约束。把这些定义清楚之后，布局应该是自动算出来的，而不是手拖出来的。
我自己的经验是，凡是需要手动对齐超过三次的图，基本都值得换成声明式的方式重做。因为手动对齐意味着你在用眼睛做计算，而眼睛做计算的结果就是：改一个地方，全图重来。
2.2 布局失控的根源是“没有约束”
很多人画图时觉得“自由摆放”是优点，但实际上，自由摆放是维护成本最高的方式。真正好维护的图，一定是有约束的。比如：从左到右的层级关系、从上到下的流程关系、环形依赖关系、树形展开关系。这些约束一旦定义好，布局引擎就能帮你算出每个节点的位置。
我举个例子。假设你要画一个系统架构图，包含接入层、逻辑层、存储层。如果你手动摆，三层之间的间距、每层内部的节点对齐，全靠肉眼判断。但如果你用声明式的方式定义“这三层是垂直排列，每层内部水平排列”，那布局引擎会自动帮你算好间距和对齐。你只需要改样式，不需要改位置。
这就是为什么我在做 diagram-design 的时候，第一件事永远是问自己：这张图的约束是什么？是层级、是流程、还是依赖？约束定义清楚了，后面的工作就顺了。
2.3 改图成本高的真正原因是“图和源分离”
还有一个常见的坑：图和源文件分离。比如你用某个在线工具画了一张图，导出成 PNG 放进文档。过了一个月，需求变了，你要改图。这时候你发现：源文件找不到了，或者源文件在另一个工具里，格式不兼容。于是你只能重新画一遍。
这个问题在技术文档里特别常见。我的做法是：图的源文件必须和文档放在同一个版本控制体系里。如果图是用代码生成的，那代码就是源文件；如果图是用某种声明式格式描述的，那这个描述文件就是源文件。只有这样，改图才不是“重画”，而是“改几行描述”。
我实测下来，最稳的方式是用文本描述图的结构，然后用工具渲染成图。这样图可以进 Git，可以 diff，可以 review。改一个节点，只需要改一行文本，而不是打开绘图软件拖半天。
3. 声明式 diagram-design 的核心工作流拆解
3.1 第一步：把图的结构写成文本
声明式画图的第一步，是把图的结构用文本描述出来。这个描述可以是某种 DSL，也可以是某种通用格式。关键是要把节点、边、分组、方向这些信息表达清楚。
我通常会用类似这样的结构来描述一张图：
方向：从上到下 分组A：接入层 - 节点1：客户端 - 节点2：网关 分组B：逻辑层 - 节点3：服务A - 节点4：服务B 分组C：存储层 - 节点5：数据库 - 节点6：缓存 边： 节点1 -> 节点2 节点2 -> 节点3 节点2 -> 节点4 节点3 -> 节点5 节点4 -> 节点6这个描述本身不涉及任何视觉样式，只描述结构和关系。这样做的好处是：结构是稳定的，样式是可变的。你可以用同一份结构描述，渲染成不同风格的图，比如正式文档风格、演示风格、手绘风格。
我试过很多次，把结构和样式分离之后，改图的效率至少提升三倍。因为大部分改图需求其实是改结构，而不是改样式。结构改一行文本，样式基本不用动。
3.2 第二步：让布局引擎去算位置
结构描述好之后，下一步是让布局引擎去算每个节点的位置。这一步的关键是选对布局算法。常见的布局算法有：层次布局、力导向布局、环形布局、网格布局。不同的图适合不同的布局。
层次布局适合有明确上下级关系的图，比如架构图、流程图、组织图。力导向布局适合关系复杂的网络图，比如依赖关系图、知识图谱。环形布局适合展示循环关系。网格布局适合展示并列关系。
我自己的经验是：大部分技术图都适合层次布局。因为技术图通常有明确的层级关系，比如从客户端到服务端到存储，从父模块到子模块。层次布局能自动处理对齐和间距，出来的图很规整。
如果你用的是支持多种布局的渲染工具，可以在结构描述里指定布局方向，比如“从上到下”或“从左到右”。方向的选择取决于图的宽度和高度比例。如果节点多、层级少，从左到右更合适；如果节点少、层级多，从上到下更合适。
3.3 第三步：样式只调一次，不要反复调
布局算好之后，最后一步是调样式。样式包括：节点颜色、边框、字体、箭头样式、间距。我的建议是：样式只调一次，然后固化下来。不要每张图都重新调样式，那样效率太低。
具体做法是：定义一个样式模板，所有图都用这个模板。模板里定义好主色、辅色、字体、圆角、阴影这些基础样式。然后每张图只需要在模板基础上做少量覆盖，比如某个节点需要高亮，就加一个高亮样式。
我实测下来，样式模板化之后，画图的视觉一致性会好很多，而且改样式的时候只需要改模板，所有图都会跟着变。这在做系列文档的时候特别有用，比如一套技术白皮书里有十几张图，样式统一会显得很专业。
注意：样式模板不要定义得太复杂。我见过有人把样式模板搞得像 CSS 框架一样，结果每张图都要写一堆覆盖规则，反而更麻烦。模板只需要定义最基础的几项：字体、主色、边框、间距。剩下的交给布局引擎。
4. 工具选型：什么样的方案值得长期用
4.1 选型的第一原则是“源文件可维护”
我在选 diagram-design 工具的时候，第一原则不是“画出来好不好看”，而是“源文件好不好维护”。因为图是要改的，改图成本才是长期成本。如果源文件是一堆二进制数据，或者是一个只能在特定软件里打开的格式，那维护成本就很高。
文本格式的源文件是最好的，因为可以进版本控制，可以 diff，可以 review。如果工具支持用代码或 DSL 描述图，那优先级最高。如果工具只支持图形界面拖拽，但能导出成文本格式，那也可以接受。如果工具只能导出图片，那基本只能用于一次性展示，不适合长期维护。
我自己的技术栈里，图的源文件都是文本格式，和代码放在同一个仓库里。改图的时候，我改文本，然后重新渲染。渲染出来的图可以直接嵌入文档，也可以导出成图片。整个流程是自动化的，不需要手动操作。
4.2 渲染质量和布局能力是第二原则
源文件可维护之后，第二原则是渲染质量和布局能力。渲染质量包括：字体渲染是否清晰、线条是否平滑、颜色是否准确。布局能力包括：是否支持多种布局算法、是否支持自动对齐、是否支持分组和嵌套。
我试过一些工具，源文件格式很好，但渲染出来的图很粗糙，字体发虚，线条锯齿严重。这种工具在正式文档里没法用。还有一些工具，布局能力很弱，只支持手动摆放，那和直接拖控件没区别。
我的经验是：布局能力比渲染质量更重要。因为渲染质量可以通过导出高分辨率图片来弥补，但布局能力不行就是不行。如果工具不能自动算布局，那维护成本就下不来。
4.3 常见方案对比
下面这张表是我自己用过的几类方案的对比，供你参考：
| 方案类型 | 源文件可维护性 | 布局能力 | 渲染质量 | 适用场景 |
|---|---|---|---|---|
| 代码生成图 | 高 | 强 | 中到高 | 技术文档、架构图、流程图 |
| DSL 描述图 | 高 | 中到强 | 中到高 | 知识图谱、关系图、流程图 |
| 图形界面拖拽 | 低 | 弱 | 高 | 一次性展示、演示文稿 |
| 手绘风格工具 | 中 | 弱 | 中 | 教学材料、非正式分享 |
从表里可以看出，代码生成图和 DSL 描述图在可维护性和布局能力上都有优势，适合长期维护的技术图。图形界面拖拽适合一次性展示，手绘风格工具适合教学和非正式场景。
我自己的主力方案是代码生成图，因为我的图大部分是技术架构和流程，需要频繁修改，而且要和代码放在一起。DSL 描述图我也用，主要用于关系复杂的图，比如知识图谱。图形界面工具我基本只在做演示文稿的时候用，因为演示文稿的图通常不需要长期维护。
5. 实操中容易踩的五个坑
5.1 坑一：节点命名太随意，改起来找不到
我刚开始用声明式画图的时候，节点命名很随意，比如“节点1”“节点2”“服务A”“服务B”。结果图一多，就分不清哪个节点是哪个了。改图的时候，要在几十个节点里找目标节点，效率很低。
后来我定了一个规则：节点命名必须带语义前缀。比如“接入-客户端”“逻辑-服务A”“存储-数据库”。这样一看名字就知道节点属于哪一层、是什么角色。改图的时候，直接搜前缀就能定位。
这个规则看起来很小，但实际用起来差别很大。尤其是图多了之后，语义命名能帮你快速定位，减少很多无谓的查找时间。
5.2 坑二：边的关系没有方向，布局算不对
声明式画图的时候，边的关系必须定义清楚方向。比如“A -> B”表示从 A 到 B 的有向边，“A -- B”表示无向边。如果方向定义错了，布局引擎算出来的位置就会很奇怪。
我踩过一次坑：画一张依赖关系图，把依赖方向写反了。结果布局引擎把被依赖的节点放在了上面，依赖的节点放在了下面，整个图的逻辑就反了。后来我检查了半天才发现是方向写反了。
所以我的建议是：定义边的时候，一定要确认方向是否符合业务逻辑。如果是依赖关系，被依赖的应该在下面；如果是流程关系，先发生的应该在前面。方向对了，布局才对。
5.3 坑三：分组嵌套太深，布局引擎算不动
分组是声明式画图的一个强大功能，可以把相关节点放在一个框里。但分组嵌套太深的时候，布局引擎可能会算不动，或者算出来的结果很丑。
我试过把分组嵌套到四层，结果布局引擎直接放弃了，所有节点堆在一起。后来我把嵌套层数控制在两层以内，布局就正常了。如果确实需要多层分组，我会拆成多张图，而不是硬塞在一张图里。
我的经验是：一张图的分组嵌套不要超过两层。如果超过两层，说明这张图的信息密度太高了，应该拆图。拆图不仅能让布局更清晰，也能让读者更容易理解。
5.4 坑四：样式覆盖太多，模板失去意义
前面说过，样式模板化能提升效率。但我也踩过一个坑：每张图都写一堆样式覆盖，结果模板形同虚设，改样式的时候还是要一张一张改。
后来我定了一个规则：样式覆盖只允许用于高亮和特殊标注。比如某个节点需要强调，就加一个高亮样式；某条边需要标注，就加一个标签样式。除此之外，所有样式都走模板。
这个规则执行下来，模板的复用率很高，改样式的时候只需要改模板，所有图都会跟着变。效率提升很明显。
5.5 坑五：图没有版本控制，改丢了找不回来
最后一个坑是版本控制。我早期画图的时候，图文件随便放，改完就覆盖，结果有一次改错了，想回退都回退不了。后来我把所有图的源文件都放进 Git，每次改图都提交一次，这样随时可以回退到任意版本。
版本控制还有一个好处：可以 diff。改图的时候，我能看到具体改了哪些节点、哪些边。这在 review 的时候特别有用，别人能清楚地看到图的变更内容。
提示：如果你的图是用代码生成的，那代码本身就在版本控制里，不需要额外处理。如果图是用 DSL 描述的，那 DSL 文件也要进版本控制。总之，图的源文件必须可追溯。
6. 一套我实测下来最稳的 diagram-design 工作流
6.1 工作流总览
经过多次迭代，我目前的工作流是这样的：
- 用文本描述图的结构，包括节点、边、分组、方向。
- 把结构描述文件放进 Git，和文档放在一起。
- 用渲染工具把结构描述渲染成图。
- 渲染出来的图嵌入文档，或者导出成图片。
- 改图的时候，改结构描述文件，重新渲染。
这个工作流的核心是：结构和样式分离，源文件文本化，渲染自动化。整个流程不需要手动拖控件，也不需要手动对齐。改图就是改几行文本，然后重新渲染。
我实测下来，这套工作流画一张中等复杂度的技术图，从开始到完成大概只需要十几分钟。改图的话，通常几分钟就能搞定。相比之前手动拖控件的方式，效率提升非常明显。
6.2 结构描述文件的组织方式
结构描述文件我通常按文档章节来组织。比如一篇文档有五章，每章有三张图，那我就会建五个目录，每个目录里放三张图的结构描述文件。文件名用“章节号-图序号-图名称”的格式，比如“01-01-系统架构图”。
这样做的好处是：图和文档的对应关系很清晰，找图的时候直接按章节找就行。而且结构描述文件可以复用，比如两张图有相同的节点，可以直接引用，不需要重复定义。
我还会在结构描述文件里加注释，说明这张图的用途和关键节点。这样别人接手的时候，能快速理解图的含义。注释用普通的文本注释就行，不需要特殊格式。
6.3 渲染和嵌入的自动化
渲染这一步，我通常会用命令行工具来完成。比如写一个脚本，遍历所有结构描述文件，逐个渲染成图片，然后输出到指定目录。这样每次改完结构描述，跑一下脚本，所有图就都更新了。
嵌入文档的时候，我用的是相对路径引用。这样文档和图片在同一个仓库里，迁移的时候不会丢图。如果文档是用 Markdown 写的，直接引用图片路径就行。如果文档是用其他格式写的，也可以用类似的方式引用。
自动化渲染的好处是：不需要手动导出图片，也不需要手动替换。改完结构描述，跑一下脚本，文档里的图就自动更新了。这在频繁改图的时候特别省事。
6.4 样式模板的维护
样式模板我通常单独放在一个文件里，所有图共享这个模板。模板里定义好字体、主色、辅色、边框、间距这些基础样式。每张图只需要在模板基础上做少量覆盖。
模板的维护频率很低，通常只在整体风格调整的时候才改。改的时候只需要改模板文件，所有图重新渲染一遍，风格就统一了。这比一张一张改图要高效得多。
我建议模板不要定义得太复杂，基础样式就够了。复杂的样式覆盖留给单张图去处理，不要都塞进模板里。模板越简单，复用率越高。
7. 关于 diagram-design 的一些个人体会
做 diagram-design 这件事，我最大的体会是：图的本质是结构，不是视觉。很多人把精力花在调颜色、调字体、调间距上，但真正决定图好不好用的，是结构清不清晰。结构清晰了，视觉稍微朴素一点也没关系；结构混乱了，视觉再花哨也救不回来。
另一个体会是：改图成本才是长期成本。画一张图可能只要十分钟，但改一张图可能要半小时。如果图的源文件不可维护，那每次改图都是重画，长期成本非常高。所以我在选方案的时候，永远优先考虑可维护性，而不是画出来的第一眼效果。
还有一个体会是：不要追求一张图讲完所有事。我见过很多人把十几层的信息塞进一张图里，结果图复杂到没人看得懂。我的做法是：一张图只讲一件事，复杂的信息拆成多张图。这样每张图都清晰，读者也容易理解。
最后说一个实操技巧：图的源文件和文档放在一起，用同一个版本控制。这样改文档的时候，顺手就能改图，不需要切换工具。而且图和文档的版本是对应的，不会出现文档更新了图没更新的情况。这个习惯我坚持了很久，实测下来非常省心。
如果你刚开始做 diagram-design，我的建议是：先从最简单的结构描述开始，不要一上来就搞复杂的样式。先把结构定义清楚，让布局引擎去算位置，然后慢慢调样式。等你习惯了声明式的方式，就会发现画图和改图都变得轻松很多。
