企业官网建设流程全解析

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

第一次听到 diagram-design 这个词，很多人会以为它只是一个画图工具的别名，或者某个设计模板库的代号。但真正在项目里被“图”折磨过的人会明白，它指向的是一套更底层的东西：把脑子里那些模糊的、线性的、说不清楚的逻辑关系，转化成一张别人三秒钟就能看懂的图。这件事听起来简单，做起来要命。

我做过一个内部工具的重构项目，需求评审会上产品经理讲了四十分钟，白板上画了七八个框和箭头，散会之后每个人对流程的理解都不一样。后端觉得是三个服务，前端觉得是两个页面，测试觉得有五个状态。后来我花了一个下午，用 diagram-design 的思路把整个数据流和状态机画成两张图，再拉大家过了一遍，之前吵了四十分钟没结论的问题，二十分钟就对齐了。从那以后我就认定，图不是装饰品，图是沟通的基础设施。

diagram-design 的核心价值在于三个层面。第一层是结构可视化，把系统里的实体、关系、流向用统一的视觉语言表达出来，消除歧义。第二层是设计决策记录，每一张图背后都对应着一组取舍，比如为什么用消息队列而不是直接调用，为什么状态要拆成两个而不是一个，这些决策如果只留在聊天记录里，三个月后没人记得。第三层是协作锚点，当团队里有人问“这个逻辑到底怎么走的”，你不用再翻代码或者翻文档，直接甩一张图过去，对方看完就懂。

这套方法适合谁？我总结下来有三类人最需要。第一类是后端和全栈开发者，你们天天跟服务、数据库、缓存、队列打交道，不画图根本说不清楚调用链。第二类是产品经理和项目负责人，你们需要把业务逻辑翻译成技术团队能理解的结构，图是最短的路径。第三类是技术写作者和布道者，你们要把复杂系统讲给外部人听，没有图就像讲相声没有捧哏，干巴巴的。

但我要提前说清楚，diagram-design 不是让你去学某个特定软件的按钮在哪里。工具会过时，语法会变，但“怎么把一团乱麻理成一张清晰的图”这个能力不会过时。下面我会从设计思路、核心细节、实操流程、常见坑四个维度，把这套方法拆开讲透。你不需要任何绘图基础，只要你会用键盘打字，就能跟着做下来。

2. 内容整体设计与思路拆解：为什么是这套结构

2.1 从“画什么”到“为什么画”：需求分层模型

很多人画图的第一步就错了——打开工具就开始拖框。这就像写代码不设计接口直接写实现，最后一定返工。diagram-design 的第一个原则是：先定图层，再定元素。我习惯把一张图的需求分成三层来问。

第一层是受众层。这张图给谁看？给老板看，重点在业务价值和数据流向，技术细节全部隐藏；给开发看，重点在接口边界和数据结构，业务背景一笔带过；给运维看，重点在部署拓扑和故障域，代码逻辑完全不出现。同一套系统，给不同人看的图应该长得完全不一样。我见过有人拿一张给开发看的详细时序图去给老板汇报，老板看了三分钟就问“所以这跟我有什么关系”，场面非常尴尬。

第二层是决策层。这张图要支撑什么决策？如果是技术选型评审，图里必须体现候选方案之间的差异，比如方案 A 是同步调用、方案 B 是异步消息，图要能让人一眼看出延迟和耦合度的区别。如果是故障复盘，图里必须标出故障发生的位置和影响范围，其他无关服务可以简化成一个小方块。图的详略程度，取决于它要回答什么问题。

第三层是演进层。这张图是临时讨论用还是长期维护？临时图用白板或者在线协作工具，五分钟画完，讨论完就扔。长期图必须纳入版本管理，跟代码一起提交，每次架构变更都要更新。我自己的习惯是：临时图用最粗糙的线条，长期图用统一的视觉规范，包括颜色、字体、箭头样式、命名规则，全部固定下来。

这三层问完，你才知道这张图应该长什么样。跳过这一步直接画，大概率是画了一张谁都不满意的图，然后反复修改，浪费时间。

