diagram-design：从草图到系统，如何画出一张可评审的架构图

1. 从一张草图到一套系统：diagram-design 到底在解决什么问题

第一次看到 “diagram-design” 这个标题，很多人会以为它只是教你怎么画流程图、时序图或者架构图。但真正做过技术方案、写过设计文档、给团队做过架构评审的人都知道，画图这件事从来不是“打开工具拖几个框”那么简单。它背后是一整套信息组织、抽象分层、视觉表达和协作沟通的方法论。diagram-design 这个项目，本质上是在解决一个非常具体的痛点：如何让一张图在脱离讲解者之后，依然能准确、高效地传递设计意图。

我见过太多团队的设计图，画的时候只有作者自己能看懂，过两周连作者本人都要重新回忆半天。也见过不少项目文档里的架构图，框线交错、颜色混乱、箭头方向随意，读者需要反复对照文字才能勉强理解。这些问题的根源不在于工具不好用，而在于画图之前没有想清楚“这张图要回答什么问题”。diagram-design 的核心价值，就是把这套“想清楚再画”的流程固化下来，形成可复用的设计规范。

这个项目适合谁？如果你是一名后端工程师，需要给团队讲清楚一次服务拆分的边界；如果你是一名产品经理，需要把复杂的业务状态流转画成一张所有人都能看懂的图；如果你是一名技术负责人，需要在评审会上用一张图说服所有人接受你的方案，那么 diagram-design 的思路和工具链都值得你花时间研究。它不要求你有美术功底，也不要求你精通某款专业绘图软件，它要求的是你对系统本身有清晰的认知，并且愿意用结构化的方式把这种认知表达出来。

从热搜词和网络讨论来看，最近关于“设计图可读性”“架构图规范”“文档配图效率”的讨论明显增多。这说明大家已经意识到，画图不是装饰，而是设计工作的一部分。diagram-design 正是在这个背景下值得被认真对待的一个项目方向。接下来我会从整体设计思路、核心细节、实操过程、常见问题几个维度，把这套方法拆开来讲清楚。

2. 整体设计思路：为什么是“先定语义，再定视觉”

2.1 图不是画出来的，是“拆”出来的

很多人画图的第一步是打开工具，然后开始拖拽图形。diagram-design 的思路完全相反：第一步是拆解信息，第二步才是选择图形。这个顺序看起来简单，但实际执行时，大部分人会不自觉地跳过第一步。我自己的经验是，如果你在画图之前没有用文字把要表达的内容列清楚，那么画出来的图大概率会返工。

具体怎么做？我通常会把一张图要回答的问题写在一张便签上，比如“这次订单系统的拆分，哪些模块独立部署，哪些模块共享数据库”。然后围绕这个问题，列出所有需要出现的信息单元：模块名称、职责边界、数据流向、同步/异步关系、外部依赖。这些信息单元就是图的“语义层”。只有语义层确定之后，才进入视觉层，决定用什么形状、什么颜色、什么连线方式来表达。

这个顺序的好处是，你不会被工具的默认样式带偏。很多人用某款工具画图，画着画着就变成了“工具能画什么我就画什么”，而不是“我需要表达什么我就画什么”。diagram-design 强调语义优先，本质上是在对抗这种工具惯性。

2.2 分层表达：一张图只讲一件事

另一个核心思路是分层。我见过不少架构图，试图在一张图里同时表达部署拓扑、数据流向、调用关系和团队归属。结果就是信息过载，读者抓不住重点。diagram-design 的做法是，把不同维度的信息拆到不同的图里，每张图只回答一个核心问题。

比如，第一张图讲“系统由哪些服务组成”，第二张图讲“一次请求在这些服务之间怎么流转”，第三张图讲“这些服务分别部署在哪些节点上”。每张图单独看都清晰，合在一起又能完整描述系统。这种分层表达的思路，和写代码时的单一职责原则非常像。一个函数只做一件事，一张图也只讲一件事。

注意：分层不是把一张图拆得越碎越好。拆分的粒度取决于读者是谁。给高层汇报的图，粒度可以粗一些；给一线开发看的图，粒度需要细到接口级别。diagram-design 建议在画图之前先明确读者对象，再决定拆几层。

