企业官网建设流程全解析

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

第一次听到 “diagram-design” 这个词，很多人会下意识觉得它只是“画图”的另一种说法。但真正在项目里被图表折磨过的人知道，画图从来不是难点，难的是让图表在三个月后还能被看懂、被修改、被复用。我见过太多团队，项目初期用某个在线工具拖了几张架构图，等到系统迭代了两轮，那些图要么链接失效，要么和代码完全对不上，最后只能全部重画。diagram-design 要处理的，正是这个从“随手画”到“工程化管”的断层。

它的核心定位可以概括成一句话：把图表当作代码资产来设计、版本化和交付。这里的“设计”不是美术意义上的好看，而是结构意义上的可维护。它关心的是图表的语义是否清晰、层级是否合理、命名是否统一、能否随系统演进而低成本更新。适合谁来参考？我认为有三类人最该认真看：一是需要长期维护系统架构文档的后端或平台工程师；二是要频繁向非技术角色解释复杂流程的产品和方案人员；三是任何被“图到用时方恨乱”坑过、想建立个人图表规范的人。

我自己的触发点很具体。早些年做一个跨模块的数据流转项目，前后画了十几版流程图，每版都存成不同文件名的图片，结果评审时有人问“这版和上版的差异在哪”，我翻了半天也没说清楚。那次之后我开始意识到，图表的问题不在画，而在没有设计约束。diagram-design 这个方向，本质上就是给图表加上一层设计系统，让每一张图都有统一的语法、统一的词汇表、统一的更新路径。下面我会把这套思路拆成可落地的几个层面，从整体设计到具体实操，再到踩过的坑，尽量讲透。

2. 整体设计思路：为什么图表需要一套“设计系统”

2.1 图表失控的三个典型症状

在讲方案之前，先说说图表失控通常长什么样，这样你才能判断自己是不是需要这套东西。第一个症状是命名漂移：同一个服务，在架构图里叫 “OrderService”，在流程图中叫 “订单服务”，在部署图里又变成 “order-svc”，看图的人得靠猜才能对上号。第二个症状是层级混乱：一张图里既有系统级模块，又有函数级调用，粒度不统一，读者不知道视线该停在哪一层。第三个症状是更新断裂：代码改了，图没改，而且没人知道图该由谁改、改完放哪。

这三个症状背后其实是同一个根因：图表没有被当作有生命周期的资产来管理。图片格式天生不适合 diff，在线工具的链接又依赖平台存活，于是图表就成了“一次性消费品”。diagram-design 的思路，就是把这三种症状分别对应到三套机制上：术语表统一命名、分层规则统一粒度、文本化源文件统一更新。理解了这三点，后面的所有操作都是它们的展开。

2.2 为什么选“文本化”而不是“拖拽式”

这是方案选型里最关键的一个决定。拖拽式工具上手快，但它的产物是二进制或平台私有格式，你没法用 Git 看差异，没法做代码评审，也没法批量替换。文本化图表（比如用声明式语法描述节点和连线）虽然前期学习成本高一点，但它带来的好处是决定性的：图表可以进版本库、可以走 PR 流程、可以被脚本生成。

我打个生活化的比方。拖拽式画图就像用 Word 排版，改一个字可能整页跑版；文本化画图就像用 Markdown 写作，内容归内容，样式归样式，改起来心里有底。对于需要长期维护的图表，这个差别是数量级的。当然，文本化不是万能的，纯展示性的、一次性的示意图，拖拽反而更快。所以我的建议是按生命周期选工具：活过两周的图，一律文本化；活不过两周的，随便画。

2.3 分层设计：一张图只讲一件事

diagram-design 里我最坚持的一条规则是：一张图只讲一个抽象层级的事。系统上下文图就只画系统和外部角色，不画内部模块；容器图就只画服务、数据库、消息队列，不画类和方法；组件图再往下钻一层。这条规则听起来简单，执行起来极难，因为人总想在一张图里把话说完。

