企业官网建设流程全解析

1. 从一张草图到一套系统：diagram-design 到底在解决什么问题

第一次听到 “diagram-design” 这个词，很多人会以为它只是“画图工具”的另一个说法。但真正在项目里被图表折磨过的人知道，问题从来不是“画不出来”，而是“画得出来、改不动、传不下去”。我见过太多团队，架构图靠某位同事的本地文件维护，流程图散落在不同人的截图里，时序图只存在于某次评审的聊天记录中。等到新人入职、系统重构、合规审计的时候，所有人都在问同一句话：最新版到底在哪？

diagram-design 要处理的，就是这件事。它不是一个单纯的绘图软件，而是一套把“图表”当作“代码资产”来管理的设计方法与实践体系。核心思路很直接：用文本描述结构，用版本控制管理变更，用自动化生成图形，用统一规范约束风格。你写的是几行结构化文本，得到的是可渲染、可对比、可追溯、可批量导出的图表。它解决的是图表在团队协作中的一致性、可维护性和可复用问题，适合架构师、技术文档写作者、产品经理、运维工程师，以及任何需要长期维护系统视图的人。

我最初接触这套思路，是因为一个跨平台系统项目。当时有 40 多张架构图和流程图，分别由 6 个人维护，格式五花八门，改一个模块名要手动翻十几张图。后来我们把所有图表迁移到文本化描述，配合渲染流水线，改一处定义，所有相关图自动更新。那次之后我才真正意识到，diagram-design 的价值不在“画”，而在“设计”和“治理”。

2. 整体设计思路拆解：为什么要把图表当代码管

2.1 图表失控的根源：图形是结果，结构才是源头

大多数人画图的习惯是打开工具、拖拽图形、调整连线、导出图片。这个流程本身没问题，但它把“结构信息”和“视觉表现”绑死在同一个文件里。一旦结构变了，视觉部分就得手动跟着改。更麻烦的是，图形文件通常是二进制或私有格式，没法做差异对比，也没法做合并。两个人同时改一张图，只能靠“你先改完我再改”。

diagram-design 的第一个设计决策，就是把结构和表现拆开。结构用纯文本描述，表现交给渲染引擎。文本可以 diff、可以 merge、可以 review，图形只是结构的一种输出。这个思路和前端领域“数据驱动视图”是一致的：你不再直接操作 DOM，而是描述状态，框架负责渲染。图表也一样，你描述节点和关系，工具负责布局和绘制。

提示：拆分结构和表现之后，图表的“唯一事实来源”变成了文本文件。任何视觉调整都不应该反向修改结构，而应该通过样式配置或渲染参数来控制。

2.2 选型背后的逻辑：为什么是文本化而不是可视化编辑器

有人会问，可视化编辑器也能导出文本格式，为什么还要手写？我的经验是，可视化编辑器适合探索性绘图，比如头脑风暴阶段快速勾勒想法。但一旦图表进入“需要长期维护”的阶段，手写文本的效率反而更高。原因有三点。

第一，批量修改成本低。改一个服务名，文本编辑器全局替换即可，可视化工具要逐个点选。第二，评审友好。文本 diff 能精确显示改了哪一行、哪个节点、哪条边，图形 diff 只能靠肉眼对比。第三，自动化集成方便。文本文件可以进 CI 流水线，渲染失败会报错，图形文件很难做这种校验。

当然，这不意味着可视化编辑器没有价值。我的做法是：探索阶段用可视化工具快速试错，定稿阶段把结构转成文本描述，后续维护全部在文本层完成。两者不是替代关系，而是不同阶段的工具选择。

2.3 统一规范的价值：让 40 张图看起来像一个人画的

图表一致性是团队协作里最容易被低估的问题。颜色、字体、箭头样式、节点命名规则，如果没有统一约束，每个人都会按自己的审美来。结果就是一套系统图里出现五六种风格，阅读体验极差。

diagram-design 的另一个核心设计，是把样式和结构分离之后，样式可以集中定义。比如定义一个主题文件，规定所有服务节点用蓝色圆角矩形，所有数据库节点用绿色圆柱体，所有外部系统用灰色虚线框。渲染时统一应用这个主题，不管有多少张图，视觉风格都是一致的。新人加入时也不需要问“该用什么颜色”，直接套主题就行。

这个思路的延伸价值在于，当公司或团队有品牌规范时，图表样式可以跟着规范走。换品牌色的时候，改一个主题文件，所有图表重新渲染即可，不需要逐张调整。