2.3 视觉编码的一致性

语义层确定之后，视觉层需要一套一致的编码规则。diagram-design 在这方面有一套很实用的约定：形状代表类型，颜色代表状态，线条代表关系。比如，矩形代表服务，圆角矩形代表外部系统，菱形代表决策点；绿色代表正常状态，黄色代表警告，红色代表故障；实线代表同步调用，虚线代表异步消息。

这套规则一旦确定，团队里所有人画图都遵循同一套编码，读者就不需要每次重新学习图的含义。我自己的团队在推行这套规则之后，新成员看架构图的理解速度明显提升。以前需要半小时讲解的图，现在十分钟就能讲完，因为读者已经熟悉了视觉语言。

2.4 工具选型：为什么我最终选择了“文本驱动”

关于工具选型，diagram-design 并没有强制指定某一款软件，但它的方法论天然更适合文本驱动的绘图工具。所谓文本驱动，就是用代码或标记语言来描述图，而不是用鼠标拖拽。常见的方案包括用 PlantUML、Mermaid、Graphviz 等。这类工具的优势在于：图的内容可以版本控制，可以 diff，可以 review，可以和代码放在同一个仓库里。

我试过纯图形界面的工具，也试过文本驱动的工具，最终长期留在文本驱动这一侧。原因很简单：图形界面的图很难做代码评审。你没法在 PR 里对比两张图的差异，也没法在 git log 里看到图是怎么演变的。而文本驱动的图，本质上就是一段代码，可以享受和代码一样的协作流程。这对于需要频繁迭代的设计文档来说，价值巨大。

当然，文本驱动也有代价。它的学习曲线比拖拽工具陡一些，调整布局也不如鼠标直接。但考虑到设计图的生命周期通常很长，前期多花一点时间学习语法，后期在协作和维护上省下的时间会远远超过投入。

3. 核心细节解析：从信息拆解到图面落地的关键环节

3.1 信息拆解：把“感觉”变成“清单”

信息拆解是 diagram-design 里最容易被低估的环节。很多人觉得自己“心里清楚”，但一旦开始画图就发现漏了这个、多了那个。我的做法是强制自己用清单的方式把信息列出来。具体来说，我会问自己四个问题：

• 这张图里有哪些实体？每个实体的名称和职责是什么？
• 实体之间有哪些关系？关系的方向和类型是什么？
• 哪些信息是必须出现的？哪些信息可以放到注释或附注里？
• 读者看完这张图之后，应该能回答什么问题？

把这四个问题的答案写成文字清单，然后再开始画图。这个习惯帮我避免了很多返工。有一次我画一张数据同步的图，画到一半才发现漏了一个关键的中间队列，导致整张图的布局要重新调整。如果提前列清单，这个问题在纸面上就能发现。

3.2 布局原则：让视线自然流动

布局是图面落地的核心。diagram-design 推荐的布局原则是视线自然流动。具体来说，人的阅读习惯是从左到右、从上到下，所以图的主要信息流也应该遵循这个方向。比如，调用关系图通常把调用方放在左侧，被调用方放在右侧；数据流图通常把数据源放在上方，数据终点放在下方。

除了方向，布局还要考虑分组。相关的实体应该放在一起，用背景框或颜色区分。比如，同一个子系统内的服务放在一个浅色背景框里，外部依赖放在另一个框里。这样读者一眼就能看出系统的边界在哪里。

我自己的经验是，布局阶段不要追求一次到位。先用最粗糙的方式把实体摆上去，然后反复调整位置，直到视线流动顺畅为止。这个过程可能需要来回改五六次，但每次调整都会让图更清晰一点。

3.3 连线与标注：别让箭头成为谜语

连线是图里最容易出问题的地方。我见过太多图，箭头指向不明、线条交叉混乱、标注缺失。diagram-design 对连线的要求很明确：每一条线都必须有明确的起点、终点和含义。如果一条线代表调用关系，那么线上应该标注调用的接口或方法名；如果一条线代表数据流向，那么线上应该标注数据的类型或格式。

