1. 从一张草图到一套系统diagram-design 到底在解决什么问题第一次看到 “diagram-design” 这个项目标题很多人会以为它只是某个画图工具的皮肤或者模板集合。但真正做过系统设计、技术方案评审、跨团队对齐的人会立刻意识到图不是画给自己看的是画给别人看的。一张好的架构图、流程图、状态机图能让一场两小时的会议压缩到二十分钟一张糟糕的图能让一群聪明人在同一个问题上反复绕圈。diagram-design 这个项目核心就是围绕“如何把复杂系统用图讲清楚”这件事提供一套可复用的设计方法、结构规范和落地工具链。它要解决的问题非常具体团队里每个人都会用不同的工具画图有人用在线白板有人用代码生成有人直接截图 PPT最后导致图与图之间风格割裂、语义不一致、维护成本极高。更麻烦的是当系统迭代之后图往往没人更新慢慢变成“历史文物”谁也不敢信。这个项目适合三类人参考。第一类是技术负责人或架构师需要频繁输出系统全景图、部署图、时序图并且希望这些图能跟着代码一起演进。第二类是产品经理和项目管理者需要把业务流程、状态流转、角色权限用图表达清楚减少和研发之间的理解偏差。第三类是独立开发者和技术博主需要一套低成本、可版本管理、能快速出图的方案而不是每次打开笨重的桌面软件从头拖拽。我自己的经历是早期做项目时用纯手工拖拽工具画架构图每次改一个模块名字就要重新对齐半天后来换成代码生成图的方案又发现团队里非技术同学完全无法参与修改。diagram-design 这类项目之所以有价值是因为它在“手工拖拽的灵活”和“代码生成的严谨”之间找到了一个可操作的中间地带。接下来我会从整体设计思路、核心细节、实操过程、常见问题四个层面把这件事拆开讲透。2. 整体设计思路为什么是“规范先行工具后置”2.1 先定义图的语义层再选渲染工具很多团队做图的第一步是打开工具第二步是拖方块第三步是连线。diagram-design 的思路完全反过来先定义这张图要表达什么语义再决定用什么工具渲染。这听起来像废话但实际操作中90% 的混乱都来自语义没定义清楚就开始画。举个具体例子。你要画一个“订单系统”的架构图。如果直接开画你会纠结订单服务是一个方块还是三个方块数据库要不要画在里面缓存算不算一个独立节点消息队列放在哪一层这些问题本质上不是画图问题而是系统边界和抽象层级的问题。diagram-design 的做法是先用一个简单的文本清单定义清楚图的类型部署架构图 / 业务流程图 / 数据流图 / 状态机图抽象层级系统级 / 服务级 / 模块级 / 类级关注点数据流向 / 调用关系 / 部署拓扑 / 状态变迁受众研发团队 / 运维团队 / 业务方 / 外部合作方这四行定义清楚之后图的形状基本就确定了。比如“服务级 调用关系 研发团队”对应的就是标准的服务依赖图每个服务一个方块箭头表示调用方向不需要画数据库内部表结构也不需要画部署机房。语义层定义是 diagram-design 最核心的设计决策因为它把“画什么”和“怎么画”解耦了。2.2 用文本描述结构用渲染器输出视觉diagram-design 推荐的落地方式是结构用文本描述视觉用渲染器生成。文本描述的好处是天然支持版本管理、代码评审、差异对比。你改了一个服务名git diff 里清清楚楚你新增了一条调用关系PR 里一目了然。相比之下二进制图片文件的版本管理几乎等于没有管理。文本描述的具体形式可以是多种多样的。常见的有DSL 类类似 PlantUML、Mermaid、Graphviz DOT 的领域特定语言结构化数据类YAML 或 JSON 描述节点和边再用脚本渲染代码注解类在代码里用注解标记依赖关系自动生成图diagram-design 并不绑定某一种具体格式而是强调结构描述与视觉渲染分离这个原则。你可以用 Mermaid 写流程图用 Graphviz 画依赖图用自定义 YAML 描述部署拓扑只要保证结构描述是纯文本、可 diff、可评审的就符合这个项目的设计哲学。提示不要试图用一种 DSL 画所有类型的图。流程图、时序图、状态机图、部署图各有最适合的表达方式强行统一只会让描述变得臃肿难读。2.3 分层维护全局图、领域图、细节图diagram-design 另一个关键设计是分层维护。很多团队的问题不是没有图而是只有一张“大而全”的图上面密密麻麻几百个节点谁看谁晕。正确的做法是分三层层级受众内容更新频率全局图所有人系统边界、核心服务、外部依赖季度级领域图领域研发领域内服务、数据流、关键接口月度级细节图模块负责人类关系、状态机、时序细节随代码更新全局图只画到服务级别不展开内部模块领域图展开到关键组件细节图才画到类和接口。这样每张图的信息密度可控维护成本也分摊到了不同角色身上。分层维护的本质是让图的更新责任和系统变更责任对齐谁改了什么谁就更新对应层级的图。2.4 为什么不用纯手工拖拽工具作为主力手工拖拽工具不是不能用而是不适合作为主力维护手段。原因有三点。第一手工图无法 diff改了什么全靠记忆和肉眼对比。第二手工图无法自动校验节点之间的引用关系错了也没人发现。第三手工图无法批量生成十个服务要画十张类似的图只能重复劳动。diagram-design 的立场是手工工具可以用来做一次性演示图或高度定制化的视觉稿但系统性的、需要长期维护的图必须走文本描述加渲染的路线。这个取舍背后是对“图的生命周期”的清醒认识——图不是画完就结束而是要和系统一起生长。3. 核心细节解析节点、边、布局、样式四要素3.1 节点定义粒度决定图的可读性节点是图的基本单元。diagram-design 对节点的核心要求是粒度一致。什么意思同一张图里不能有的节点代表一个服务有的节点代表一个函数。粒度不一致的图读者无法建立统一的认知模型。定义节点时我习惯问三个问题这个节点在系统里是一个独立部署单元吗这个节点有独立的生命周期吗这个节点是受众关心的一级概念吗如果三个问题都是“是”那它就应该是一个节点。如果只有部分为“是”那它可能应该被合并到父节点里或者拆成子图单独表达。节点的命名也有讲究。diagram-design 建议使用领域术语加角色后缀的命名方式比如order-service、payment-gateway、user-db。避免使用service1、moduleA这种无意义命名也避免使用订单服务模块这种中英混杂且带冗余后缀的命名。命名的一致性直接决定了图的可搜索性和可讨论性。3.2 边定义方向、类型、标签边是节点之间的关系。diagram-design 强调边必须携带方向、类型、标签三个信息。方向表示依赖或数据流向类型表示是同步调用、异步消息、数据读取还是控制流标签补充说明具体接口或协议。很多图的问题出在边上。比如画了一条从 A 到 B 的箭头但没说是 A 调用 B 还是 B 调用 A也没说是 HTTP 还是消息队列。这种图在评审时必然引发歧义。diagram-design 的做法是给边定义一套最小标签集同步调用A -- B : HTTP /api/order异步消息A -.- B : MQ order.created数据读取A -- B : SQL read控制流A -- B : trigger这套标签集不需要很复杂但必须团队统一。统一之后任何人看到图都能准确理解关系语义不需要额外解释。3.3 布局策略让图自己讲故事布局是图的视觉呈现。diagram-design 不建议过度依赖自动布局因为自动布局往往把图排得“均匀但无重点”。好的布局应该让读者一眼看到核心路径。常见的布局策略有从左到右适合数据流和调用链入口在左出口在右从上到下适合层级结构和部署拓扑上层依赖下层中心辐射适合以某个核心服务为中心的依赖图分组泳道适合跨角色的业务流程每个角色一条泳道选择布局的依据是图的叙事逻辑。你想让读者先看什么后看什么布局就要引导这个顺序。比如画订单创建流程核心路径是“用户下单 - 订单服务 - 库存服务 - 支付服务”那这条路径就应该放在图的中央水平线上其他分支服务放在上下两侧。3.4 样式规范颜色、形状、线型的一致性样式不是装饰是语义的视觉编码。diagram-design 建议团队定义一套最小样式规范视觉元素语义示例蓝色方块内部服务order-service绿色方块外部依赖payment-gateway灰色方块数据存储order-db实线箭头同步调用HTTP虚线箭头异步消息MQ红色边框待废弃legacy-service这套规范一旦确定所有图都遵循。好处是读者不需要每次重新学习图的视觉语言看一眼颜色和线型就能快速定位关键信息。样式规范不需要很复杂五到八条足够覆盖大部分场景。注意样式规范要写进团队文档并且在图评审时作为检查项。否则新人加入后很容易引入不一致的样式慢慢就退化了。4. 实操过程从零搭建一套可维护的图系统4.1 第一步盘点现有图资产分类打标动手之前先盘点。把团队现有的所有图收集起来按类型、层级、受众、更新频率四个维度打标。这一步的目的是搞清楚哪些图值得保留哪些图应该废弃哪些图需要重构。我自己的经验是一个中等规模团队通常有几十到上百张图其中真正还在维护的不超过三分之一。大量图是“一次性产物”画完就再也没更新过。盘点之后把图分成三类活跃图还在指导实际工作的纳入统一管理归档图历史项目留下的标记归档不再更新废弃图已经完全不准确的直接删除或标记废弃这一步能砍掉大量维护负担让后续工作聚焦在真正重要的图上。4.2 第二步定义团队的图规范文档规范文档不需要很长但必须包含以下内容图的类型清单团队允许哪些类型的图每种图的用途和受众节点命名规范命名格式、大小写、分隔符边标签规范关系类型、标签格式样式规范颜色、形状、线型的语义映射分层维护规则全局图、领域图、细节图的更新责任和频率评审流程新图如何评审变更如何通知这份文档是 diagram-design 落地的核心。没有规范工具再好也会用乱。规范文档建议放在团队知识库里并且在新人入职时作为必读材料。4.3 第三步选择文本描述格式和渲染工具根据团队的技术栈和图的类型选择合适的文本描述格式。下面是一个简单的选型对照图类型推荐格式渲染工具适用场景流程图Mermaid内置渲染业务流程、审批流时序图Mermaid / PlantUML内置渲染接口调用、交互流程状态机图Mermaid / PlantUML内置渲染订单状态、工单状态依赖图Graphviz DOTGraphviz服务依赖、模块依赖部署图YAML 自定义脚本自定义渲染部署拓扑、机房分布架构图Structurizr DSLStructurizrC4 模型架构选型的原则是优先使用团队已有工具链支持的格式。如果团队已经在用 Markdown 写文档Mermaid 是最自然的选择因为大多数 Markdown 渲染器都支持。如果团队有专门的架构管理需求Structurizr 这类 C4 模型工具更合适。4.4 第四步建立图与代码的关联机制图要跟着代码走就必须建立关联机制。diagram-design 推荐两种方式方式一图文件与代码同仓库。把图的文本描述文件放在代码仓库的docs/diagrams目录下和代码一起提交、一起评审。代码变更时如果影响了架构评审人可以直接在 PR 里要求更新图。方式二自动生成加人工校验。对于依赖关系图可以从代码的 import 或注解中自动提取依赖生成初版图再由人工校验和补充。这种方式适合服务数量多、手工维护成本高的场景。两种方式可以结合使用。核心图手工维护辅助图自动生成。关键是图不能脱离代码独立存在否则必然过期。4.5 第五步把图评审纳入研发流程图评审不是额外负担而是设计评审的一部分。在技术方案评审时要求方案里必须包含对应的图在代码评审时如果变更影响了系统结构要求同步更新图。这样图的更新就变成了研发流程的自然环节而不是额外的“文档工作”。我自己的做法是在 PR 模板里加一条检查项“本次变更是否影响系统结构如果是是否更新了对应层级的图”这条检查项看起来简单但能显著提高图的更新率。4.6 第六步定期巡检和清理图系统也需要定期维护。建议每季度做一次图巡检检查以下内容是否有图引用了已下线的服务是否有图超过三个月未更新但系统已变更是否有图违反了样式规范是否有图的信息密度过高需要拆分巡检的结果形成清理任务分配给对应的负责人。图系统的健康度取决于清理频率不清理的图系统会在半年内退化成一堆无人信任的图片。5. 常见问题与排查技巧实录5.1 图太多不知道从哪开始整理这是最常见的问题。我的建议是从最痛的那张图开始。哪张图每次评审都被吐槽哪张图每次新人来了都看不懂哪张图每次系统变更后都要花半天重画从这张图开始用 diagram-design 的方法重构它。一张图跑通之后再推广到其他图。不要试图一次性整理所有图那会让人崩溃。一张一张来每张图都是一次方法论的实践。5.2 文本描述写起来太麻烦不如拖拽快这个感受在初期非常真实。手工拖拽五分钟能画完的图写文本描述可能要十五分钟。但区别在于手工图改一次要重新拖五分钟文本图改一次只要改一行字。图的寿命越长文本描述的优势越明显。我的经验是一次性演示图用手工工具长期维护图用文本描述。判断标准很简单这张图三个月后还会有人看吗会就用文本描述。5.3 自动布局出来的图太丑没法看自动布局确实经常不尽如人意。diagram-design 的建议是自动布局加人工微调。大多数文本渲染工具都支持布局提示比如指定节点方向、分组、层级。花十分钟调整布局提示能让图的可读性提升一个档次。如果自动布局实在无法满足可以考虑用文本描述生成结构再导入可视化工具做最终排版。但这样会失去纯文本 diff 的优势需要权衡。5.4 团队非技术同学不愿意写文本描述这是推广时的最大阻力。解决办法不是强迫非技术同学写 DSL而是提供模板和辅助工具。比如为常见的业务流程图提供填空式模板非技术同学只需要填节点名和关系不需要学语法。或者提供一个简单的表单界面填写后自动生成文本描述。diagram-design 的核心是结构描述与视觉分离不是必须手写 DSL。只要结构描述是可版本管理的文本用什么方式生成的不重要。5.5 图更新了但没人知道图更新后需要通知机制。常见做法有在团队群里发变更摘要在图的文件头部维护变更日志把图嵌入到相关的技术文档里文档更新时自然带动图更新在 CI 里加检查图变更时自动通知相关人关键是让图的变更可见。不可见的变更等于没变更。5.6 常见问题速查表问题可能原因解决方向图无人更新更新责任不明确把图更新纳入 PR 检查项图风格不一致缺少样式规范定义最小样式规范并评审图信息密度过高抽象层级混乱分层维护拆分为全局图和细节图图无法 diff使用二进制格式改用文本描述格式新人看不懂图缺少图例和说明每张图附带图例和上下文说明图与代码不一致缺少关联机制图文件与代码同仓库同步评审5.7 我踩过的几个坑第一个坑是过度设计规范。一开始我定义了二十多条样式规范结果没人记得住反而导致执行率下降。后来砍到六条执行率反而上去了。规范要少而精能覆盖 80% 场景就够了。第二个坑是试图用一张图表达所有信息。我曾经画过一张包含所有服务、所有数据库、所有消息队列的“全景图”结果这张图成了“谁看谁晕”的典型。后来拆成三层每层只表达该层受众关心的信息可读性立刻提升。第三个坑是忽略图的上下文。一张图单独存在时读者不知道它的背景、范围、更新时间。后来我在每张图的开头加了简单的元信息图的类型、受众、最后更新时间、相关文档链接。这个小改动让图的可信度大幅提升。第四个坑是没有定期清理。图系统运行半年后积累了大量过期图新人分不清哪些是当前的、哪些是历史的。后来建立了季度巡检机制过期图及时归档或删除图系统的信噪比才保持住。6. 工具选型与团队适配的几点经验6.1 小团队从 Mermaid 加 Markdown 开始五到十人的小团队不需要复杂的工具链。Mermaid 加 Markdown 足够覆盖大部分场景。图文件放在代码仓库的docs目录下和代码一起评审。渲染直接用支持 Mermaid 的 Markdown 编辑器或文档平台。成本低上手快维护简单。6.2 中等团队引入分层维护和样式规范二十到五十人的团队图的数量和类型都会增加需要引入分层维护和样式规范。这时候可以考虑用 Structurizr 或类似的架构管理工具把全局图、领域图、细节图分开管理。样式规范要写进文档并且在图评审时检查。6.3 大型团队自动化生成加人工校验超过五十人的团队手工维护所有图不现实。这时候需要自动化生成加人工校验。依赖关系图、部署拓扑图可以从代码和配置中自动提取人工只负责校验和补充关键信息。核心架构图仍然手工维护但数量控制在可管理范围内。6.4 工具选型的核心判断标准不管团队大小工具选型的核心判断标准只有三条结构描述是否可版本管理必须是纯文本能 diff能评审渲染是否可自动化能集成到 CI 或文档平台不需要手动导出图片学习成本是否可接受团队成员能在半天内学会基本用法三条都满足就是合适的工具。缺一条长期维护都会出问题。7. 图系统的长期维护心得图系统和代码系统一样需要持续投入才能保持健康。我的经验是图的维护成本应该控制在研发时间的 5% 以内。超过这个比例说明图系统设计得太重需要简化低于这个比例说明图系统可能已经荒废需要检查。具体做法上我习惯把图维护拆成三类任务日常更新随代码变更同步更新纳入 PR 流程成本最低月度巡检检查图的准确性和一致性发现过期图及时处理季度重构对信息密度过高或结构混乱的图进行重构提升可读性这三类任务的时间分配大概是 70%、20%、10%。日常更新是主力巡检和重构是保障。只要日常更新做到位巡检和重构的压力就会小很多。另外图系统的价值最终体现在沟通效率上。如果一张图能让评审会议缩短十分钟一年下来节省的时间就非常可观。反过来如果一张图每次都要花时间解释那它就是在消耗而不是创造价值。定期问自己这张图还在帮我们省时间吗如果答案是否定的就该考虑重构或废弃了。最后分享一个我一直在用的小技巧每张图的开头加一行注释写明“最后更新人”和“最后更新原因”。比如// updated by A, reason: order-service split into order and payment。这行注释看起来不起眼但当你三个月后回头看这张图时能立刻知道它为什么变成现在这样。图的历史和代码的历史一样重要只是大多数人忽略了。