3. 核心细节解析与实操要点：从文本到图形的关键环节

3.1 结构描述语言的选择：不是越强大越好

文本化图表描述有很多种格式可选，常见的有 Mermaid、PlantUML、Graphviz DOT、D2 等。每种格式的定位不同，选型时要看具体场景。

我的建议是：如果图表主要嵌在文档里，优先选 Mermaid，因为渲染链路短。如果需要复杂布局和精细样式，选 D2 或 PlantUML。如果图非常大、节点非常多，Graphviz 的自动布局更省心。不要追求“一种格式打天下”，按场景选工具才是务实做法。

注意：选型时一定要确认渲染工具是否支持无头模式，也就是能不能在命令行里渲染成图片。这决定了它能不能进自动化流水线。

3.2 节点与关系的建模：先想清楚“什么是实体”

写图表描述之前，最重要的一步是确定“实体”和“关系”。实体就是图里的节点，关系就是节点之间的连线。听起来简单，但实际操作中很容易混乱。比如一个微服务系统，节点应该是“服务”还是“服务实例”？连线应该是“调用关系”还是“数据流向”？

我的经验是：一张图只表达一个视角。部署图就画部署单元，不要混入业务逻辑。时序图就画交互顺序，不要混入网络拓扑。如果一张图想表达太多东西，最后一定是一团乱麻。diagram-design 的实践里，通常会为同一个系统维护多张图，每张图聚焦一个视角，而不是试图用一张“大图”囊括所有信息。

节点命名也要有规范。我习惯用“类型:名称”的格式，比如service:order-api、db:order-main、queue:order-events。这样在文本里一眼就能看出节点类型，渲染时也可以根据类型自动应用样式。

3.3 样式与主题的集中管理：别在每张图里重复写颜色

样式集中管理是 diagram-design 里最容易被忽视但收益最高的实践。很多人写图的时候，习惯在每个节点上单独指定颜色和形状。短期看没问题，长期看就是灾难。改一次品牌色，要翻遍所有文件。

正确做法是定义一个主题文件，把颜色、字体、形状、连线样式都抽出来。图表文件里只描述结构和类型，渲染时把主题应用上去。比如：

# theme.yaml styles: service: fill: "#E3F2FD" stroke: "#1565C0" shape: rounded-rect database: fill: "#E8F5E9" stroke: "#2E7D32" shape: cylinder external: fill: "#F5F5F5" stroke: "#9E9E9E" shape: rect stroke-dash: 4

图表文件里只需要写service:order-api，渲染引擎会自动查主题表，应用对应样式。这样换主题的时候，只改一个文件，所有图重新渲染即可。

提示：主题文件也要进版本控制。样式变更和结构变更一样，需要 review 和记录。否则某天有人偷偷改了颜色，所有人都不知道。

3.4 渲染流水线的搭建：让图表自动更新

文本化图表的真正威力，在于它可以进自动化流水线。我的做法是在项目里建一个diagrams/目录，存放所有图表源文件，然后配置一个渲染脚本，在 CI 里自动把源文件渲染成 PNG 或 SVG，输出到docs/diagrams/目录。

# render.sh #!/bin/bash set -e mkdir -p docs/diagrams for f in diagrams/*.d2; do name=$(basename "$f" .d2) d2 --theme 0 --layout elk "$f" "docs/diagrams/${name}.svg" done

这个脚本做的事情很简单：遍历所有图表源文件，用 D2 渲染成 SVG，输出到文档目录。CI 里配置成每次 push 自动执行，这样文档里的图永远是最新的。如果有人改了结构但忘了更新图，CI 会重新渲染，不会出现“文档和图不一致”的情况。

如果团队用 Markdown 写文档，还可以更进一步：在 Markdown 里直接引用源文件，用插件在构建时渲染。这样连手动跑脚本都省了。

4. 实操过程与核心环节实现：一个跨平台系统的图表治理案例

4.1 现状盘点：先搞清楚有多少图、谁在维护、多久改一次

任何治理工作都要从盘点开始。我们当时做的是一个模拟项目，代号“某跨平台系统”，涉及 6 个子系统、40 多张图表。第一步是列出所有图表的清单，包括：文件名、格式、维护人、最后修改时间、被引用位置。

盘点结果很不乐观：格式有 5 种，维护人 6 个，最后修改时间跨度超过一年，有 8 张图已经找不到源文件，只有导出的 PNG。更麻烦的是，有 3 张图的内容互相矛盾，同一个模块在不同图里叫不同名字。