对于交叉线，diagram-design 的建议是尽量避免。如果实在避不开，可以用“跳线”或“桥接”的方式表示两条线不相交。另外，连线的粗细和颜色也可以用来表达不同的含义，比如粗线代表主要路径，细线代表次要路径，红色线代表异常路径。

提示：如果你的图里出现了超过三条交叉线，说明布局需要重新调整。交叉线是读者理解图的最大障碍之一，能消除就尽量消除。

3.4 颜色使用：克制比丰富更重要

颜色是双刃剑。用得好，图会非常清晰；用不好，图会变得花哨且难以理解。diagram-design 的原则是颜色数量不超过五种，并且每种颜色都要有明确的语义。比如，蓝色代表核心服务，灰色代表外部依赖，绿色代表新增模块，红色代表待废弃模块。

我见过一些图，用了十几种颜色，结果读者根本记不住每种颜色代表什么。更糟糕的是，有些颜色在打印或投影时会变得难以区分。所以，选择颜色时还要考虑实际展示场景。如果图需要在会议室投影，那么对比度要足够高；如果图需要打印成黑白文档，那么颜色不能是唯一的信息载体。

3.5 文字与图的关系：图为主，字为辅

diagram-design 强调图本身要能独立传达信息，文字只是补充。这意味着图里的标签要简洁、准确，不能依赖大段文字说明。我见过一些图，图里只有几个框，然后旁边配了上千字的说明。这种图其实没有起到图的作用，读者还是得读文字才能理解。

正确的做法是，把关键信息直接标注在图上。比如，服务的名称、接口的名称、数据的格式，都应该出现在图里。文字说明只用来解释背景、约束和例外情况。这样读者先看图就能建立整体认知，再看文字补充细节，效率会高很多。

4. 实操过程：从零开始画一张可评审的架构图

4.1 第一步：明确图的读者和目的

在动手之前，我会先写一句话描述这张图的读者和目的。比如：“这张图给后端团队看，目的是说明订单服务拆分后的调用关系。”这句话会决定图的详细程度和表达方式。给后端团队看的图，可以出现具体的接口名和数据库表名；给产品团队看的图，则应该用业务语言描述，避免技术术语。

这一步看起来简单，但实际执行时很多人会跳过。我自己的教训是，有一次我给高层画了一张技术细节非常丰富的图，结果汇报时对方完全抓不住重点。后来我重新画了一张只有业务模块和数据流向的图，汇报效果立刻好了很多。所以，读者和目的决定了图的抽象层次，这个前提必须先确定。

4.2 第二步：列出实体和关系清单

确定读者和目的之后，我会用文字列出所有需要出现的实体和关系。实体包括服务、数据库、队列、外部系统等；关系包括调用、依赖、数据流向等。这个清单不需要很正式，用简单的列表就行。比如：

• 实体：订单服务、支付服务、库存服务、订单数据库、消息队列
• 关系：订单服务调用支付服务（同步）、订单服务发送消息到队列（异步）、库存服务消费队列消息（异步）、订单服务读写订单数据库

这个清单就是图的骨架。有了它，后面画图时就不会漏掉关键信息。

4.3 第三步：选择工具并搭建骨架

工具选择上，我目前主要用文本驱动的方案。以 PlantUML 为例，我会先用最简单的语法把实体和关系描述出来，不关心样式和布局。比如：

@startuml component "订单服务" as order component "支付服务" as payment component "库存服务" as inventory database "订单数据库" as orderDb queue "消息队列" as mq order --> payment : 同步调用 order --> orderDb : 读写 order --> mq : 发送消息 mq --> inventory : 消费消息 @enduml

这段代码渲染出来的图可能很粗糙，但骨架已经在了。接下来就是调整布局、添加颜色、优化标签。

4.4 第四步：调整布局和视觉编码

骨架搭好之后，我会根据前面说的布局原则调整位置。比如，把订单服务放在中间，支付服务和库存服务放在两侧，数据库和队列放在下方。然后应用视觉编码规则：服务用蓝色矩形，数据库用灰色圆柱，队列用黄色圆角矩形。同步调用用实线箭头，异步消息用虚线箭头。

这个阶段需要反复预览和调整。文本驱动工具的好处是，改一行代码就能重新渲染，比鼠标拖拽快很多。我通常会调整五六轮，直到视线流动顺畅、没有交叉线为止。