2.2 视觉语法的统一：颜色、形状、线条的约定

diagram-design 的第二个核心是视觉语法的一致性。什么叫一致性？就是同一张图里，蓝色永远代表数据库，圆角矩形永远代表服务，虚线箭头永远代表异步消息。读者不需要看图例就能猜出大概含义，阅读成本降到最低。

我给自己定了一套简单的规则，你可以直接抄。颜色方面：蓝色系用于数据存储（数据库、缓存、对象存储），绿色系用于计算单元（服务、函数、任务），橙色系用于消息中间件（队列、事件总线），灰色用于外部依赖（第三方接口、遗留系统），红色只用于故障点和告警。形状方面：矩形用于服务，圆柱用于数据库，菱形用于判断分支，圆角矩形用于外部系统，虚线框用于逻辑分组。线条方面：实线箭头用于同步调用，虚线箭头用于异步消息，粗线用于主流程，细线用于辅助流程，带数字的线条用于标注顺序。

这套规则不需要多复杂，关键是坚持用。我见过一个团队，每个人画图都有自己的颜色习惯，结果评审会上光解释“这个紫色是什么意思”就花了十分钟。统一语法之后，新来的同事看第一张图就能跟上节奏。

还有一个细节：命名规范。图里的每个节点名称必须跟代码里的服务名或者数据库表名对应，不能一个叫“用户服务”，一个叫“UserService”，一个叫“用户中心”。我吃过这个亏，画图的时候随手写了“订单处理”，结果开发找了半天不知道对应哪个模块。后来我强制自己：图里的名字必须能从代码仓库里搜到，搜不到就说明命名有问题。

2.3 工具选型的取舍：文本驱动还是画布驱动

工具选择上，diagram-design 的实践者分成两派。一派是画布驱动，用拖拽式工具，所见即所得，适合快速出图。另一派是文本驱动，用代码描述图，版本可控，适合长期维护。我的建议是：临时讨论用画布，长期资产用文本。

文本驱动的代表是各种基于 DSL 的绘图工具，你写一段类似代码的描述，工具渲染成图。好处非常明显：可以跟代码一起提交到 Git，每次变更都有记录，可以 diff，可以 review。坏处是学习成本高，画一张简单的图可能要写几十行描述。画布驱动则相反，上手快，但版本管理困难，改一版存一个文件，最后文件夹里全是“架构图-v3-final-真的最终版”。

我自己的做法是混合使用。架构决策记录用文本驱动，因为需要长期追溯；评审会上的草图用画布驱动，因为要快速迭代；对外分享的图用画布驱动精修，因为要好看。关键是不要纠结工具，先想清楚这张图的寿命有多长。

提示：不管你选哪种工具，导出格式尽量选 SVG 而不是 PNG。SVG 是矢量图，放大不糊，而且可以用文本编辑器打开，方便做细微调整。PNG 只适合发聊天窗口。

3. 核心细节解析与实操要点：把逻辑翻译成图形

3.1 实体识别：从需求描述里提取名词和动词

画图的第一步不是画，是读。给你一段需求描述或者一段代码，你要能从中提取出实体和关系。我用的方法叫“名词动词法”：名词是节点，动词是连线。

举个例子，需求里写“用户下单后，系统扣减库存，然后通知物流”。名词有：用户、订单、库存、物流。动词有：下单、扣减、通知。那么图里至少有四个节点，三条连线。但这还不够，因为“系统”这个词太模糊了，到底是哪个服务在扣减库存？是订单服务直接调库存服务，还是通过消息队列异步处理？这些细节决定了图的准确性。

我的实操步骤是这样的。第一步，把需求里所有名词圈出来，去掉重复的和无关的，剩下的就是候选节点。第二步，把动词圈出来，确定每个动词的发起方和接收方，这就是连线。第三步，问自己三个问题：这个调用是同步还是异步？这个数据是推还是拉？这个失败会不会影响主流程？这三个问题的答案，决定了线条的样式和标注。