这个阶段的关键是不要急着动手改，先把现状摸清楚。我见过有人一上来就开始迁移，结果迁到一半发现漏了一批图，又得回头补。盘点虽然枯燥，但能避免后期返工。

4.2 迁移策略：分批迁移，先易后难

40 多张图不可能一次性迁完。我们的策略是分批处理，优先级按“修改频率”和“引用次数”来定。修改频率高、被引用多的图先迁，因为收益最大。修改频率低、几乎没人看的图后迁，甚至可以暂时不动。

第一批选了 8 张核心架构图，这些图每个月至少改一次，而且被多个文档引用。迁移过程分三步：先把图形结构转成文本描述，然后套用统一主题，最后接入渲染流水线。每迁完一张，就和原图做对比，确认结构一致、样式符合规范。

这里有个细节：迁移时不要追求“一次完美”。第一版文本描述只要结构正确就行，样式可以后续再调。我见过有人花大量时间调样式，结果结构还没对齐，本末倒置。

4.3 命名规范落地：从“各叫各的”到“统一字典”

命名混乱是图表治理里最头疼的问题。同一个服务，有人叫“订单服务”，有人叫“order-service”，有人叫“OrderSvc”。迁移过程中，我们做了一件事：建立命名字典。

字典的格式很简单，三列：标准名、别名、类型。标准名是唯一标识，别名是历史遗留叫法，类型用于样式匹配。比如：

迁移时，所有图表里的节点名都替换成标准名。渲染时，主题引擎根据类型自动应用样式。这样不仅解决了命名混乱，还让样式应用变得自动化。

注意：命名字典本身也要进版本控制，并且要有 review 机制。新增节点时，先查字典，没有再加。否则字典会逐渐失控。

4.4 渲染流水线接入：从手动导出到自动生成

迁移完成后，下一步是接入渲染流水线。我们在项目里建了一个diagrams/目录，所有源文件放这里。然后写了一个渲染脚本，在 CI 里配置成每次 push 自动执行。

脚本的核心逻辑是：遍历源文件，渲染成 SVG，输出到docs/diagrams/。如果渲染失败，CI 会报错，阻止合并。这样保证了图表源文件始终是可渲染的，不会出现“改了文本但渲染不出来”的情况。

# .ci/config.yml stages: - render-diagrams render-diagrams: stage: render-diagrams script: - bash scripts/render.sh artifacts: paths: - docs/diagrams/

这个配置做的事情很简单：在 CI 里跑渲染脚本，把生成的图作为构建产物保存。文档构建时直接引用这些产物，不需要手动更新。

4.5 效果验证：改一处定义，所有图自动更新

迁移完成后的第一次验证，是改一个服务名。我们在命名字典里把service:order-api改成service:order-service，然后重新渲染。结果所有引用这个节点的图都自动更新了，包括架构图、时序图、部署图。整个过程不到 5 分钟，而以前手动改的话，至少要半天。

这次验证之后，团队才真正认可了这套方法。后来我们又做了几次批量修改，比如调整主题色、统一箭头样式，都是改一个文件、重新渲染，所有图同步更新。维护成本从“每张图单独改”变成了“改一处定义”。

5. 常见问题与排查技巧实录：踩过的坑和绕过的弯

5.1 渲染布局不理想：自动布局不是万能的

文本化图表最大的痛点之一是布局控制。自动布局算法虽然省心，但有时候会把节点排得很难看，连线交叉严重。我遇到过一张依赖关系图，自动布局把两个强关联的节点排到了对角，中间隔了七八个节点，阅读体验极差。

解决办法有两个。一是调整布局引擎的参数，比如 Graphviz 的rankdir、nodesep、ranksep，D2 的layout选项。二是手动指定部分节点的位置或分组，用子图或容器把相关节点聚在一起。我的经验是，先让自动布局跑一遍，看看哪里不合理，再针对性调整。不要一上来就手动摆位置，那样工作量太大。

提示：如果一张图自动布局怎么调都不理想，可能是图本身太复杂了。考虑拆成两张图，或者换一个视角表达。

5.2 文本 diff 可读性差：结构描述也要讲可读性

文本化图表的一个卖点是 diff 友好，但前提是文本本身可读。如果所有节点写在一行，diff 出来就是一大坨，根本看不出改了什么。我的做法是每个节点一行，关系也一行，保持格式规整。