4.5 第五步：添加标注和注释

布局和视觉编码确定之后，我会添加必要的标注。比如，在同步调用的箭头上标注接口名，在异步消息的箭头上标注消息主题。如果某些关系有特殊约束，比如超时时间、重试策略，可以用注释的方式标在图的空白处。

标注的原则是能标在图上就不写在图外。读者看图的视线不应该频繁跳到图外的文字说明。如果图里实在放不下，可以用编号的方式，在图下方列出编号对应的说明。

4.6 第六步：评审和迭代

图画完之后，我会找至少一个同事做一次快速评审。评审的问题很简单：“你能看懂这张图在说什么吗？”如果对方需要我解释才能看懂，说明图还有问题。评审时我会特别关注几个点：读者是否能快速找到核心服务？是否能理解数据流向？是否有歧义或遗漏？

评审之后根据反馈修改，然后再次评审。通常两到三轮之后，图就基本稳定了。之后如果系统有变化，只需要修改对应的代码片段，重新渲染即可。整个过程和代码开发非常像，这也是文本驱动方案的优势所在。

5. 常见问题与排查技巧实录

5.1 图太乱怎么办：先做减法，再做加法

图太乱是最常见的问题。我的经验是，先做减法。把图里所有“可能有用”但“不是必须”的信息删掉，只保留回答核心问题所需的最小信息集。如果删完之后还是乱，说明这张图承担了太多职责，需要拆成多张图。

做完减法之后，如果确实需要补充信息，再做加法。但加法要有节制，每加一个元素都要问自己：“这个元素对回答核心问题有帮助吗？”如果没有帮助，就不加。

5.2 读者看不懂图怎么办：换位思考

读者看不懂图，通常是因为作者和读者的知识背景不一致。作者觉得理所当然的缩写、术语、关系，读者可能完全不知道。解决方法是换位思考：假设读者完全不了解这个系统，他需要哪些信息才能理解这张图？

具体做法包括：避免使用内部缩写，或者在使用时给出全称；对关键实体添加简短说明；用颜色和形状区分不同类型的信息。如果条件允许，找一位不了解这个系统的同事做一次盲测，看他能否在不听讲解的情况下理解图的主要内容。

5.3 图更新不及时怎么办：把图纳入版本控制

图更新不及时是设计文档的通病。解决方法是把图纳入版本控制，和代码放在同一个仓库里。每次代码变更时，如果涉及架构调整，就同步更新图。文本驱动的工具天然支持这种方式，因为图本身就是文本文件，可以像代码一样提交、评审、合并。

我自己的团队在推行这种做法之后，图的更新频率明显提高。因为更新图不再是一个额外的、需要打开专业软件的任务，而是代码提交的一部分。开发人员在修改代码时，顺手就把图改了。

5.4 工具选择困难怎么办：先跑通流程再优化工具

很多人花大量时间比较各种绘图工具，却迟迟没有开始画图。我的建议是先跑通流程再优化工具。随便选一个能用的工具，按照 diagram-design 的流程画完第一张图，然后再根据实际体验决定是否换工具。

工具之间的差异其实没有想象中那么大。真正决定图的质量的，是信息拆解是否清晰、布局是否合理、视觉编码是否一致。这些和工具关系不大。我见过用最简单的工具画出非常清晰的图，也见过用最专业的工具画出非常混乱的图。

5.5 常见问题速查表

5.6 几个我踩过的坑

第一个坑是过度追求美观。早期我花了很多时间调整图的配色和字体，结果图是好看了，但信息表达反而不清晰。后来我意识到，设计图的第一目标是准确传达信息，美观是第二位的。在信息准确的前提下再考虑美观，顺序不能反。

第二个坑是忽略图的维护成本。有些图我画得很详细，但后来系统变了，图没跟上，反而误导了读者。现在我画图时会刻意控制详细程度，只保留相对稳定的信息，容易变化的信息用注释或链接的方式引用，降低维护成本。

第三个坑是不写图例。有些视觉编码我自己很清楚，但读者不知道。后来我养成了写图例的习惯，把颜色、形状、线条的含义列在图的一角。这个小小的改动，让图的易读性提升了很多。