还有一个容易忽略的点：边界。图里必须明确标出哪些是系统内部，哪些是外部依赖。我习惯用虚线框把内部服务圈起来，外部系统放在框外。这样读者一眼就能看出系统的职责范围，不会把第三方的问题算到自己头上。

3.2 关系建模：一对一、一对多、多对多的视觉表达

实体之间的关系比实体本身更重要。diagram-design 里，关系建模的核心是基数表达。一对一、一对多、多对多，这三种关系在图上必须一眼能区分。

一对一用单线连接，两端都不加标记。一对多用“鸦爪”符号，多的一端画三个分叉。多对多用中间加一个关联节点的方式表达，比如用户和角色是多对多，中间加一个“用户角色关联”节点，两边都是一对多。这个规则来自数据库建模的 ER 图传统，但我在服务架构图里也沿用，因为开发人员一看就懂。

但服务架构图里还有更复杂的关系，比如依赖方向和数据流向。依赖方向用箭头表示，A 依赖 B 就画 A 到 B 的箭头。数据流向用带标签的箭头表示，标签写清楚传的是什么数据，比如“用户ID”、“订单详情”、“库存变更事件”。我见过很多图只画箭头不写标签，读者只能猜，猜错了就是事故。

还有一个高级技巧：用颜色区分关系类型。同步调用用蓝色箭头，异步消息用橙色虚线，数据复制用绿色双向箭头。这样一张图里即使有几十条连线，读者也能快速分类。我做过一个微服务架构图，服务之间有同步调用、异步事件、数据库共享三种关系，用颜色区分之后，评审会上没有人再问“这条线是什么意思”。

3.3 布局原则：从左到右、从上到下、从外到内

图的布局决定了读者的阅读顺序。diagram-design 的布局原则很简单：主流程从左到右，分支从上到下，外部依赖从外到内。

从左到右是最符合人类阅读习惯的。用户请求从左边进入，经过一系列处理，结果从右边输出。如果流程有回环，比如重试或者补偿，用向上的弧线画回去，不要画成左右来回的锯齿，那样看起来像心电图。

从上到下用于表达层级关系。比如一个服务内部有多个模块，模块下面有多个类，这种包含关系用垂直布局。上层是抽象，下层是具体，读者从上往下看，理解成本最低。

从外到内用于表达边界。外部系统放在最外层，网关或者负载均衡放在中间层，核心业务服务放在最内层。这种同心圆或者分层布局，能直观地表达“哪些是我们要负责的，哪些是别人负责的”。

布局还有一个大忌：线条交叉。两条线交叉会让读者困惑，到底有没有连接关系？如果实在避不开，用“跳线”符号，就是一条线跨过另一条线时画一个小弧。但最好的办法是调整节点位置，让线条不交叉。我画图的时间有一半花在调整布局上，因为布局清晰比内容详细更重要。

注意：不要为了省空间把节点挤在一起。图的可读性跟留白成正比，节点之间至少留一个节点宽度的间距。导出的时候如果发现字太小，宁可分成两张图，也不要硬塞。

4. 实操过程与核心环节实现：从零画出一张能用的架构图

4.1 准备阶段：明确目标、收集素材、确定范围

动手之前，先做三件事。第一，写一句话描述这张图的目标。比如“这张图要说明订单创建流程中，订单服务、库存服务、支付服务之间的调用关系”。这句话就是图的主题，所有内容围绕它展开，无关的节点全部砍掉。第二，收集素材。把相关的代码仓库、接口文档、数据库表结构、之前的会议记录都翻出来，确保图里的每个节点和连线都有依据，不是拍脑袋想的。第三，确定范围。明确哪些在范围内，哪些不在。比如“本次只画同步调用，异步消息另外画一张”，这样图不会无限膨胀。

我自己的习惯是先在纸上画一个草图，用铅笔，五分钟。草图只画节点和连线，不纠结样式。画完之后问自己：这张图能回答目标里那个问题吗？如果能，进入下一步；如果不能，调整节点或者补充连线。这一步花五分钟，能省后面半小时的返工。

