1. 从“diagram-design”这个标题里能读出什么第一次看到“diagram-design”这个标题很多人会以为它只是某个绘图工具的别名或者是一个教你怎么画流程图的普通教程。但如果你在技术社区里泡过一段时间就会发现这个词背后其实藏着一类非常具体的需求用代码或结构化描述来生成图表而不是靠鼠标拖拽。这个区别听起来不大实际用起来却是天壤之别。我最早接触这类需求是在给一个内部系统写技术文档的时候。当时需要画十几张架构图和时序图用传统绘图工具一张张拖拽、对齐、调样式改一个节点位置就要重新调整整张图。后来换成用文本描述生成图表的方式改一个词就能重新渲染效率提升非常明显。从那以后我就开始关注“diagram-design”这类工具和方案。这篇文章想聊的就是围绕“diagram-design”这个主题把图表设计从“手工活”变成“工程活”的完整思路。我会讲到为什么文本驱动的方式更适合技术场景、常见的图表描述语言怎么选、实际落地时会遇到哪些坑、以及怎么把图表生成集成到日常开发流程里。无论你是写文档的开发者、做技术方案的产品经理还是需要频繁输出架构图的运维人员这些内容都能直接参考。提示本文讨论的“diagram-design”指的是用结构化文本描述来设计和生成图表的方法论与工具链不涉及任何特定商业产品的推广。2. 为什么文本驱动正在取代鼠标拖拽2.1 传统绘图方式的三个硬伤用鼠标拖拽画图在演示场景下确实直观但一旦进入技术协作流程问题就暴露出来了。我总结下来主要有三个硬伤。第一个是版本管理困难。一张用二进制格式保存的图表文件在Git里只能看到“文件变了”完全无法diff。两个人同时改一张图冲突解决起来基本靠猜。而文本描述的图表每一行改动都清清楚楚谁在什么时候把哪个节点从A改成了B一目了然。第二个是样式一致性难以保证。手动拖拽的图十个人画出来是十种风格。箭头粗细、字体大小、颜色搭配全靠个人审美。文本驱动的方式可以通过模板和主题文件统一控制改一处全局生效。第三个是维护成本随规模指数上升。一张图改一个节点还好如果是几十张图需要统一调整某个命名或布局手动操作几乎是不可能完成的任务。文本驱动的方式可以用脚本批量处理改一个变量就能重新生成所有图。2.2 文本描述图表的本质优势文本驱动图表的核心逻辑是把“画图”这件事拆成两层内容描述层和渲染层。你只需要关心“有哪些节点、它们怎么连接、分了几组”至于节点画成圆角矩形还是菱形、箭头用什么颜色、布局是横向还是纵向交给渲染引擎去处理。这种分层带来的好处是显而易见的。内容描述可以像代码一样被review、被版本控制、被复用。同一个描述文件可以渲染成不同风格的图适配不同的输出场景。比如同一份架构描述可以生成适合放在文档里的简洁版也可以生成适合投屏演示的高对比度版。我自己的习惯是把图表描述文件和代码放在同一个仓库里。代码改了图表描述跟着改CI流程里自动渲染出最新的图。这样文档永远不会和代码脱节省去了大量“文档更新滞后”的沟通成本。2.3 哪些场景最适合这种方案不是所有图表都适合文本驱动。如果你只是偶尔画一张简单的示意图用鼠标拖拽可能更快。但以下几类场景文本驱动的优势非常明显技术架构图节点多、连接关系复杂、需要频繁更新流程图和时序图逻辑性强、有明确的步骤和分支状态机图状态和转换关系用文本描述比画图更清晰数据库ER图表结构本身就有明确的定义可以直接从schema生成批量图表生成需要根据数据动态生成大量相似结构的图反过来如果是需要高度定制化视觉效果的营销图、需要精细调整每个元素位置的海报那还是交给专业设计工具更合适。文本驱动解决的是“逻辑清晰、结构规整”类图表的需求不是替代所有绘图场景。3. 主流图表描述语言怎么选3.1 Mermaid上手最快但边界也最明显Mermaid是目前普及度最高的文本绘图方案之一。它的语法非常直观基本上看几分钟就能上手。比如画一个简单的流程图graph TD A[开始] -- B{判断条件} B --|是| C[执行操作] B --|否| D[结束]这种语法几乎就是自然语言的映射学习成本极低。而且Mermaid被大量文档平台原生支持写进Markdown里就能直接渲染非常方便。但Mermaid的局限性也很明显。它的布局算法是自动的你很难精确控制节点位置。对于简单的图没问题但节点一多布局就会变得混乱箭头交叉严重。另外Mermaid的样式定制能力有限虽然支持主题变量但想做出精细的视觉效果比较困难。我的经验是Mermaid适合快速表达逻辑关系比如在技术方案里画个简单的流程示意。但如果是要放在正式文档里、需要反复打磨视觉效果的图Mermaid可能不够用。3.2 PlantUML功能全面但学习曲线陡PlantUML是另一个老牌的文本绘图工具支持的图表类型非常丰富包括时序图、用例图、类图、状态图、部署图等等。它的语法比Mermaid复杂一些但控制力也更强。举个例子画一个时序图startuml participant 客户端 as C participant 服务端 as S C - S: 发起请求 S -- C: 返回响应 endumlPlantUML的优势在于图表类型覆盖广而且可以通过skinparam等参数做比较细致的样式调整。它还支持从代码或数据库schema反向生成图表这在维护大型系统文档时非常有用。但PlantUML的渲染依赖Java环境部署起来比Mermaid重一些。而且它的语法细节比较多想精通需要花不少时间。另外PlantUML的默认视觉风格偏“工程感”如果对美观度要求高需要额外做不少样式定制。3.3 其他值得关注的方案除了Mermaid和PlantUML还有一些更垂直的方案值得了解。比如Graphviz的DOT语言它是很多图表工具的底层引擎布局算法非常强大适合生成复杂的网络拓扑图。但DOT的语法比较底层直接写DOT文件的门槛较高通常作为其他工具的渲染后端来使用。还有D2这个相对较新的方案它的设计理念是“声明式图表”语法比Mermaid更简洁同时支持更丰富的样式和布局控制。我最近在几个项目里试用了D2感觉它在表达力和易用性之间找到了不错的平衡点尤其是对容器和嵌套结构的支持很自然。另外如果团队已经在用Structurizr做架构描述那它自带的图表生成能力也值得考虑。Structurizr的核心思路是用代码定义架构模型然后从模型生成多个视图非常适合需要维护多张关联架构图的场景。3.4 选型决策表方案上手难度图表类型覆盖样式控制力部署复杂度适合场景Mermaid低中中低文档内嵌、快速示意PlantUML中高高高中正式技术文档、多类型图表Graphviz DOT高中中低复杂拓扑、自动布局D2低中中高高低现代化文档、嵌套结构Structurizr中中中中架构模型驱动、多视图选型时不要只看功能列表要结合团队的实际工作流。如果图表主要是嵌在Markdown文档里Mermaid的零配置优势很难被替代。如果需要生成多种类型的正式图表并且愿意投入学习成本PlantUML的全面性更值得考虑。4. 把图表描述集成到开发流程的实操路径4.1 目录结构与文件组织要让图表描述真正融入开发流程第一步是把文件组织好。我的习惯是在项目根目录下建一个docs/diagrams目录按图表类型或模块分子目录。比如docs/ diagrams/ architecture/ system-overview.d2 >#!/bin/bash set -e DIAGRAM_DIRdocs/diagrams OUTPUT_DIRdocs/images mkdir -p $OUTPUT_DIR find $DIAGRAM_DIR -name *.d2 | while read -r file; do relative_path${file#$DIAGRAM_DIR/} output_name${relative_path%.d2}.svg output_path$OUTPUT_DIR/$output_name mkdir -p $(dirname $output_path) d2 --theme200 --layoutelk $file $output_path echo Rendered: $output_path done这个脚本做了几件事遍历所有.d2文件、保持目录结构输出到images目录、指定主题和布局引擎。几个关键点需要注意输出格式选SVGSVG是矢量图放大不糊而且文件小、可diff。如果目标平台不支持SVG再考虑PNG。布局引擎要显式指定D2默认的布局引擎和ELK引擎效果差别很大ELK通常更适合复杂图。显式指定可以避免不同环境渲染结果不一致。错误处理不能省set -e让脚本在遇到错误时立即停止避免生成一半的图没人发现。4.3 与CI/CD流水线的对接渲染脚本写好后下一步是把它接入CI流程。我的做法是在CI配置里加一个独立的job专门负责图表渲染和校验。render-diagrams: stage: build script: - bash scripts/render-diagrams.sh - git diff --exit-code docs/images/ || (echo 图表有更新请本地重新渲染后提交 exit 1) artifacts: paths: - docs/images/这个job的逻辑是先渲染所有图表然后检查渲染结果和仓库里已提交的图片是否有差异。如果有差异说明有人改了描述文件但忘了重新渲染提交CI直接失败并提示。这样做的好处是图表永远不会和描述文件脱节。任何人改了描述文件CI会强制要求同步更新渲染结果。虽然多了一步操作但保证了文档的一致性。注意如果团队用的是Git LFS管理图片CI里的diff检查需要额外处理LFS指针文件否则会误报。4.4 本地开发时的预览方案CI流程保证了最终一致性但本地开发时总不能每次都等CI跑完再看效果。我通常会在本地装一个文件监听工具描述文件一保存就自动重新渲染。以D2为例可以用entr或者watchexec来实现ls docs/diagrams/**/*.d2 | entr -s bash scripts/render-diagrams.sh这样每次保存描述文件脚本自动重新渲染配合支持SVG预览的编辑器可以做到近乎实时的反馈。如果编辑器不支持SVG预览可以额外生成一份PNG用于快速查看。另外很多文本绘图工具都有在线编辑器可以在浏览器里实时预览。对于复杂的图我有时会先在在线编辑器里调好布局和样式再把最终代码复制回项目文件里。这样比反复改文件、渲染、查看要快得多。5. 实际落地时最容易踩的五个坑5.1 布局失控节点一多就乱成一团文本绘图最大的痛点就是布局控制。自动布局算法在节点少的时候表现不错但节点一多、连接一复杂就容易出现箭头交叉、节点重叠、留白不均等问题。我踩过最惨的一次是一张有三十多个节点的架构图自动布局渲染出来完全没法看。后来花了两个小时手动调整节点分组和连接顺序才勉强能看。但下次改一个节点布局又全乱了。应对策略对于复杂图不要指望一次自动布局就完美。我的做法是先把节点按逻辑分组用子图或容器把相关节点框在一起。这样布局算法会先在组内布局再在组间布局结果通常可控得多。另外适当调整节点的声明顺序也会影响布局结果把关联紧密的节点放在一起声明往往能得到更合理的布局。5.2 中文字体渲染异常这个问题在PlantUML和Graphviz上尤其常见。默认字体配置里往往没有中文字体渲染出来的中文要么是方框要么是乱码。应对策略在主题配置里显式指定中文字体。以PlantUML为例可以在文件开头加上skinparam defaultFontName Noto Sans CJK SC skinparam defaultFontSize 14D2的话可以在主题文件里配置font-family。关键是要确保渲染环境里确实安装了对应的字体否则指定了也没用。在CI环境里可能需要在构建镜像里预装中文字体包。5.3 版本升级导致的渲染差异文本绘图工具也在不断迭代新版本可能改变了默认布局算法或样式。这会导致同一个描述文件在不同版本的渲染器下输出不同的结果。我遇到过最典型的情况是本地渲染出来的图和CI渲染出来的图不一致排查半天才发现是两边工具版本不同。应对策略在项目里锁定渲染工具的版本。如果是Node生态的工具用package.json锁定版本如果是二进制工具在CI配置里指定下载特定版本。另外可以在项目README里注明推荐的渲染环境方便新成员快速对齐。5.4 图表描述文件本身的可维护性文本描述虽然比二进制文件好维护但如果写得随意一样会变成“屎山”。我见过一个描述文件写了上千行节点命名混乱、没有注释、逻辑分组不清改起来比重新画还痛苦。应对策略把描述文件当代码来写。节点命名要有意义用注释分隔逻辑区块复杂图拆成多个文件而不是堆在一个文件里。如果多个图共享部分节点定义可以考虑用工具提供的include或import机制来复用。5.5 输出图片的体积控制SVG虽然好但如果图特别复杂文件体积也会很大。我见过一张包含几百个节点的SVG超过2MB放在网页里加载明显变慢。应对策略对于特别复杂的图可以考虑拆分成多张子图或者输出时做适当的简化。另外渲染时可以选择性地嵌入字体或使用系统字体避免把字体文件打包进SVG。如果目标平台对图片体积敏感可以在CI流程里加一个体积检查超过阈值就告警。6. 让图表描述真正好用的几个进阶技巧6.1 用变量和模板减少重复很多文本绘图工具支持变量和模板机制。比如D2支持用vars定义变量在多个地方引用。这样改一个变量值所有引用处自动更新。vars: { db-color: #4A90D9 } database: { style.fill: ${db-color} }对于需要生成多张相似结构的图模板机制尤其有用。可以定义一个基础模板然后通过参数生成不同模块的图。这样既保证了风格统一又减少了重复劳动。6.2 从代码或配置反向生成图表手动维护图表描述文件的一个风险是它可能和实际代码脱节。更可靠的做法是从代码或配置反向生成图表。比如从数据库schema生成ER图从API定义生成时序图从基础设施配置文件生成部署图。这样图表永远是代码的“投影”不会出现文档和实现不一致的情况。实现方式可以是写一个脚本读取代码或配置输出图表描述文件再走正常的渲染流程。这个脚本可以放在CI里定期执行确保图表始终最新。6.3 多视图管理一张模型生成多张图在架构文档里经常需要从不同角度展示同一个系统。比如一张总览图、一张数据流图、一张部署图。如果每张图都单独维护很容易出现不一致。更好的做法是维护一个统一的模型描述然后从中生成多个视图。Structurizr就是这种思路的典型代表。即使不用Structurizr也可以自己组织描述文件把共享的节点定义抽出来不同视图引用同一份定义。6.4 图表描述的代码审查要点既然图表描述文件是代码的一部分那它也应该被review。我在团队里推行的review要点包括节点命名是否清晰、是否符合项目术语规范连接关系是否准确反映了实际逻辑是否有不必要的节点或连接可以简化样式配置是否引用了统一的主题变量复杂图是否有适当的注释和分组这些检查看起来琐碎但能有效防止图表描述文件随着时间推移变得难以维护。6.5 输出格式的选择策略不同场景需要不同的输出格式。我的经验是文档内嵌优先SVG矢量清晰、体积可控演示投屏PNG高分辨率版避免某些投屏软件对SVG支持不好打印输出PDF或高DPI的PNG网页展示SVG配合适当的CSS控制可以在渲染脚本里配置多种输出格式按需生成。不需要所有格式都提交到仓库只提交最常用的那一种其他格式在需要时临时生成。7. 我个人在实际操作中的几点体会说了这么多方法和技巧最后聊几点我自己的真实感受。文本驱动图表这件事最大的价值不在于“画图更快”而在于把图表变成了可管理、可协作、可追溯的工程资产。以前图表是文档的附属品改不改、什么时候改全凭自觉。现在图表和代码一样有版本、有review、有CI检查质量自然就上去了。但也不要走极端不是所有图都值得文本化。我现在的做法是逻辑性强、需要频繁更新的图用文本驱动一次性展示、注重视觉效果的图还是用传统工具。两者不是替代关系而是互补关系。另外工具选型不要追求“一步到位”。我见过团队花大量时间对比各种方案结果迟迟不动手。其实随便选一个上手最快的先用起来在实际使用中自然会知道哪里不够用再针对性调整。Mermaid也好D2也好核心思路是相通的学会一个再换另一个成本并不高。最后分享一个小技巧如果你刚开始尝试文本绘图可以先从时序图入手。时序图的逻辑最线性文本描述和最终图形之间的对应关系最直观上手最快也最容易感受到文本驱动的优势。等熟悉了基本流程再尝试流程图和架构图循序渐进。