为什么必须分层？因为读者的认知带宽有限。一张图里混了两个层级，读者就得不断切换思维模式，一会儿想“这个系统边界在哪”，一会儿想“这个类怎么调那个类”，最后什么都没记住。分层之后，每张图回答一个明确的问题，读者看完一张再看下一张，认知是递进的。这跟写文档先写摘要再写正文是一个道理。实操上，我会给每张图在文件头写一句“本图回答的问题”，如果这句话写不出来或者写了两个问题，就说明该拆图了。

3. 核心细节解析：术语表、分层规则与源文件组织

3.1 术语表：让每个名字只有一个写法

术语表是整套设计的地基。做法很简单：建一个 Markdown 或 YAML 文件，列出项目里所有关键实体，每个实体给出唯一的标准名、类型、一句话说明。比如OrderService类型是“服务”，说明是“负责订单创建与状态流转”。之后所有图表里的节点，都必须从这个表里取名字，不允许临时起意。

这一步的价值在于消除歧义。我踩过的坑是：早期没建术语表，结果同一个支付模块在三张图里有三种叫法，新同事入职时对着图问“这三个是不是一个东西”，我愣了半天才反应过来是。建了术语表之后，这种问题基本消失。更妙的是，术语表还能反向约束代码命名——如果图里叫OrderService，代码里的类名最好也一致，久而久之整个项目的命名都统一了。

提示：术语表不要一次写全，按需增长即可。每画一张新图，先把图里用到的实体补进术语表，再开始画。这样术语表是“用出来”的，不是“憋出来”的。

3.2 分层规则：用固定模板约束粒度

有了术语表，接下来要解决粒度问题。我的做法是准备几套固定模板，每套模板对应一个抽象层级，模板里预置好“允许出现的元素类型”。比如上下文层模板只允许“系统”和“外部角色”两种节点；容器层模板只允许“服务”“数据库”“队列”“外部系统”；组件层模板只允许“组件”“接口”。

模板的作用是物理上阻止你画错粒度。当你想在上下文图里塞一个数据库时，会发现模板里根本没有这个元素类型，于是你被迫思考“数据库属于容器层，我是不是该画下一张图”。这种“不方便”恰恰是设计的一部分。我实测下来，用模板约束后，团队里图表粒度的混乱程度下降了非常明显，评审时关于“这图画得太细/太粗”的争论几乎没有了。

3.3 源文件组织：一个图一个文件，一个目录一套系统

文件组织看起来是小事，但它决定了你三个月后能不能快速找到某张图。我的组织方式是：按系统分目录，按层级分文件，源文件和导出图分开存放。具体结构大致是这样：

diagrams/ order-system/ context.diagram container.diagram components/ payment.diagram inventory.diagram exports/ context.svg container.svg

源文件用文本格式，导出图用 SVG 而不是 PNG。为什么选 SVG？因为它是矢量图，放大不糊，而且本身也是文本，可以进版本库做 diff。PNG 虽然通用，但它是二进制，diff 出来是一堆乱码，评审时根本看不出改了什么。这个细节很多人忽略，但在实际协作里差别很大。

4. 实操过程：从零搭一套可维护的图表工作流

4.1 环境准备与工具链选择

先说工具。文本化图表的工具这几年成熟了不少，选择时我主要看三点：语法是否声明式、是否支持自动布局、导出格式是否够用。声明式意味着你描述“有什么”而不是“画在哪”，自动布局意味着你不用手动调坐标，导出格式至少要支持 SVG。这三点满足了，基本就能进工作流。

安装层面，大多数这类工具都是命令行程序，通过包管理器装即可。我一般会在项目根目录放一个配置文件，声明图表的输出目录、主题色、字体等。主题色统一很重要，否则每张图颜色都不一样，放在一起像拼盘。字体建议用系统自带的无衬线字体，避免导出时缺字。这些配置一次写好，后面所有图都继承，省去重复劳动。

注意：不要一上来就追求花哨的样式。图表的首要目标是清晰，颜色和图标是辅助。我见过太多图，配色很炫但连线交叉成一团，读者根本理不清。先把结构画对，样式最后再调。

4.2 第一张图：从术语表生成上下文图

实操从上下文图开始，因为它最简单，也最能验证工作流是否跑通。步骤是：先从术语表里挑出“系统本身”和“外部角色”，然后在源文件里声明这些节点和它们之间的交互。交互要写清楚方向和数据流向，比如“用户提交订单给订单系统”“订单系统向支付系统发起扣款”。