4.2 绘制阶段：节点、连线、标注的逐步实现

绘制阶段我分成四步走。第一步，放节点。按照从左到右或者从上到下的顺序，把主要节点摆好。先放核心服务，再放数据库和中间件，最后放外部依赖。节点大小尽量一致，除非某个节点特别重要，可以稍微放大。第二步，连主线。把主流程的连线画出来，用实线箭头，标注调用顺序。主线通常只有一条，从入口到出口，中间经过哪些服务。第三步，加分支。把异常流程、补偿流程、异步流程用虚线或者不同颜色画出来。分支不要太多，超过三条就考虑拆图。第四步，补标注。给每个节点加名称，给每条连线加标签，给关键决策点加注释。注释用简短的文字，不要写长句。

这里有一个实操细节：先画粗后画细。先用最粗的线条把大框架搭出来，确认布局合理之后再细化样式。我见过有人一上来就调颜色、调字体、调箭头样式，结果画到一半发现布局不对，全部重来。正确的顺序是：布局 > 连线 > 标注 > 样式。样式是最后一步，而且应该用统一的模板，不要每张图都重新调。

还有一个技巧：用图层。大部分绘图工具都支持图层，把节点放在一个图层，连线放在一个图层，标注放在一个图层。这样调整的时候可以单独操作，不会误触。比如你想把所有连线改成虚线，只需要选中连线图层，一键修改，不用一个个点。

4.3 校验阶段：自检清单与同行评审

图画完不是结束，是校验的开始。我给自己定了一个自检清单，每次画完都过一遍。

自检之后，找至少一个同事做同行评审。评审的时候不要问“你觉得好看吗”，要问“你能看懂这个流程吗？有没有哪里不清楚？”让对方用自己的话复述一遍图的内容，如果复述错了，说明图有问题。我经历过一次评审，我以为画得很清楚，结果同事看完问“这个服务是同步调用还是异步的”，我才发现忘了标箭头样式。这种问题自己看不出来，必须让别人看。

4.4 维护阶段：版本管理、变更记录、废弃处理

长期维护的图必须纳入版本管理。我的做法是：图跟代码放在同一个仓库，目录结构按模块划分，每次架构变更提交代码的同时更新图。提交信息里写清楚改了什么，比如“订单服务拆分为订单服务和订单查询服务，更新架构图”。这样回溯的时候，能直接看到图和代码的对应关系。

变更记录也很重要。我在图的底部加一个小的版本表格，记录每次修改的日期、修改人、修改内容。不要写“优化布局”这种模糊的描述，要写“增加支付服务到订单服务的异步回调连线”。这样三个月后有人问“这条线什么时候加的”，你能直接回答。

废弃的图不要直接删，移到archive目录，加一个deprecated前缀。因为有时候需要回溯历史决策，比如“当初为什么用消息队列而不是直接调用”，翻出旧图一看就明白了。直接删掉的话，这些信息就永远丢失了。

5. 常见问题与排查技巧实录：踩过的坑和填坑方法

5.1 图太复杂看不懂怎么办：分层拆解与渐进披露

这是最常见的问题。一张图里塞了三十个节点、五十条连线，读者看一眼就放弃了。我的解决方法是分层拆解。把一张大图拆成三张：第一张是上下文图，只画系统跟外部的关系，五到七个节点，让读者知道系统在什么位置；第二张是容器图，画系统内部的主要服务和技术选型，十到十五个节点，让读者知道有哪些模块；第三张是组件图，画某个服务内部的模块和类，按需展开。

这三层图对应不同的受众和场景。给老板看上下文图，给新同事看容器图，给开发看组件图。每张图只回答一个问题，不要试图用一张图回答所有问题。我见过有人把三层信息塞进一张图，结果谁都不满意。拆开之后，每张图都清晰了，维护成本也降低了。

还有一个技巧叫渐进披露。在交互式文档里，可以做成可折叠的图，默认只显示主要节点，点击某个节点展开细节。如果是静态图，就用编号标注，图里只画主要节点，细节用文字列表放在图下面。比如图里画了“订单服务”，下面用文字写“订单服务包含：订单创建、订单查询、订单取消三个模块”。这样图保持简洁，细节也不丢失。

