企业官网建设流程全解析

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

第一次看到 “diagram-design” 这个标题，很多人会以为它只是一个画图工具或者某个模板库。但真正做过系统设计、技术方案评审、产品架构梳理的人会立刻意识到，它指向的是一个更底层、更磨人的问题：如何把脑子里那些零散、跳跃、半成品的结构关系，稳定地转化成一张别人能看懂、能评审、能落地的图。

我做了十多年一线项目，画过的架构图、流程图、时序图、部署图、数据流图加起来少说也有大几百张。早期我用的是最笨的办法：打开绘图软件，拖方框、拉箭头、调对齐、改配色，一张图折腾两三个小时，改到第三版的时候自己都不想看了。后来我开始琢磨一件事——图不是画出来的，是设计出来的。diagram-design 这个项目标题背后，核心就是这套“设计先行”的方法论：先定义图的语义结构，再定义视觉规则，最后才动手渲染。它解决的不是“怎么画”，而是“怎么让图自己长成该有的样子”。

这套东西适合谁？如果你是后端开发、架构师、技术负责人，需要频繁输出系统设计文档，那它是刚需；如果你是产品经理、项目经理，需要把业务流程讲清楚，它同样适用；甚至你是写论文、做汇报的学生，只要涉及“把复杂关系可视化”，这套思路都能直接抄作业。它不依赖某个特定软件，而是一套可以迁移到任意工具里的设计系统。

我先把结论放在这里：diagram-design 的本质是用工程化思维管理图的语义层、结构层和视觉层，让图从“一次性手工作品”变成“可维护、可复用、可批量生成”的资产。下面我按自己实际落地的顺序，把这套东西拆开讲透。

2. 核心思路拆解：为什么大多数人的图越画越乱

2.1 图的三个层次：语义、结构、视觉

大部分人画图失败，不是因为审美差，而是因为把三个层次混在一起同时处理。你一边想“这个模块该放哪”，一边想“这个框用什么颜色”，一边又想“箭头怎么绕过去”，大脑的多线程能力瞬间被榨干，结果就是图越画越乱。

diagram-design 的第一个核心思路，就是强制分层：

• 语义层：这张图要表达什么关系？是调用关系、依赖关系、数据流向，还是状态迁移？语义层只关心“谁和谁之间发生了什么”，不关心长什么样。
• 结构层：这些关系如何组织？是分层、分簇、分时序，还是分区域？结构层决定图的骨架，比如分层架构图天然是上下结构，时序图天然是左右结构。
• 视觉层：颜色、线型、字号、间距、图标。视觉层只负责“让结构层更容易被眼睛解析”，它不承担任何语义职责。

我踩过最大的坑，就是早期把语义和视觉绑死。比如我用红色表示“核心服务”，结果后来核心服务变成了三个，红色不够用了，整张图就得重画。正确的做法是：语义层用标签和分组表达重要性，视觉层只是把标签映射成颜色。这样语义变了，只改映射规则，图的结构不动。

2.2 为什么选择“声明式”而不是“拖拽式”

拖拽式绘图（比如传统画图软件）的问题是：你画的是像素结果，不是关系描述。一旦某个节点要挪位置，所有跟它相连的线都要手动重连。图越大，维护成本呈指数上升。

diagram-design 走的是声明式路线：你用文本或结构化数据描述“有哪些节点、哪些边、哪些分组”，渲染引擎负责自动布局。这跟写代码是一个道理——你声明“我要一个按钮”，而不是手动去画一个按钮的每一个像素。

声明式带来的直接好处有三个。第一，版本可控：图的定义就是一份文本文件，可以进 Git，可以 diff，可以 code review。第二，批量生成：同一套结构定义，换一套视觉主题，就能输出适配不同场景的图。第三，一致性：所有图共用同一套布局规则，不会出现这张图方框圆角、那张图方框直角的混乱。

我实测下来，用声明式方式维护一套包含 30 多个节点的微服务架构图，改一个服务名只需要改一行文本，重新渲染 3 秒出图。而用拖拽方式，同样的改动至少要 10 分钟，还容易漏改连线标签。

2.3 设计系统的四个支柱

把 diagram-design 落地成一套可复用的系统，我总结出四个必须提前定义的支柱：

这四个支柱里，语义词汇表是最容易被忽略但最重要的。我见过太多团队，A 画的图里叫“服务”，B 画的图里叫“模块”，C 画的图里叫“组件”，其实说的是同一个东西。diagram-design 要求你在动手之前，先把这张图里会用到的所有名词和动词列出来，定义清楚。这一步花 20 分钟，能省后面 2 小时的扯皮。

3. 核心细节解析：语义层怎么定义才不返工

3.1 节点类型：别超过七种

心理学上有个经典结论：人短期记忆能同时处理的信息块大约是 7±2 个。图的节点类型如果超过七种，读者就需要频繁回看图例，阅读体验断崖式下跌。

我在实际项目里把节点类型控制在5 到 6 种，比如：

• 服务（Service）：可独立部署的单元
• 存储（Store）：数据库、缓存、对象存储
• 队列（Queue）：消息中间件
• 外部系统（External）：不在本系统控制范围内的依赖
• 用户角色（Actor）：触发流程的人或系统

每种节点类型对应一个固定的视觉形状。比如服务用圆角矩形，存储用圆柱体，队列用平行四边形，外部系统用虚线框。这样读者不用看图例，光看形状就能猜出大概。

注意：节点类型一旦定下来，整个项目周期内不要轻易增加。如果实在需要新类型，优先考虑用“标签”而不是“新形状”来表达。比如“这个服务是核心服务”，用加粗边框或角标表达，而不是新造一个“核心服务”形状。

3.2 边类型：方向、线型、标签三要素

