1. 从一张草图到一套系统：diagram-design 到底在解决什么问题
第一次看到 diagram-design 这个词，很多人会以为它只是“画图工具”的又一个新名字。但真正在项目里被图表折磨过的人会明白，它指向的是一套更底层的东西：把“图”从一次性产物变成可维护、可复用、可协作的设计资产。我做过不少带架构图、流程图、状态机的项目，最深的体会是——画图不难，难的是三个月后回来改图。那时候你会发现，当初那个箭头为什么这么连、那个模块为什么单独抽出来，全忘了。diagram-design 要解决的，正是这种“图与代码、图与文档、图与团队认知”之间的脱节。
它适合谁？如果你是后端或全栈开发者，需要给系统画架构图、时序图、部署图；如果你是技术写作者，文档里要嵌大量流程图；如果你是团队里那个“被迫负责画图”的人，每次评审前都要熬夜对齐版本——那这套东西值得你花时间。它不要求你会设计，但要求你愿意把图当成代码一样去管理。核心思路一句话：用文本描述结构，用工具渲染图形，用版本控制管理演进。图不再是图片文件，而是一段可 diff、可 review、可回滚的源码。
我见过太多团队在“画图”这件事上反复内耗：有人用在线白板画完导出 PNG，有人用桌面软件存成二进制文件，最后合并时谁也说不清哪版是最新。diagram-design 的价值就在于把这种混乱收敛到一条可追踪的流水线上。下面我会从整体设计、核心细节、实操过程到问题排查，完整拆一遍我是怎么落地这套方法的。
2. 整体设计与思路拆解：为什么把图当代码管
2.1 核心矛盾：图的“表达力”与“可维护性”天然打架
图表这东西，表达力越强，往往越难维护。手绘风格的白板图沟通效率极高，但改一处要动全身；专业绘图软件能做出精美架构图，但文件是二进制的，git diff 出来一堆乱码。diagram-design 的切入点很聪明：它承认图有两种消费场景——给人看的“展示态”和给机器/流程用的“结构态”。展示态可以精美，结构态必须文本化。
所以它的整体设计遵循一条主线：结构用文本描述，布局交给引擎，样式按需覆盖。你写的是“A 调用 B，B 依赖 C”，而不是“把方块拖到坐标 (320, 180)”。这样当系统演进时，你改的是关系描述，不是像素位置。布局引擎会根据关系自动重排，你只需要关注逻辑是否正确。这个取舍非常关键：牺牲了一部分“像素级控制”，换来了“逻辑级可维护”。
我早期也抵触过这种方式，觉得“自动布局出来的图太丑”。但后来想通了：架构图的第一价值是准确传达结构，第二才是好看。而且现在主流文本绘图工具的自动布局已经相当成熟，配合少量样式指令，出图质量完全能进正式文档。
2.2 方案选型：为什么是文本驱动而不是插件化绘图
市面上画图方案大致分三类：桌面软件、在线白板、文本驱动。diagram-design 明显站在第三类。为什么？因为前两类都有一个致命问题——无法进入代码评审流程。你没法在 PR 里对一张 PNG 写评论说“这个箭头方向反了”。而文本驱动的图，天然就是纯文本文件，可以 diff、可以 blame、可以 CI 校验。
具体到工具选型，我实测下来比较稳的组合是：Mermaid 做流程/时序/状态图，Graphviz DOT 做复杂依赖关系，PlantUML 做 UML 系图。三者都是文本描述、都有成熟渲染器、都能嵌进 Markdown。选它们不是因为它们最漂亮，而是因为它们最“工程化”：命令行可调用、输出格式可控、社区活跃、语法稳定。
注意：不要一上来就追求“一个工具画所有图”。我踩过的坑是硬用 Mermaid 画复杂网络拓扑，结果布局惨不忍睹。后来改成 Graphviz 画拓扑、Mermaid 画流程，各司其职，效率翻倍。
2.3 目录结构设计：让图跟着代码走还是跟着文档走
这是落地时第一个要决策的点。我的经验是：图放在它最常被修改的地方附近。如果图描述的是某个服务的内部流程，就放在该服务的docs/下；如果图描述的是跨服务调用，就放在仓库根目录的architecture/下。不要单独建一个“图库”仓库，那样一定会和代码脱节。
我现在的标准结构是这样的：
project/ ├── docs/ │ ├── architecture/ │ │ ├── system-overview.mmd │ │ ├── deploy-topology.dot │ │ └── sequence-login.puml │ └── guides/ │ └── onboarding.md # 内嵌图引用 ├── scripts/ │ └── render-diagrams.sh # 批量渲染脚本 └── .github/ └── workflows/ └── diagram-check.yml # CI 校验图语法这样做的理由是：图文件跟文档同目录，改文档时顺手改图；渲染脚本统一管理输出路径；CI 里加一道语法检查，防止有人提交了渲染不出来的图。这套结构我用了两年多，团队里再没人问“最新架构图在哪”。
3. 核心细节解析与实操要点：语法、布局与样式控制
3.1 文本绘图语法速通：从“能画”到“画对”
以 Mermaid 为例，最常用的三类图是流程图、时序图、状态图。流程图的核心是节点和连线：
flowchart LR A[客户端] --> B[网关] B --> C{鉴权} C -->|通过| D[业务服务] C -->|拒绝| E[返回401] D --> F[(数据库)]这段代码里，LR表示从左到右布局，[]是矩形节点，{}是菱形判断，[()]是圆柱形数据库。关键点在于：节点 ID 和显示文本分离。A是内部 ID，客户端是显示文本。这样你改显示文本不影响连线关系，改连线也不影响文本。这是文本绘图比拖拽绘图强的地方——关注点分离。
时序图则强调交互顺序：
sequenceDiagram participant U as 用户 participant S as 服务端 U->>S: 提交登录请求 S->>S: 校验凭证 alt 校验通过 S-->>U: 返回 Token else 校验失败 S-->>U: 返回错误码 endalt/else/end是条件分支，->>是实线箭头，-->>是虚线返回。我建议时序图里显式写出 participant，不要依赖自动推断，否则参与者顺序会随首次出现顺序变化，评审时容易看晕。
3.2 布局引擎的选择逻辑：什么时候用 dagre，什么时候用 elk
Mermaid 底层默认用 dagre 布局，适合大多数有向无环图。但当你图里有大量交叉连线或嵌套子图时，dagre 会显得很挤。这时候可以切到 elk 布局（部分渲染器支持）。我的判断标准很简单：
| 场景 | 推荐布局 | 理由 |
|---|---|---|
| 线性流程、简单分支 | dagre | 默认即可，速度快 |
| 多层嵌套子图 | elk | 层次感更强，交叉少 |
| 复杂依赖网络 | Graphviz dot | 专为有向图优化 |
| 状态机 | dagre | 状态转移通常不复杂 |
实测下来，大部分业务流程图用 dagre 就够了。真正需要 elk 的是那种“一个主流程里嵌了三个子流程，子流程里还有判断”的图。但我的建议是：与其调布局，不如拆图。一张图超过 15 个节点，阅读体验就急剧下降。拆成两张图，每张都清晰，比硬塞一张强。
3.3 样式控制：少即是多，别把图做成彩虹
文本绘图工具都支持样式指令，比如 Mermaid 里可以给节点上色：
flowchart TD A[正常节点] B[警告节点] C[错误节点] style B fill:#fff3cd,stroke:#ffc107 style C fill:#f8d7da,stroke:#dc3545但我强烈建议：默认样式能看就别改。我见过太多图因为过度上色变得像圣诞树，反而掩盖了结构信息。样式只用在三个地方：一是区分环境（生产/测试），二是标记异常路径，三是突出核心模块。其他情况一律用默认。
实操心得：如果团队有设计规范，把颜色定义成 class，而不是每个节点单独写 style。Mermaid 支持
classDef，这样改主题时只改一处。
flowchart LR classDef core fill:#e7f5ff,stroke:#1971c2 classDef ext fill:#f8f9fa,stroke:#868e96 A[核心服务]:::core --> B[外部依赖]:::ext这种写法比逐个style干净得多，也更容易维护。
4. 实操过程与核心环节实现：从零搭一条图表流水线
4.1 环境准备：渲染器安装与版本锁定
文本绘图的第一步是能本地渲染。Mermaid 有 CLI，Graphviz 有dot命令，PlantUML 是 Java 包。我建议用 Docker 统一环境，避免“我机器上能渲染，CI 上不行”。
# 用 Docker 跑 Mermaid CLI docker run --rm -v $(pwd):/data minlag/mermaid-cli \ -i /data/docs/architecture/system-overview.mmd \ -o /data/docs/architecture/system-overview.svg # Graphviz 渲染 dot -Tsvg deploy-topology.dot -o deploy-topology.svg # PlantUML 渲染 java -jar plantuml.jar sequence-login.puml版本锁定很重要。Mermaid 不同大版本之间语法有差异，比如 v9 到 v10 的配置方式变了。我在package.json里固定@mermaid-js/mermaid-cli的版本，CI 里也用同一个版本，避免“本地能渲染、CI 报错”。
4.2 渲染脚本编写：一条命令批量出图
手动一个个渲染太累，我写了个脚本扫描目录下所有.mmd、.dot、.puml文件，统一输出到dist/diagrams/：
#!/usr/bin/env bash set -euo pipefail SRC_DIR="docs" OUT_DIR="dist/diagrams" mkdir -p "$OUT_DIR" find "$SRC_DIR" -name "*.mmd" | while read -r f; do base=$(basename "$f" .mmd) docker run --rm -v "$(pwd):/data" minlag/mermaid-cli \ -i "/data/$f" -o "/data/$OUT_DIR/$base.svg" echo "rendered: $base.svg" done find "$SRC_DIR" -name "*.dot" | while read -r f; do base=$(basename "$f" .dot) dot -Tsvg "$f" -o "$OUT_DIR/$base.svg" echo "rendered: $base.svg" done这个脚本的关键是set -euo pipefail，任何一步失败就中断，避免生成一半图还以为成功了。输出统一放dist/，方便 CI 收集产物。
4.3 嵌入文档：让图跟着文字走
图渲染出来后，嵌入 Markdown 有两种方式：一是直接引用 SVG 文件，二是用支持 Mermaid 的渲染器内联。我推荐文档里内联源码，构建时渲染。这样改图不用重新导出，改完源码提交即可。
如果文档平台支持 Mermaid（很多静态站点生成器都支持），直接写：
```mermaid flowchart LR A[请求] --> B[处理] --> C[响应] ```如果不支持，就用图片引用：
注意：SVG 比 PNG 更适合架构图，因为矢量图放大不糊，而且文本可搜索。但有些平台对 SVG 支持不好，那就退而求其次用 PNG，分辨率至少 2x。
4.4 CI 集成：让坏图进不了主干
这是整套流水线里最有价值的一环。我在 CI 里加了一个 job，专门检查所有图文件能否成功渲染：
name: diagram-check on: [pull_request] jobs: render: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - name: Render all diagrams run: bash scripts/render-diagrams.sh - name: Check output exists run: | count=$(find dist/diagrams -name "*.svg" | wc -l) if [ "$count" -eq 0 ]; then echo "No diagrams rendered!" exit 1 fi这样任何人提交了语法错误的图，PR 直接挂掉，评审时就不会出现“图打不开”的尴尬。我团队里有个规矩：改架构必须先改图，图不过 CI 不许合并。执行半年后，文档里的图和代码终于同步了。
5. 常见问题与排查技巧实录：那些年我踩过的坑
5.1 渲染失败排查速查表
| 现象 | 可能原因 | 解决方式 |
|---|---|---|
| Mermaid 报语法错误 | 节点文本含特殊字符未转义 | 用引号包裹文本，如A["含(括号)的文本"] |
| 图渲染出来是空白 | 输出路径不对或权限不足 | 检查-o路径，确保目录存在 |
| Graphviz 布局混乱 | 节点太多或存在环 | 拆图，或用rankdir调整方向 |
| PlantUML 中文乱码 | 默认字体不含中文 | 加skinparam defaultFontName指定中文字体 |
| CI 渲染超时 | Docker 拉镜像慢 | 预拉镜像或改用本地安装 |
5.2 三个最容易忽略的细节
第一个是节点文本里的特殊字符。Mermaid 里括号、引号、冒号都可能被解析成语法，必须用引号包起来。我一开始不知道，写了个A[用户(已登录)]，渲染直接报错。后来养成习惯：只要文本里有非字母数字，一律加引号。
第二个是图的粒度。我见过一张图塞了 40 多个节点，评审时没人看得清。后来定了个硬规矩：单图不超过 15 个节点，超过就拆。拆图不是失败，是专业。一张清晰的子图比一张糊成一团的总图有价值得多。
第三个是版本兼容。Mermaid v10 改了配置方式，以前写在%%{init}%%里的主题配置，现在推荐用--configFile。如果你在 CI 里用最新版、本地用旧版，就会出现“本地好好的，CI 挂了”。解决办法只有一个：锁定版本，本地和 CI 用同一个。
5.3 独家避坑：图与代码不同步怎么办
这是文本绘图最大的敌人。图放在仓库里，代码改了图没改，三个月后图就是错的。我的解法是把图纳入 Definition of Done：任何涉及接口变更、模块拆分、流程调整的 PR，必须同时更新对应图文件。评审时专门有人检查这一点。
另外，我会在关键图文件头部加一行注释，写明最后更新时间和对应代码版本：
%% @last-updated 2025-01-15 %% @related-service user-service %% @related-pr #1234这样即使图旧了，也能快速定位到它描述的是哪个版本。别小看这行注释，排查“图为什么和代码对不上”时能省半小时。
6. 进阶玩法：让图表流水线更自动
6.1 从代码生成图：反向同步的思路
手动维护图终究有滞后。进阶做法是从代码里提取结构自动生成图。比如从 OpenAPI 定义生成接口调用图，从数据库 schema 生成 ER 图，从 Terraform 配置生成部署拓扑图。我试过用脚本解析服务间的 HTTP 调用注解，自动输出 Mermaid 流程图，效果不错。
思路是：能自动提取的绝不手写，必须手写的才手写。接口关系、依赖关系这类结构化信息，完全可以从代码或配置里解析。而业务流程、状态流转这类语义信息，还是得人写。两者结合，既保证准确又保留表达力。
6.2 图的可访问性：别让色盲同事看天书
如果图里用颜色区分状态，记得加文字标注或形状区分。红绿色盲在男性中比例不低，纯靠颜色传递信息会漏掉一部分人。我的做法是：颜色只做辅助，主要靠形状和文字。比如正常节点用矩形、异常节点用菱形加文字“异常”，这样即使黑白打印也能看懂。
6.3 图的版本对比：diff 出来给评审看
文本图的一大优势是能 diff。我有时会在 PR 描述里贴出图的 diff，让评审者直观看到“加了哪个节点、改了哪条连线”。Mermaid 源码的 diff 可读性很好，比贴两张 PNG 让人找不同高效得多。这个习惯坚持下来，团队对架构变更的敏感度明显提高。
7. 我个人在实际操作中的体会
这套 diagram-design 的方法我用了两年多，最大的感受是：图的质量不取决于工具多高级，而取决于你愿不愿意把图当代码一样对待。文本绘图工具只是手段，真正的改变是心态——图不再是“画完就扔”的附件，而是和代码一起演进的一等公民。
踩过最深的坑是早期追求“一张图讲清所有事”，结果图越画越大，最后没人看。后来学会拆图，每张图只讲一件事，反而沟通效率高了。另一个体会是：自动布局出来的图，丑一点没关系，准确最重要。手调坐标花的时间，够你写三张新图了。
如果让我给刚接触的人一条建议：从一张最简单的流程图开始，用 Mermaid 写，提交到仓库，加进 CI。跑通这条最小闭环，你就理解了 diagram-design 的精髓。剩下的，都是在这条流水线上加东西。