5.2 改了代码忘了改图怎么办：自动化与流程约束

图和代码不同步是常态。我试过靠自觉，结果三个月后图就跟代码完全对不上了。后来我用了两个办法。第一，自动化检查。如果图是文本驱动的，可以写一个脚本，从代码里提取服务名和接口名，跟图里的节点做对比，不一致就报错。这个脚本可以集成到 CI 里，每次提交都跑一遍。第二，流程约束。在代码评审的清单里加一条：“如果本次变更涉及服务边界或者调用关系，必须更新架构图”。评审人不看代码只看图，图没更新就打回。

但说实话，自动化只能检查名称是否一致，检查不了逻辑是否正确。所以定期人工审查还是必要的。我自己的节奏是每个季度花半天时间，把核心图跟代码过一遍，该更新的更新，该废弃的废弃。这个时间投入是值得的，因为一张过时的图比没有图更危险，它会误导人。

还有一个经验：图不要画太细。如果你发现每次改代码都要改图，说明图画得太细了。架构图应该只画服务边界和主要调用关系，服务内部的实现细节不要画。内部细节用代码和接口文档表达，图只负责宏观结构。这样变更频率会低很多。

5.3 团队审美不统一怎么办：模板化与规范落地

团队里每个人画图风格不一样，评审会上光解释图例就花十分钟。解决方法是模板化。我做一个模板文件，里面预定义了颜色、字体、形状、线条样式，所有人基于模板画图。模板里还包含常用的图例，比如数据库、缓存、队列、外部系统，直接拖出来用，不用自己画。

规范落地需要一点强制力。我的做法是：第一次评审用模板的图直接过，不用模板的图打回重画。听起来有点霸道，但效果很好。两次之后所有人都用模板了，因为不用模板反而更麻烦。模板还要定期更新，比如团队引入了新的中间件，就在模板里加一个新的形状和颜色，大家统一使用。

还有一个细节：命名规范也要模板化。模板里预置常用的服务名和数据库名，画图的时候直接选，不要手打。手打容易打错，而且不同人打出来的可能不一样。比如“用户服务”和“用户中心”和“UserService”，三个名字指同一个东西，读者会困惑。统一用代码里的名字，从模板里选，就不会错。

提示：模板不要做得太复杂。我见过一个模板有二十种颜色、十五种形状，结果没人记得住。模板越简单越好，五到七种颜色，三到四种形状，足够表达大部分场景。

5.4 评审会上被挑战怎么办：用图说话而不是用嘴

评审会上被挑战是好事，说明有人认真看了。但怎么回应挑战，决定了评审的效率。我的原则是：用图说话，不要用嘴。如果有人说“这个流程不对”，不要急着解释，先问“你觉得哪里不对”，然后让对方在图上指出来。如果对方指出的位置确实有问题，当场改图，改完再确认。如果对方指的位置没问题，是理解偏差，就对着图再讲一遍。

我经历过一次评审，有人质疑“为什么订单服务要调库存服务，而不是库存服务监听订单事件”。这个问题用嘴说很复杂，但我在图上加了一条虚线箭头，标注“异步事件”，然后说“这是异步的，不是同步调用”，对方立刻就明白了。图能把复杂的关系可视化，比语言高效得多。

还有一个技巧：准备一张“备选方案图”。如果评审会上有人提出不同的方案，你可以直接切到备选图，对比两个方案的差异。这样讨论有依据，不会变成空对空的争论。我通常会在评审前准备两到三张图，主方案一张，备选方案一到两张，根据现场情况切换。

6. 工具链与效率提升：让画图不再痛苦

6.1 文本驱动工具的选择与配置

文本驱动工具的核心是用代码描述图。你写一段类似这样的描述：

用户 -> 网关: HTTPS 请求 网关 -> 订单服务: 创建订单 订单服务 -> 库存服务: 扣减库存 订单服务 -> 支付服务: 发起支付 支付服务 --> 订单服务: 支付结果回调