6. 工具链与协作流程的落地建议

6.1 文本驱动工具的实际使用体验

我目前主要用 PlantUML 和 Mermaid 两种方案。PlantUML 的语法更丰富，支持的图类型更多，适合画复杂的架构图和时序图。Mermaid 的语法更简洁，和 Markdown 的集成更好，适合画简单的流程图和状态图。两者都是文本驱动，都可以纳入版本控制。

实际使用中，我会根据图的类型选择工具。架构图用 PlantUML，因为需要更精细的布局控制；流程图用 Mermaid，因为写起来快，渲染也快。两者生成的图都可以导出为图片，嵌入到文档或网页里。

提示：如果你所在的团队已经在用 Markdown 写文档，Mermaid 的集成成本最低。很多 Markdown 编辑器原生支持 Mermaid 渲染，不需要额外安装插件。

6.2 团队协作中的规范制定

如果团队里有多个人需要画图，制定一套简单的规范会很有帮助。规范不需要很复杂，包括几个核心点就行：颜色含义、形状含义、线条含义、命名规则。比如，我们团队的规范是：蓝色代表核心服务，灰色代表外部依赖，绿色代表新增模块；矩形代表服务，圆柱代表数据库，圆角矩形代表队列；实线代表同步调用，虚线代表异步消息。

规范制定之后，最重要的是执行。我会在代码评审时顺便检查图是否符合规范，不符合的就提出来修改。坚持一段时间之后，大家就养成了习惯。

6.3 图与文档的配合方式

图和文档不是替代关系，而是配合关系。我的做法是，在文档的开头放一张总览图，让读者快速建立整体认知；然后在具体章节里放细节图，配合文字说明。总览图回答“系统由哪些部分组成”，细节图回答“某个流程具体怎么走”。

图和文档的另一个配合方式是图注。每张图下面用一两句话说明这张图的核心信息，帮助读者快速抓住重点。图注不需要很长，但必须准确。我见过一些图注写得很敷衍，比如“系统架构图”，这种图注等于没写。好的图注应该像“订单服务拆分后的调用关系，支付和库存通过消息队列解耦”。

6.4 从个人实践到团队习惯的过渡

个人画图容易，团队统一习惯难。我的经验是，先从自己做起，把图的质量提上去，然后在团队分享时展示效果。当其他人看到清晰的图确实能减少沟通成本时，他们自然会愿意学习。强行推行规范往往效果不好，用实际效果说话更有效。

另外，可以准备一些模板和示例，降低其他人的上手成本。比如，把常用的图类型做成模板，别人只需要修改实体名称和关系就行。模板不需要很复杂，但能大大降低初学者的心理门槛。

7. 一些个人体会和后续可以尝试的方向

我在实际使用 diagram-design 这套方法的过程中，最大的体会是：画图的时间其实大部分花在“想”上，而不是“画”上。真正打开工具画图的时间可能只占两成，剩下八成时间都在拆解信息、确定布局、调整表达。这个比例一开始让我很意外，但后来觉得非常合理。因为图的质量本质上取决于思考的质量，思考清楚了，画图就是水到渠成的事。

另一个体会是，图是设计的一部分，不是设计的附属品。以前我总觉得画图是“额外工作”，现在我觉得画图是设计过程中不可或缺的一环。很多设计问题在画图的过程中才会暴露出来，比如模块边界不清晰、数据流向有环、依赖关系过于复杂。这些问题如果在画图时发现，修改成本很低；如果等到编码时才发现，修改成本就高得多。

后续我打算尝试的方向包括：把图生成纳入持续集成流程，每次代码合并时自动检查图是否需要更新；探索用 AI 辅助生成图的初稿，然后人工调整；以及把图和其他设计文档更紧密地关联起来，形成一套完整的设计知识库。这些方向都还在探索阶段，但我觉得值得投入时间。

最后分享一个小技巧：如果你觉得画图很痛苦，不妨先从一张最简单的图开始，不要追求完美，先把信息表达清楚。画完第一张之后，你会发现第二张容易很多。画图这件事，和写代码一样，都是越练越熟的。