这里有个细节值得说：连线的标签要写动词短语，不要写名词。写“订单数据”不如写“提交订单”，因为前者只说明传了什么，后者说明了谁对谁做了什么。动词短语能让读者一眼看懂交互的意图。我早期图省事只写名词，结果评审时有人问“这条线到底是同步调用还是异步消息”，我答不上来，因为图里根本没表达。后来统一改成动词短语，这类问题少了很多。

生成第一张图后，先别急着画第二张。把源文件提交到版本库，改一个节点名字，再生成一次，看看 diff 是否清晰。如果 diff 能一眼看出改了什么，说明工作流是通的；如果 diff 是一团乱码，说明工具或格式选错了，趁早换。

4.3 逐层下钻：容器图与组件图的生成

上下文图跑通后，往下就是容器图和组件图。容器图的关键是把系统拆成可独立部署的单元，每个单元标注技术选型和职责。比如订单系统拆成“订单服务（负责创建和查询）”“订单库（存订单数据）”“订单队列（异步处理状态变更）”。这里要注意，容器图不是部署图，不用画服务器和网络，那是更下一层的事。

组件图再往下钻，把每个服务拆成内部组件。这一步最容易画过头，我的经验是只画有独立职责的组件，不画工具类和辅助函数。判断标准是：如果这个组件删掉，服务还能不能完成核心职责？能，说明它不是核心组件，可以不画。这样能有效控制图的复杂度。每画完一层，我都会回头对照术语表，确认所有节点名字都在表里，没有临时起意的新名字。

4.4 自动化：让图表跟着代码走

工作流跑顺之后，可以加一层自动化。最简单的做法是在 CI 里加一个步骤：每次合并到主分支，自动重新生成所有图表并提交回仓库。这样图表永远不会落后于源文件。再进一步，可以用脚本从代码里提取服务列表，自动生成容器图的骨架，人工只需要补充交互关系。

自动化的价值在于消除“忘了更新”这个借口。图表更新一旦依赖人的自觉，就一定会滞后。我现在的习惯是：改代码的 PR 里，如果涉及架构变化，必须同时改对应的图表源文件，否则 CI 会提示。这个约束一开始有人嫌麻烦，但跑了一段时间后，大家都习惯了，因为图表始终是准的，查问题时省下的时间远超改图的时间。

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

5.1 图表太乱怎么办：先删再拆

图表乱是最高频的问题。我的排查顺序是：先看是不是层级混了，如果是，拆图；再看是不是节点太多，如果是，删掉非核心节点；最后看是不是连线交叉太多，如果是，调整节点顺序或换布局方向。这三步走下来，九成的乱图都能救回来。

有个具体技巧：给节点按重要性排序，重要的放左上，次要的放右下。人的阅读习惯是从左上到右下，把核心节点放在视线起点，读者第一眼就能抓住重点。这个技巧在自动布局工具里也能用，大多数工具支持指定节点的优先级或分组，善用分组能把相关节点聚在一起，减少连线跨度。

5.2 命名对不上：术语表没维护好

命名对不上，几乎都是术语表没跟上。排查方法是：把所有图里的节点名提取出来，和术语表做一次比对，找出不在表里的名字。这些“野生名字”要么补进术语表，要么改掉。我建议补进术语表，因为野生名字往往反映了新的业务概念，是术语表该扩展的信号。

提示：可以写个小脚本定期做这个比对，比人工检查靠谱。脚本逻辑很简单：解析所有源文件，提取节点名，和术语表求差集。跑一次几秒钟，能省下大量排查时间。

5.3 导出图模糊：格式选错了

导出图模糊，基本是选了 PNG 或 JPG。这两种格式是位图，放大就糊。解决办法是导出 SVG，它是矢量图，任意缩放都清晰。如果某些平台不支持 SVG，可以导出高分辨率的 PNG 作为备选，但源文件一定要保留 SVG。另外，导出时注意字体嵌入，否则在没装对应字体的机器上打开会变样。

5.4 常见问题速查表

5.5 几个我踩过的坑