工具渲染成图。这种方式的优势是版本可控、易于修改、可以批量生成。我常用的配置是：用 Git 管理描述文件，用 CI 自动渲染成 SVG，推送到文档站点。每次提交代码，图自动更新，不需要手动操作。

配置的时候注意几点。第一，统一缩进和命名。描述文件也是代码，要有代码规范。第二，加注释。在描述文件里用注释说明每个节点的含义，方便后来人理解。第三，分文件。不要把所有图写在一个文件里，按模块拆分，每个文件一张图。第四，定期渲染。本地开发的时候可以实时预览，提交之后 CI 自动渲染，确保图跟描述一致。

6.2 画布驱动工具的高效使用技巧

画布驱动工具适合快速出图，但用不好会很慢。我的高效技巧有几个。第一，用快捷键。大部分工具都支持快捷键，比如复制、粘贴、对齐、分布，熟练之后速度翻倍。第二，用模板。前面说的模板文件，直接打开就能用，不用从零开始。第三，用对齐工具。手动拖节点很难对齐，用对齐和分布工具，一键搞定。第四，用组合。把相关的节点组合在一起，移动的时候一起动，不会散架。

还有一个技巧：先画草图再精修。不要一上来就追求完美，先用最粗糙的线条把结构画出来，确认布局合理之后再调样式。我见过有人花半小时调一个箭头的弧度，结果最后发现整个布局要改，白调了。正确的顺序是：结构 > 布局 > 样式 > 细节。

6.3 导出与分享：格式选择与嵌入方式

导出格式的选择取决于用途。SVG适合嵌入网页和文档，矢量图放大不糊，而且可以用 CSS 控制样式。PNG适合发聊天窗口和邮件，兼容性好，但放大后会糊。PDF适合打印和正式文档，排版固定。HTML适合交互式文档，可以加悬停提示和折叠展开。

嵌入方式也有讲究。如果是文档站点，用 SVG 直接嵌入，配合 CSS 做响应式。如果是聊天分享，用 PNG，但要注意分辨率，至少 2 倍图，不然在高分屏上会糊。如果是打印，用 PDF，确保线条和文字清晰。我自己的习惯是：源文件用文本格式，导出用 SVG，分享用 PNG，打印用 PDF。

还有一个细节：图里的文字要能选中。有些工具导出的 SVG 把文字转成了路径，虽然显示没问题，但无法搜索和复制。导出的时候检查一下，确保文字是可选的。这个细节在文档站点里很重要，用户可能想搜索图里的某个服务名。

7. 从图到文档：让 diagram-design 成为团队资产

7.1 图与文档的联动：嵌入、引用、更新

图不是孤立的，它应该跟文档联动。我的做法是：文档里嵌入图，图里引用文档。比如架构文档里嵌入架构图，图里的每个节点链接到对应的详细设计文档。这样读者看图的时候，想深入了解某个服务，直接点链接跳过去。反过来，详细设计文档里也嵌入相关的局部图，让读者有全局视角。

更新的时候要同步。如果改了图，文档里的引用要检查；如果改了文档，图里的链接要检查。我见过一个团队，图更新了但文档没更新，结果新人看文档以为系统还是旧架构，踩了坑。后来他们用了一个简单的检查脚本，每次提交都检查图和文档的链接是否有效，无效就报错。

还有一个技巧：用图作为文档的目录。把架构图放在文档首页，每个节点链接到对应的章节。读者先看图了解全局，再点进去看细节。这种“图-文档”结构比纯文字目录直观得多，新人上手速度明显加快。

7.2 新人上手：用图做 onboarding 材料

新人入职最怕的是“不知道从哪看起”。代码仓库几百个文件，文档几十篇，看哪篇？我的做法是：用图做 onboarding 的第一站。给新人一张上下文图，告诉他“这是我们系统在整体架构里的位置”；再给一张容器图，告诉他“这是我们系统内部的主要服务”；然后给一张核心流程的时序图，告诉他“这是最常用的下单流程”。三张图看完，新人对系统有了全局认知，再去看代码和文档，方向感强很多。

