1. 从一张草图到一套系统diagram-design 到底在解决什么问题第一次看到 “diagram-design” 这个标题很多人会下意识觉得它只是“画图”或者“做图表美化”。但真正在项目里摸爬滚打过的人都知道图这件事从来不是审美问题而是信息架构问题。一张图能不能让人三秒看懂取决于你在画之前有没有想清楚“谁看、看什么、看完做什么”。diagram-design 这个项目本质上是在解决一个非常具体的痛点团队里每个人都在画图但画出来的东西风格不一、语义混乱、维护成本极高最后图比代码还难改。我见过太多项目架构图是半年前某位同学用某款在线工具随手拖的流程图是另一位同学用另一款工具导出的时序图干脆是截图贴进文档的。结果就是新人看不懂、老人懒得改、评审时没人敢动。diagram-design 要做的不是再教你一个画图工具而是建立一套可复用、可版本化、可协作的图表设计系统。它适合谁适合那些已经过了“能画出来就行”阶段开始被图表一致性、可维护性折磨的团队也适合独立开发者希望自己的项目文档看起来不那么“野生”。核心关键词其实就三个图表即代码、设计令牌、语义一致性。这三个词后面我会反复拆开讲因为它们决定了你是“画图的人”还是“设计系统的人”。这篇文章我会从整体思路、核心细节、实操过程、常见坑四个层面把 diagram-design 这套东西彻底讲透尽量让你看完就能在自己项目里落地。2. 整体设计与思路拆解为什么不是“找个好用的画图工具”2.1 图表即代码把图从画布上拽回仓库里传统画图工具最大的问题是图和数据分离。你画了一张架构图它存在某个云端账号里和你的代码仓库没有任何关系。代码改了图不会自动变图改了没人知道改了什么。diagram-design 的第一个核心决策就是把图表定义成文本放进版本控制。这背后的逻辑很简单凡是能被 diff 的东西就能被 review凡是能被 review 的东西就能被维护。你用文本描述节点和连线用 Git 管理变更图就不再是“某个人电脑里的神秘文件”而是和代码一样的一等公民。我试过在几个中型项目里推行这种方式最大的感受是图终于有人敢改了。因为改图变成了改几行文本而不是打开一个复杂的图形界面重新拖拽。具体实现上常见的选择是 Mermaid、PlantUML、Graphviz 这类文本转图工具。diagram-design 并不绑定某一个而是强调“定义与渲染分离”。你写的是语义化的图表描述渲染器负责把它变成 SVG 或 PNG。这样即使以后换渲染器你的图表定义还在不会推倒重来。2.2 设计令牌让所有图长得像一家人第二个核心决策是设计令牌Design Token。这个词在前端圈不新鲜但在图表领域很少有人认真用。所谓设计令牌就是把颜色、字体、间距、圆角、线宽这些视觉决策从具体的图里抽出来变成一套全局变量。为什么这件事重要因为当你有十张图的时候最怕的就是每张图的蓝色都不一样、每张图的字号都差一点。评审的时候没人会明说但整体观感就是“不专业”。diagram-design 的思路是先定义一套令牌比如color-primary、color-danger、font-size-node、stroke-width-edge然后所有图表都引用这些令牌。改一个令牌所有图同步更新。我个人的经验是令牌不要一上来就搞几十个。先从最核心的六个开始主色、辅色、警示色、节点字号、连线粗细、背景色。等团队习惯了再慢慢扩展。令牌太多反而没人记得住最后又回到“随手填色”的老路。2.3 语义一致性图里的每个形状都有固定含义第三个决策最容易被忽略但影响最深语义一致性。什么意思就是在你的图表系统里圆角矩形永远代表服务菱形永远代表判断虚线永远代表异步调用实线永远代表同步调用。一旦定下来所有图都必须遵守。这件事的价值在于降低认知负担。读者看第一张图的时候需要学习你的图例看第二张图的时候就不需要了因为规则没变。我见过一个团队架构图里圆角矩形一会儿是服务、一会儿是数据库结果每次评审都要花十分钟解释“这个框到底是什么”。diagram-design 要求你把图例当成 API 文档一样维护形状和语义的映射关系是契约不能随便改。这三个决策合在一起构成了 diagram-design 的骨架文本定义保证可维护设计令牌保证一致性语义规则保证可读性。缺一个系统就会退化成“另一套画图工具”。3. 核心细节解析与实操要点从零搭一套图表系统3.1 工具选型Mermaid、PlantUML 还是自研渲染选型这件事没有标准答案但有几个判断维度。Mermaid 的优势是生态好、Markdown 原生支持、上手快适合流程图、时序图、状态图这类常见图表。缺点是样式定制能力有限复杂布局容易失控。PlantUML 的表达能力更强支持更多图类型样式控制也更细但学习曲线陡一些渲染依赖 Java 环境。Graphviz 适合关系网络和依赖图自动布局能力强但写起来偏底层。我的建议是如果团队已经在用 Markdown 写文档优先 Mermaid如果图表复杂度高、样式要求严选 PlantUML如果是依赖关系分析类场景考虑 Graphviz。diagram-design 不要求你只选一个可以按图类型分工。但要注意工具越多令牌同步的成本越高所以最好控制在两种以内。提示不要因为“某个工具看起来更酷”就选它。选型的核心是团队里有多少人愿意学、维护成本能不能接受。3.2 令牌定义用 JSON 还是 YAML以及放在哪令牌的定义文件我推荐用 YAML因为可读性好注释方便非技术同学也能看懂。放在仓库根目录的design/tokens.yaml下和代码一起版本控制。结构上分三层基础令牌、语义令牌、组件令牌。基础令牌是原始值比如blue-500: #3B82F6。语义令牌是用途映射比如color-primary: {blue-500}。组件令牌是具体图表元素的引用比如node-fill: {color-primary}。这样分层的好处是改基础值不影响语义改语义不影响组件每一层职责清晰。# design/tokens.yaml base: blue-500: #3B82F6 gray-100: #F3F4F6 gray-800: #1F2937 semantic: color-primary: {base.blue-500} color-bg: {base.gray-100} color-text: {base.gray-800} component: node-fill: {semantic.color-primary} node-text: {semantic.color-text} canvas-bg: {semantic.color-bg}实测下来这套结构在三个项目里都跑得通。唯一要注意的是令牌命名要有约定比如颜色用color-前缀字号用font-前缀避免命名混乱。3.3 图表模板把重复劳动变成填空diagram-design 里最省时间的一环是图表模板。你不可能每次都从零写一个时序图所以要把常见场景做成模板服务调用、数据流、状态机、部署拓扑。模板里预置好节点样式、连线样式、图例说明使用者只需要填业务内容。比如一个服务调用时序图模板预置了参与者声明、消息箭头样式、激活框样式使用者只需要改参与者名字和消息内容。这样出来的图风格天然统一因为样式部分根本不需要使用者碰。我踩过的一个坑是模板做得太死使用者遇到特殊情况没法扩展。后来改成“模板 覆盖”模式模板提供默认值使用者可以局部覆盖灵活性就上来了。这个思路和前端组件库的“默认样式 可覆盖”是一回事。3.4 渲染流水线本地预览与 CI 自动出图图定义好了怎么变成可看的图本地预览用命令行工具比如mmdc或plantuml -pipe配合编辑器的预览插件写的时候就能看到效果。CI 里加一步自动渲染每次提交图表定义自动生成 SVG 并归档到文档目录。这样做的好处是图永远和代码同步。代码合并了图也更新了不会出现“文档里的图还是上个版本”的情况。渲染产物建议只保留 SVG因为矢量图放大不糊而且文本可搜索。PNG 只在需要嵌入不支持 SVG 的平台时才生成。注意CI 渲染要设置超时和失败告警。我遇到过图表定义有语法错误CI 卡了十分钟才报错体验很差。加个语法检查前置步骤能省很多时间。4. 实操过程与核心环节实现一个完整案例的拆解4.1 场景设定给一个模拟项目画架构图假设我们有一个模拟项目 X包含网关、用户服务、订单服务、消息队列、数据库五个组件。需求是画一张架构图要求风格统一、可版本化、后续能扩展。下面按 diagram-design 的流程走一遍。第一步确认语义规则。圆角矩形代表服务圆柱代表数据库平行四边形代表消息队列实线代表同步调用虚线代表异步消息。这些规则写进design/legend.md作为团队约定。第二步定义令牌。主色用蓝色系数据库用绿色系消息队列用橙色系背景浅灰文字深灰。令牌文件按 3.2 的结构写好。第三步写图表定义。用 Mermaid 的 flowchart 语法节点样式引用令牌对应的 class。flowchart LR GW[网关]:::service US[用户服务]:::service OS[订单服务]:::service MQ[[消息队列]]:::queue DB[(数据库)]:::database GW -- US GW -- OS US -- DB OS -- DB OS -.- MQ classDef service fill:#3B82F6,color:#fff,stroke:#1F2937 classDef queue fill:#F59E0B,color:#fff,stroke:#1F2937 classDef database fill:#10B981,color:#fff,stroke:#1F2937第四步渲染并检查。本地预览确认布局合理连线没有交叉混乱。如果节点太多考虑拆成多张图而不是硬塞进一张。第五步提交并归档。CI 自动渲染 SVG归档到docs/diagrams/下文档里引用生成的 SVG。4.2 参数计算字号、间距、线宽怎么定视觉参数不是拍脑袋定的有几个经验公式。字号方面节点文字建议 14px 到 16px太小看不清太大图会显得臃肿。如果图要投影展示字号至少 18px。间距方面节点之间的水平间距建议是节点宽度的 1.5 倍垂直间距是节点高度的 2 倍这样连线有足够空间不会挤在一起。线宽方面主流程线建议 2px辅助线 1px强调线 3px。圆角半径建议 4px 到 8px太小看不出圆角太大显得卡通。这些值不是绝对的但作为起点很稳。我一般会把这些参数也放进令牌文件改起来方便。4.3 实操现场记录一次真实的迁移过程之前帮一个团队把散落的图迁移到 diagram-design 体系过程大致是这样。第一周盘点现有图表按类型分类统计有多少张、用了哪些工具、哪些还在维护。结果发现 60% 的图已经过期直接废弃。第二周定义令牌和语义规则团队评审通过。第三周把核心的十张图用文本重写边写边调整模板。第四周接入 CI培训团队使用。整个过程最大的阻力不是技术是习惯。有人觉得“我直接拖一下更快”这时候需要用数据说话迁移后改一张图平均耗时从 20 分钟降到 3 分钟评审时关于“图为什么这样画”的讨论减少了一半。数据摆出来抵触就小了。提示迁移不要追求一次到位。先把最核心的图迁了让团队尝到甜头再逐步铺开。一次性全迁容易烂尾。5. 常见问题与排查技巧实录踩过的坑和绕过的弯5.1 图表渲染失败语法、依赖、编码三宗罪渲染失败是最常见的问题原因基本逃不出三类。语法错误最常见比如 Mermaid 里节点名带特殊字符没转义、箭头方向写错。排查方法是把图表定义单独拿出来用最小可复现的片段测试。依赖问题多见于 PlantUMLJava 版本不对或者 Graphviz 没装都会导致渲染失败。编码问题容易被忽略中文节点名在某些渲染器下会乱码解决办法是统一用 UTF-8并在渲染命令里显式指定编码。问题现象可能原因排查方法解决方案渲染报语法错误特殊字符未转义最小片段测试转义或改用引号包裹渲染卡住无输出依赖缺失检查 Java/Graphviz安装对应依赖中文显示乱码编码不一致检查文件编码统一 UTF-8布局混乱节点过多数节点和连线拆分为多张图5.2 样式不生效优先级和继承的坑样式不生效通常是优先级问题。比如你在令牌里定义了节点填充色但图表定义里又写了内联样式内联样式优先级更高令牌就被覆盖了。解决办法是约定“图表定义里不写具体颜色只写语义 class”颜色统一由令牌控制。另一个坑是继承。某些渲染器里父节点的样式会继承给子节点导致你以为没生效其实是生效了但被继承覆盖。排查方法是把样式作用范围缩小逐个节点确认。5.3 团队协作图改了没人知道怎么办这是流程问题不是技术问题。解决办法是把图表定义纳入代码评审流程改图必须走 PRPR 里附上渲染后的预览图。这样每次改动都有记录、有 review、有预览。我试过在 PR 模板里加一个“图表变更”勾选项提醒作者附上预览效果不错。还有一个技巧是给图表定义加 owner 字段标明谁负责维护。图过期了直接找 owner不会出现“没人管”的情况。5.4 独家避坑技巧三个血泪教训第一个教训不要用图表工具画图例。图例应该是文本和图表定义放在一起渲染时自动生成。手动画的图例改一次忘一次最后图例和图对不上。第二个教训节点命名用英文 ID显示名用中文。英文 ID 稳定改显示名不影响引用关系。我见过有人直接用中文当节点 ID改个名字所有连线都断了。第三个教训图表定义也要写注释。半年后你自己都忘了某个节点为什么这么连注释能救命。注释不用多一句话说明业务含义就行。6. 图表系统的扩展与长期维护6.1 从静态图到交互式文档diagram-design 做到后面可以往交互式方向走。比如生成的 SVG 里嵌入链接点击节点跳到对应的代码仓库或文档页面。这样图就不只是图而是导航入口。实现方式是在图表定义里给节点加链接属性渲染时保留为 SVG 的a标签。这个扩展的价值在于图和代码真正连起来了。新人看架构图点一下就能看到服务代码学习成本大幅降低。我试过在一个项目里做这个新人的上手时间从两周缩短到三天。6.2 图表即测试用图验证架构约束更进一步可以把图表定义当成架构约束的载体。比如规定“用户服务不能直接调用订单服务的数据库”这条规则可以写成检查脚本解析图表定义发现违规连线就报错。这样图就不只是文档而是架构的守卫者。实现上解析 Mermaid 或 PlantUML 的文本定义提取节点和连线关系和预定义的规则比对。规则可以用简单的 DSL 描述比如no-direct: 用户服务 - 数据库。这个思路在几个项目里验证过能提前发现架构漂移。6.3 长期维护令牌版本化与废弃策略令牌用久了总会有废弃和替换。这时候要有版本化策略。比如color-primary要换成color-brand不能直接删要先标记废弃保留一个版本周期让所有图表有时间迁移。迁移完成后再删除旧令牌。废弃标记可以写在令牌文件的注释里CI 检查时如果发现还在引用废弃令牌给出警告。这样既保证平滑过渡又不会让废弃令牌永远留着。注意令牌废弃一定要有截止日期否则永远迁不完。我一般给一个季度的过渡期到期强制删除。7. 我个人在实际操作中的体会这套东西我前后在四个项目里落地过最大的体会是diagram-design 的难点从来不是工具而是共识。工具再好团队不遵守语义规则图还是会乱。所以推行的时候先把规则定简单简单到大家愿意遵守再慢慢加细节。一开始就搞一套复杂的规范大概率没人理。另一个体会是图的价值在于被看不在于被画。很多人花大量时间把图做得精美但没人看等于白做。diagram-design 强调语义一致和可维护本质上是为了让图更容易被看懂、被信任。一张能随时更新、风格统一的图比十张精美但过期的图有价值得多。最后分享一个小技巧每次评审的时候让看图的人先说“这张图告诉我什么”如果他说出来的和你预期的一致说明图合格了如果不一致别急着解释先改图。图是给人看的不是给自己看的。这个习惯坚持下来你的图表设计能力会提升得很快。