# 不好的写法 a -> b -> c; d -> e; f -> g # 好的写法 a -> b b -> c d -> e f -> g

这样 diff 的时候，改哪一行一目了然。另外，节点定义和关系定义分开写，不要混在一起。节点定义放前面，关系定义放后面，结构更清晰。

5.3 渲染工具版本不一致：锁定版本很重要

不同版本的渲染工具，输出可能不一样。我遇到过本地渲染正常，CI 渲染出来布局完全不同。排查后发现是本地和 CI 的 D2 版本不一致。解决办法是在项目里锁定渲染工具版本，比如用package.json或requirements.txt固定版本号，CI 和本地都用同一个版本。

5.4 团队接受度低：先做一个小胜利

推广任何新方法，最大的阻力都是人。我一开始推文本化图表的时候，很多人觉得“手写文本太麻烦，不如拖拽直观”。后来我选了一个小场景做试点：一个只有 5 个节点的流程图，用文本描述，接入自动渲染。改了几次之后，大家发现改文本比拖拽快，而且 diff 清晰。这个小胜利之后，推广阻力小了很多。

我的经验是，不要一上来就要求所有人迁移。先找愿意尝试的人，做一个小项目，拿到结果再推广。用事实说话，比讲道理有用。

5.5 图表源文件丢失：版本控制是底线

盘点时发现 8 张图找不到源文件，只有 PNG。这个问题没有技术解法，只能靠流程约束。我的做法是：所有图表源文件必须进版本控制，导出的图片可以进，但源文件是必须的。CI 里加一个检查，如果diagrams/目录为空或者源文件数量少于阈值，就报警。

另外，图表源文件的命名也要规范，最好和文档结构对应。比如docs/architecture/overview.d2对应docs/architecture/overview.md，这样找起来方便。

6. 工具链选型与扩展思路：不追求大而全，只追求够用

6.1 渲染工具对比：按场景选，不按喜好选

工具选型是 diagram-design 落地时绕不开的问题。我的原则是：按场景选，不按喜好选。如果图表主要嵌在 Markdown 里，Mermaid 最省事，因为很多 Markdown 渲染器原生支持。如果需要复杂布局和精细样式，D2 或 PlantUML 更合适。如果图非常大、节点非常多，Graphviz 的自动布局更稳。

我个人的组合是：文档内嵌用 Mermaid，架构图用 D2，大规模依赖图用 Graphviz。不追求统一，按场景选最合适的。

6.2 与文档系统的集成：让图表跟着文档走

图表最终是要给人看的，所以和文档系统的集成很重要。我的做法是图表源文件和文档放在同一个仓库，渲染产物输出到文档目录。文档构建时直接引用产物，不需要手动更新。

如果文档系统支持插件，还可以更进一步：在 Markdown 里直接写图表源文件路径，构建时自动渲染。这样连渲染脚本都不用单独跑，文档构建和图表渲染是一体的。

6.3 扩展方向：从静态图到交互式图

文本化图表的一个扩展方向是交互式图。比如用 D2 渲染成 SVG 后，可以用 JavaScript 加交互，点击节点展开详情、悬停显示说明。这个方向适合在线文档和内部知识库，能显著提升阅读体验。

另一个方向是图表校验。比如检查所有节点是否都在命名字典里、所有关系是否合法、是否有孤立节点。这些校验可以进 CI，提前发现问题。我试过用脚本检查孤立节点，发现了几张图里有定义但没连线的节点，都是历史遗留问题。

7. 我个人在实际操作中的体会

这套方法我用了两年多，最大的体会是：图表治理的本质不是技术问题，而是流程问题。工具再好，如果团队不遵守规范，照样会乱。所以推广的时候，一定要先建立流程，再引入工具。流程包括：命名规范、主题管理、渲染流水线、review 机制。工具只是流程的载体。

另一个体会是，不要追求一步到位。我见过有人想把所有图一次性迁移，结果做到一半就放弃了。分批迁移、先易后难、拿到小胜利再推广，才是可持续的做法。

最后分享一个小技巧：图表源文件里加注释。文本化图表的一个优势是可以在源文件里写注释，解释为什么这么画、有什么背景信息。这些注释不会出现在渲染结果里，但对后续维护的人非常有帮助。我习惯在每个复杂节点旁边加一行注释，说明它的职责和边界。这样半年后回来看，还能快速理解当时的思路。