我试过让新人先看代码再看图，结果他看了三天代码还是一头雾水。后来改成先看图再看代码，半天就能说出主要服务的职责。图的作用是建立心智模型，有了模型再看细节，信息才能挂上去。没有模型，信息就是一堆散点，记不住也用不上。

7.3 对外分享：用图讲好技术故事

对外分享的时候，图是最好的辅助工具。但对外分享的图跟内部图不一样。内部图重准确，外部图重易懂。内部图可以出现内部服务名、数据库表名、中间件型号，外部图要脱敏，用通用名称代替。内部图可以画得很细，外部图要简化，只保留核心流程。

我做过一次对外分享，讲的是系统重构的经验。我没有放代码，也没有放详细的架构图，而是画了三张对比图：重构前的架构、重构中的过渡架构、重构后的目标架构。每张图只有五到七个节点，用颜色标出变化的部分。观众看完三张图，就理解了重构的必要性和路径。分享结束后有人问“你们用的什么消息队列”，我说“图里没画，因为重点不是选型，是架构演进”。对外分享的图，要服务于故事，而不是展示技术细节。

还有一个技巧：用图做开场。分享开始的时候，先放一张全局图，告诉观众“我们今天要讲的是这个图的中间部分”。这样观众有了全局视角，知道你在讲什么位置，不会迷失。我见过很多分享，讲了三十分钟观众还不知道在讲系统的哪一部分，就是因为没有全局图。

8. 我个人的实操心得与避坑清单

画了这么多年图，踩过的坑比画过的图还多。分享几条最值钱的经验。

第一条：图是给人看的，不是给机器看的。不要追求图的“完整性”，追求图的“可读性”。一张只有五个节点但人人都能看懂的图，比一张有五十个节点但没人看得懂的图有价值得多。我见过有人把数据库的每个字段都画在架构图里，结果图大得像海报，没人看。字段是给开发看的，架构图是给所有人看的，层次要分清。

第二条：先对齐再画图。评审会上最怕的是“你画的跟我理解的不一样”。所以在画图之前，先用文字把关键流程写下来，跟相关人对一遍，确认理解一致之后再画。我试过直接画图，画完发现理解错了，全部重来。后来改成先写文字再画图，返工率降低了一半。

第三条：图要跟着代码走。不要单独维护图，把图跟代码放在一起，用同一个版本管理。每次改代码的时候顺手改图，不要攒着。攒着的结果就是图永远过时，最后没人看。我自己的习惯是：代码提交之前，检查一下有没有涉及架构变更，有就更新图，没有就跳过。这个习惯坚持了两年，图一直跟代码同步。

第四条：不要追求完美。图是工具，不是艺术品。能用就行，不要花太多时间调样式。我见过有人花一下午调颜色，结果评审会上根本没人看颜色。把时间花在逻辑上，花在跟人对齐上，比花在样式上值得多。

第五条：多画多练。画图跟写代码一样，是手艺，需要练。我刚开始画图的时候，一张图要画两个小时，现在二十分钟就能画一张能用的。秘诀就是多画，画完让别人看，看别人能不能看懂，看不懂就改。改多了就有感觉了，知道什么该画什么不该画，什么该详细什么该简化。

最后分享一个小技巧：用图做会议纪要。每次评审会或者讨论会，不要只写文字纪要，画一张图。图里标出讨论的结论、待办事项、负责人。这样下次开会的时候，直接看图就能回顾上次的内容，比翻文字纪要快得多。我试过用图做纪要，会议效率明显提升，因为大家对着图讨论，不会跑题。

这个内容后续还可以这样扩展：把图跟监控系统联动，在图的节点上显示实时指标，比如 QPS、延迟、错误率。这样图不仅是设计文档，还是运维视图。我试过一个简单的版本，用脚本从监控系统拉数据，渲染到图的节点上，效果很好。不过这是另一个话题了，有机会再展开。