第一个坑是过早追求完美样式。刚开始做的时候，我花了很多时间调颜色和图标，结果结构没画对，样式再好看也没用。后来我定了个规矩：结构评审通过之前，不碰样式。第二个坑是术语表写得太正式。一开始我按写文档的标准写术语表，每条都写一大段，结果维护成本太高，没人愿意更新。后来改成一句话说明，维护意愿明显提升。第三个坑是自动化加得太早。工作流还没跑顺就上 CI，结果每次生成都报错，反而拖慢进度。正确的顺序是：手工跑通，再半自动，最后全自动。

6. 图表设计的延伸价值：从文档到沟通工具

6.1 图表作为团队共识的载体

图表设计做久了，我发现它的价值早就超出了“文档”范畴。一张结构清晰的图，其实是团队共识的载体。当大家对某个模块的理解有分歧时，把图摊开，指着图讨论，分歧往往很快收敛。因为图是具体的，而口头描述是模糊的。我现在的习惯是：任何有争议的设计讨论，先画一张图，再开会。图一画出来，很多争论自然就消解了。

这也解释了为什么图表要分层。不同角色关心的层级不同：管理者关心上下文层，架构师关心容器层，开发者关心组件层。分层之后，每个人都能找到自己关心的那张图，不用在一张巨图里找自己的部分。这种“各看各的层”的协作方式，比所有人盯着一张图高效得多。

6.2 图表作为新人上手的入口

新人入职最怕的是“不知道从哪看起”。一套分层清晰的图表，天然就是上手路径：先看上下文图了解系统边界，再看容器图了解技术组成，最后看组件图了解代码结构。这条路径比读文档快得多，因为图是并行的，一眼能看全，而文档是线性的，得一行行读。

我实测过，有图表体系的项目，新人上手时间能缩短不少。当然前提是图表是准的、更新的。如果图表滞后，反而会误导新人，所以前面强调的自动化更新在这里就体现出价值了。图表准，它就是最好的入门材料；图表不准，它就是最大的坑。

6.3 图表作为设计评审的依据

设计评审最容易变成“我觉得”和“我觉得”的对抗。有了图表，评审就有了共同参照物。评审时我会要求：每个设计点都要能在图上指出来。指不出来的，说明设计还没想清楚，或者图没画全。这个要求倒逼设计者在评审前把图想清楚，评审效率提升明显。

更进一步，图表源文件进版本库后，评审可以直接看 diff。这次改动加了哪个服务、删了哪条连线、改了哪个交互，diff 里一目了然。这比对着两张图片找不同靠谱多了。我现在的评审流程里，看图表 diff 是固定环节，很多问题在 diff 阶段就被发现了。

7. 我个人的几条实操心得

先说工具选择。不要迷信某一个工具，文本化图表工具这几年更新很快，选一个语法顺眼、导出格式够用、社区活跃的就行。关键是工作流，不是工具本身。我换过两次工具，因为工作流是清晰的，换工具只花了半天迁移，没伤筋动骨。

再说维护节奏。图表不要攒着一起更新，那样每次都是大工程。我的做法是小步更新：每次代码改动涉及架构，顺手改对应的图，一次改一两个节点，几分钟的事。攒着改，一次改几十个节点，光找位置就找半天，还容易漏。这个习惯养成后，图表维护几乎感觉不到负担。

最后说心态。图表设计这件事，前期投入是明显的，收益是滞后的。前两周你会觉得“画个图怎么这么麻烦”，但三个月后回头看，你会庆幸当初建了术语表和分层规则。我踩过的最大坑就是早期图省事，结果后面花了几倍时间返工。所以如果你正准备开始，我的建议是：先把术语表和分层规则定下来，哪怕只定个草稿，也比没有强。这两样东西是地基，地基打好了，上面怎么盖都稳。

另外分享一个小技巧：给每张图的源文件加一个头部注释，写清楚这张图的“最后更新日期”和“负责人”。这样当图过期时，你知道该找谁确认。这个注释不占地方，但能省下大量“这图谁画的、还能不能信”的沟通成本。我现在的所有图表源文件都有这个头部，团队里也形成了习惯，看到过期的图直接找负责人，效率高很多。