边比节点更容易乱。我见过一张图里同时出现实线、虚线、点线、双线、带箭头、不带箭头、带菱形、带圆形……读者直接放弃。

diagram-design 对边的定义只有三个维度：

1. 方向：有向还是无向。绝大多数技术图都是有向的，无向边只在表示“关联”时使用。
2. 线型：实线表示同步调用或强依赖，虚线表示异步消息或弱依赖，点线表示可选或未来规划。
3. 标签：边上必须写清楚“发生了什么”。比如“HTTP 调用”“写入”“订阅”“推送”。

我强烈建议：每条边都要有标签。没有标签的边等于没说清楚关系，评审的时候一定被问。标签的写法也有讲究，用“动词+名词”结构，比如“查询订单”“写入日志”，而不是只写“调用”。

3.3 分组与边界：让图有“房间感”

一张没有分组的架构图，就像一间没有隔断的大仓库，所有东西堆在一起，找什么都费劲。分组的作用是给图建立“房间感”，让读者知道哪些东西属于同一个逻辑单元。

常见的分组维度有三种：

• 按部署边界分组：比如“客户端”“网关层”“服务层”“数据层”
• 按业务域分组：比如“订单域”“支付域”“用户域”
• 按团队归属分组：比如“基础架构组”“业务中台组”

分组不要超过两层。一层大分组，里面最多再套一层小分组。三层以上的嵌套，读者会迷失在框里框外。

实操心得：分组框的标题放在左上角，用比节点标题小一号的字号，颜色用中性灰。这样分组框不会抢节点的视觉焦点，但又能清晰界定范围。

3.4 命名规范：让图能“读”出来

图不仅要能看，还要能读。什么叫能读？就是你把图上的文字按顺序念出来，能形成一句通顺的话。

我给自己定的命名规范是：

• 节点名用名词短语，首字母大写，比如“Order Service”“User Store”
• 边标签用动词短语，小写开头，比如“queries”“writes to”“subscribes”
• 分组名用范围名词，比如“Data Layer”“Payment Domain”

这样一张图读下来就是：“Order Service queries Order Store, Order Service publishes to Payment Queue, Payment Service subscribes from Payment Queue……”逻辑链条清清楚楚。

4. 实操过程：从零搭建一套可复用的图设计系统

4.1 第一步：建立语义词汇表文件

我习惯在项目根目录建一个diagram-vocab.md，把所有节点类型、边类型、分组类型列出来。格式大概是这样：

## 节点类型 - service: 可独立部署的服务单元，圆角矩形 - store: 数据存储，圆柱体 - queue: 消息队列，平行四边形 - external: 外部依赖，虚线圆角矩形 - actor: 用户或触发者，圆形 ## 边类型 - sync: 同步调用，实线箭头 - async: 异步消息，虚线箭头 - write: 写入，实线箭头，标签必填 - read: 读取，实线箭头，标签必填 - optional: 可选依赖，点线箭头 ## 分组类型 - layer: 部署层次，浅灰背景 - domain: 业务域，浅蓝背景 - team: 团队边界，浅绿背景

这个文件是整个设计系统的“字典”。后面所有图的定义都只能引用这里出现过的类型，不允许临时发明新类型。如果确实需要新类型，先改字典，再改图。

4.2 第二步：定义布局规则

布局规则决定了图的“骨架”。我常用的三种布局模式：

分层布局（Layered）：适合架构图、部署图。节点按层从上到下排列，层与层之间用边连接。层内节点水平排列，层间间距固定。

力导向布局（Force-directed）：适合关系网络、依赖图。节点根据连接关系自动散开，连接多的节点自然聚在一起。缺点是每次渲染位置可能不同，需要固定随机种子。

时序布局（Sequential）：适合流程图、时序图。节点按时间或步骤从左到右排列，边表示流转方向。

在声明式工具里，布局规则通常通过属性指定。比如：

layout: layered direction: top-to-bottom layer-gap: 80 node-gap: 40

这几个参数我调过很多次，最后稳定在：层间距 80px，节点间距 40px，节点宽度 160px，节点高度 60px。这个尺寸在 1080p 屏幕上缩放 100% 时，文字清晰可读，整体又不至于太散。

4.3 第三步：配置视觉主题

视觉主题是一组映射规则，把语义类型映射到具体的颜色、字体、线宽。我通常定义两套主题：一套浅色用于文档，一套深色用于演示。

浅色主题的核心参数：

这套配色我用了三年，最大的优点是打印成黑白也不会糊。因为不同节点类型的填充灰度不同，边框虚实不同，即使没有颜色也能区分。

注意：不要用纯红、纯绿、纯蓝这种高饱和度颜色。高饱和色在投影仪上会刺眼，在打印时会变成一团黑。用低饱和度的“粉彩系”颜色，专业感更强。

4.4 第四步：编写图定义文件

有了词汇表、布局规则、视觉主题，就可以写具体的图定义了。我以一张典型的微服务架构图为例，展示定义文件的结构：

title: 订单系统架构 layout: layered theme: light nodes: - id: user type: actor label: 用户 layer: 0 - id: gateway type: service label: API Gateway layer: 1 - id: order-svc type: service label: Order Service layer: 2 - id: payment-svc type: service label: Payment Service layer: 2 - id: order-db type: store label: Order DB layer: 3 - id: payment-queue type: queue label: Payment Queue layer: 3 edges: - from: user to: gateway type: sync label: HTTPS - from: gateway to: order-svc type: sync label: 路由 - from: order-svc to: order-db type: write label: 写入订单 - from: order-svc to: payment-queue type: async label: 发布支付消息 - from: payment-svc to: payment-queue type: async label: 订阅支付消息 groups: - id:>