1. 从diagram-design这个标题里能读出什么第一次看到diagram-design这个标题我脑子里蹦出来的第一个念头是这大概率不是一个单纯的画图工具推荐而是一个关于如何用代码或结构化方式去设计和生成图表的项目。为什么这么判断因为如果只是推荐几个在线画图网站标题通常会写成好用的画图工具合集或者架构图绘制指南之类而diagram-design这种命名方式更像是把图表当成一个可以被设计、被编程、被系统化管理的对象。我在实际工作中接触过大量和图表打交道的场景技术方案评审要画架构图项目复盘要画流程图给非技术同事讲数据要画柱状图饼图写文档要嵌入时序图。这些场景有一个共同的痛点——图表的维护成本极高。你辛辛苦苦用鼠标拖拽出来的图一旦业务逻辑变了就得重新拖一遍团队里每个人画图风格不一样拼在一起像打了补丁更别提把图表纳入版本管理几乎是不可能的事。所以当我看到diagram-design这个标题时我理解它背后真正要解决的问题是如何把图表从手工艺术品变成可维护的工程产物。这个转变的核心思路就是用文本描述来定义图表让图表像代码一样可以被编辑、被复用、被版本控制。这也是我接下来要展开讲的完整方法论。这篇文章适合三类人看第一类是被画图折磨过的开发者想找到更高效的图表工作流第二类是技术文档写作者需要频繁产出架构图和流程图第三类是对图表即代码这个概念好奇、想系统了解的人。不管你是哪一类我都会从原理到实操把这条链路讲透。2. 图表即代码为什么文本定义比鼠标拖拽更靠谱2.1 鼠标拖拽画图的三个致命伤先说清楚为什么传统画图方式在工程场景下会出问题。我用过市面上几乎所有主流的拖拽式画图工具它们在做一次性演示时确实方便但一旦进入需要长期维护的项目问题就暴露了。第一个问题是不可diff。你用鼠标拖出来的图本质上是一堆坐标和图形对象的集合保存成二进制或者私有格式后根本没法看出这次改动到底改了什么。而文本定义的图表改动一行代码git diff 清清楚楚告诉你哪个节点加了、哪条连线删了。这在团队协作里太重要了评审的时候不用盯着两张图找不同。第二个问题是风格不统一。十个人用拖拽工具画图能画出十种风格有人喜欢圆角矩形有人喜欢直角有人用蓝色表示服务有人用绿色。文本定义图表可以通过统一的主题配置来强制约束风格所有人产出的图天然一致。第三个问题是复用性差。一个系统架构图里的某个子系统在另一个项目里可能也要用。拖拽方式下你只能复制粘贴改一处还得手动同步另一处。文本定义可以把公共部分抽成模块通过引用和参数化来复用改一处全局生效。2.2 文本定义图表的底层逻辑图表即代码的核心逻辑其实很简单用一套领域特定语言DSL描述图的元素和关系再由渲染引擎把它转成图形。你描述的是有什么和连什么而不是画在哪和多大。打个比方这就像写HTML和用可视化编辑器做网页的区别。可视化编辑器你拖一个按钮到某个位置HTML里就是绝对定位的坐标而手写HTML你写的是一个按钮元素具体位置由布局引擎决定。前者精确但脆弱后者抽象但健壮。图表也是同样的道理你关心的是服务A调用服务B这个关系而不是这条线从坐标(100,200)画到(300,400)。这种抽象带来的好处是渲染引擎可以自动处理布局。节点多了自动排版连线交叉了自动优化路径你不需要手动去调。当然代价是你对最终视觉效果的控制力会弱一些但对于技术图表来说清晰传达信息比视觉炫酷重要得多。2.3 哪些场景适合哪些场景不适合不是所有图表都适合用文本定义。我总结了一个简单的判断标准场景类型是否适合文本定义原因系统架构图非常适合节点关系明确需要频繁更新流程图/时序图非常适合逻辑性强天然适合结构化描述数据图表适合数据本身结构化图表只是呈现思维导图较适合层级关系清晰但自由布局需求高品牌视觉设计图不适合对视觉细节要求极高需要精细控制手绘风格插画不适合艺术性表达无法用规则描述一次性演示草图看情况如果只是临时用拖拽可能更快我的经验是只要这张图需要被维护超过一次就值得用文本定义。如果画完就扔那拖拽确实更省事。3. 主流文本图表方案的能力边界与选型对比3.1 几类方案的定位差异文本定义图表这个领域方案其实不少但它们的定位和能力边界差别很大。我大致把它们分成三类第一类是通用图表DSL比如Mermaid和PlantUML。这类方案的特点是语法简单、上手快、支持的图表类型多。Mermaid的语法接近Markdown写起来很直观PlantUML功能更强大支持的图表类型更丰富但语法相对复杂一些。它们的共同优势是生态好大量文档工具和代码托管平台都原生支持渲染。第二类是专业绘图语言比如Graphviz的DOT语言。这类方案更偏向底层表达能力极强几乎可以描述任何图结构但学习曲线陡峭而且默认的视觉效果比较朴素需要额外配置才能好看。它更适合需要程序化生成大量图表的场景。第三类是代码驱动绘图库比如用Python的Matplotlib、Plotly或者JavaScript的D3.js。这类方案本质上是写代码来画图灵活度最高但工作量也最大适合数据可视化这种需要精细控制的场景。3.2 选型时我实际关注的几个维度选哪个方案不能只看功能列表得结合你的实际工作流。我一般从这几个维度去评估渲染环境。你的图表最终在哪里展示如果是代码仓库的README那Mermaid几乎是唯一选择因为主流代码托管平台都原生支持。如果是技术文档站点PlantUML和Mermaid都能集成。如果是PPT或Word那可能需要先渲染成图片再插入。团队接受度。这一点经常被忽略。你选了一个很强大的方案但团队里没人愿意学最后还是回到拖拽工具。Mermaid之所以流行很大程度上就是因为它的语法足够简单前端后端测试都能快速上手。版本控制友好度。所有文本方案在这方面都天然有优势但差异在于语法是否稳定、diff是否可读。Mermaid的语法改动通常只影响一两行diff很清晰而某些方案的语法嵌套很深改一个结构可能导致大段重排。可扩展性。如果你需要自定义节点样式、自定义布局算法那通用DSL可能就不够用了得考虑代码驱动的方式。但对于绝大多数技术图表需求通用DSL已经足够。3.3 一个容易踩的坑渲染一致性这里要特别提醒一个坑。文本定义图表虽然源码一致但不同渲染引擎产出的效果可能不一样。同一个Mermaid文件在代码托管平台上看和在你本地工具里看布局可能不同颜色可能不同甚至某些语法支持程度都不同。我踩过这个坑在本地编辑器里预览好好的图推到代码仓库后布局全乱了因为两边用的渲染引擎版本不同。解决办法是尽量使用最基础的语法特性避免依赖特定渲染器的扩展功能。如果必须用扩展功能那就在目标平台上先验证一遍。4. 从零搭建一套可维护的图表工作流4.1 目录结构怎么组织如果你决定在项目里系统性地使用文本图表第一件事是把目录结构规划好。我的建议是按图表类型或业务模块分目录而不是把所有图都堆在一个文件夹里。一个我实际用过的结构是这样的docs/ diagrams/ architecture/ system-overview.mmd >// mermaid-config.js const config { theme: base, themeVariables: { primaryColor: #e1f5fe, primaryTextColor: #01579b, primaryBorderColor: #0288d1, lineColor: #546e7a, fontSize: 14px } };然后在渲染时统一加载这个配置。这样所有图表天然风格一致改主题只需要改一个文件。我在一个项目里就是这么做的后来产品要求换配色方案我只花了五分钟改配置所有图全部同步更新如果用拖拽工具那得一张一张改。4.3 把图表纳入CI流程这是进阶玩法但价值很大。你可以把图表渲染纳入持续集成流程每次提交代码时自动检查图表语法是否正确、是否能正常渲染。具体做法是写一个脚本遍历所有图表源文件调用渲染引擎尝试渲染如果失败就报错。这样能避免提交了一个语法错误的图表等到别人看文档时才发现的尴尬。我用Node.js写过一个简单的检查脚本核心逻辑就是读取文件、调用渲染API、捕获异常const fs require(fs); const path require(path); const mermaid require(mermaid); async function validateDiagrams(dir) { const files fs.readdirSync(dir).filter(f f.endsWith(.mmd)); let hasError false; for (const file of files) { const content fs.readFileSync(path.join(dir, file), utf-8); try { await mermaid.parse(content); console.log(PASS: ${file}); } catch (e) { console.error(FAIL: ${file} - ${e.message}); hasError true; } } process.exit(hasError ? 1 : 0); }这个脚本挂到CI里每次PR都会跑图表语法错误在合并前就能拦住。5. 实战中那些文档不会告诉你的细节5.1 节点命名与ID的取舍写文本图表时每个节点都要有个ID。新手常犯的错误是用中文或者带空格的字符串当ID结果渲染报错。正确的做法是用简短的英文标识符当ID用显示文本来呈现中文内容。比如Mermaid里flowchart LR A[用户服务] -- B[订单服务] B -- C[支付服务]这里的A、B、C是ID方括号里才是显示文本。ID尽量短因为连线的时候要反复引用。我见过有人用userServiceNode这种长ID结果连线代码又长又难读。5.2 布局方向的玄学文本图表的布局是引擎自动算的但你可以通过方向参数来引导。Mermaid里用LR表示从左到右TD表示从上到下。听起来简单但实际效果经常出乎意料。我的经验是节点少的时候方向影响不大节点一多方向选错图就没法看。比如一个十几步的流程用从左到右会拉得特别长屏幕根本放不下改成从上到下就舒服多了。反过来如果是一个层级很深的树状结构从左到右可能比从上到下更紧凑。还有一个技巧是用子图subgraph来分组。把相关的节点放进一个子图里引擎会倾向于把它们排在一起整体布局会清晰很多。这个技巧在处理复杂架构图时特别有用。5.3 连线太多时的处理策略当一个节点连出十几条线时图会变成一团乱麻。这时候有几个策略第一是分层。把直接相连的节点放在一层间接相连的放在下一层用子图或者分组来体现层次。这样连线会集中在相邻层之间不会到处乱窜。第二是抽象。如果某个节点连了太多东西考虑把它拆成几个逻辑子节点或者把一组连线归纳成一条批量连线。图表的目的是传达核心关系不是穷举所有细节。第三是换图表类型。如果关系实在太复杂可能流程图或架构图本身就不是最合适的表达方式考虑换成时序图或者状态图用不同的视角来呈现。5.4 中文渲染的字体问题这个问题在本地渲染时特别常见。文本图表里的中文如果渲染环境没有配置合适的中文字体会显示成方块或者乱码。解决办法是在渲染配置里指定中文字体。比如用命令行工具渲染时通过参数指定字体文件路径。如果是集成到文档站点那要在站点的CSS里确保中文字体被正确加载。我一般会准备一个包含常用中文字体的配置在不同环境里复用。6. 图表维护的长期主义版本管理与协作规范6.1 图表源文件应该和代码一起管理我见过不少团队把图表源文件单独放在一个文档仓库里和代码仓库分离。这种做法短期看没问题长期看一定会导致图表和代码不同步。正确的做法是图表源文件跟着代码走。哪个模块的架构图就放在哪个模块的目录下。代码改了图表跟着改在同一个PR里提交。这样评审代码的时候顺便就把图表也评审了不会出现代码早就改了图还是半年前的这种情况。6.2 提交信息里写清楚图表改动图表改动也是改动提交信息里要写清楚。我一般要求团队在提交信息里注明更新XX架构图新增XX服务节点之类的说明。这样回溯历史的时候能快速定位到某次图表改动的原因。如果图表改动比较大建议在PR描述里附上渲染后的截图。虽然文本图表可以diff但视觉上的变化还是看图更直观。很多代码托管平台支持在PR里嵌入图片用起来很方便。6.3 建立图表评审的checklist图表评审不能只看好不好看更要看准不准。我整理过一个简单的checklist团队评审图表时逐条对照节点名称是否和实际服务名一致连线方向是否反映了真实的调用关系是否遗漏了重要的依赖或数据流图例和标注是否清晰是否有过时的节点需要删除布局是否清晰有没有明显的连线交叉这个checklist看起来简单但能拦住大部分低级错误。特别是节点名称一致性这一条我见过太多图表里写的是用户中心代码里叫user-service对不上号。6.4 定期清理过时图表图表和代码一样会随着时间腐化。我建议每个季度做一次图表审查把已经不再反映现状的图要么更新要么删除。留着过时的图比没有图更糟糕因为它会误导人。删除图表的时候记得在提交信息里说明原因比如XX功能已下线移除对应流程图。这样以后有人找这张图能知道它为什么消失了。7. 我在这条路上踩过的几个真实坑7.1 过度设计把简单图画复杂了刚开始用文本图表时我特别兴奋觉得什么都能用代码描述。结果有一次画一个简单的三层架构图我非要搞参数化、搞模块复用写了上百行配置最后渲染出来还不如手画五分钟的效果好。这个坑的教训是工具是为目的服务的不要为了用工具而用工具。简单的图就用简单的写法别过度抽象。我现在画图的原则是能用十行搞定的绝不写二十行。7.2 忽略渲染性能大图渲染卡死有一次我画一个包含几百个节点的依赖关系图源文件写完后渲染引擎直接卡死了浏览器标签页崩溃。后来才知道某些渲染引擎在处理大规模图时性能很差。解决办法是分而治之。几百个节点的图拆成几张子图每张控制在几十个节点以内。如果确实需要全局视图那就用抽象节点把细节折叠起来。图表是给人看的人一次能处理的节点数量本来就有限画那么大也没人看得清。7.3 版本升级导致的语法不兼容文本图表工具也在不断迭代有时候新版本会修改语法或者废弃某些写法。我就遇到过升级渲染引擎后之前好好的图突然渲染报错的情况。应对策略是锁定版本。在项目里明确指定渲染引擎的版本号不要用最新版。升级版本时先在测试环境把所有图表跑一遍确认没问题再正式升级。这个习惯能省掉很多半夜排查问题的痛苦。7.4 团队推广时的阻力最后说一个非技术层面的坑。你个人觉得文本图表很好想推广到团队但总会有人抵触觉得学新东西太麻烦拖拽挺好的。我的经验是不要强推先做示范。你自己先用文本图表产出几张高质量的图在评审和文档里展示效果。当别人发现你的图更新及时、风格统一、改起来快自然会来问你怎么做的。这时候再分享方法接受度会高很多。技术推广从来都是吸引比说服有效。8. 关于图表设计的一点个人体会写了这么多技术和流程最后想聊聊设计这个层面。文本定义图表解决的是怎么画的问题但画什么和怎么画得好是另一回事。我越来越觉得一张好的技术图表核心不在于用了多炫的工具而在于信息层次是否清晰。什么是主要信息什么是次要信息什么是可以省略的细节这些判断比工具选择重要得多。文本定义图表的好处是它逼着你去思考这些关系因为你要把每个节点和连线都显式地写出来写的过程中自然会想这个真的需要画吗。另外一点体会是图表是给人看的不是给机器看的。不要为了追求完整的自动化而牺牲可读性。有时候手动调整一下布局、加一个注释比追求纯文本定义更实际。工具是手段传达信息才是目的。我现在的工作流是用文本定义图表作为主力因为它可维护、可版本控制、风格统一但在最终呈现时如果发现某些细节需要微调也不排斥导出后做少量手工优化。这种文本为主、手工为辅的混合方式是我试过最舒服的平衡点。