企业官网建设流程全解析

1. 从一张草图到一套视觉语言：diagram-design 到底在解决什么问题

很多人第一次听到 diagram-design 这个词，会下意识觉得它只是“画图”的另一种说法。但真正在项目里做过架构图、流程图、时序图、部署拓扑图的人都知道，画图本身从来不是难点，难点在于图与图之间的一致性、可维护性和表达效率。你画第一张架构图的时候，可能花十分钟就搞定了，配色随意、字体随意、箭头样式随意，看起来还挺清爽。等到项目里需要第五张、第十张图的时候，问题就来了：颜色对不上、线宽不统一、图例缺失、同一个模块在不同图里叫法不一样，最后整份文档看起来像是五个人分别做的。

diagram-design 要解决的就是这个问题。它不是某个具体的绘图工具，也不是某个库的别名，而是一套围绕图表设计的系统性方法论加落地规范。你可以把它理解成“给图表做设计系统”的思路：先定义一套视觉语言，包括颜色语义、形状语义、间距规则、字体层级、连线规范，然后再用这套语言去批量生产图表。这样做的好处非常直接——当你需要新增一张图时，不需要从零开始纠结“这个框用什么颜色”，而是直接查表：数据层用蓝色、服务层用绿色、外部依赖用灰色虚线框，照着规则拼就行。

我最初接触这套思路，是因为一个跨平台系统项目。当时项目文档里有二十多张图，分别由后端、前端、运维三拨人维护。每次评审，总有人问“这个黄色框是什么意思”“为什么这两张图的数据库图标不一样”。后来我们花了两天时间，把所有的图停掉，先做了一套 diagram-design 规范，再回头统一重绘。重绘之后，评审时间直接缩短了一半，因为大家不再需要花精力去解读图的“方言”，而是直接看结构本身。

这套方法适合谁？如果你是技术文档撰写者、系统架构师、产品经理，或者任何需要频繁用图表沟通的人，它都能帮你省下大量反复解释和返工的时间。哪怕你只是偶尔画一张流程图，了解这套思路也能让你的图看起来更专业、更易读。接下来我会从核心构成、工具选型、实操步骤、常见坑几个角度，把这套东西完整拆开讲清楚。

2. diagram-design 的四个核心支柱：颜色、形状、排版、连线

2.1 颜色不是装饰，而是语义载体

很多人选颜色凭感觉，觉得蓝色专业、绿色清新、橙色醒目。但在 diagram-design 里，颜色的第一原则是语义固定，第二原则才是美观。也就是说，一旦你定义了“蓝色代表数据存储”，那么所有图里的数据库、缓存、消息队列都必须用蓝色系，不能因为这张图里蓝色不好看就换成紫色。

具体怎么定？我通常建议按“层”来分色。比如一个典型的后端系统图，可以分成四层：接入层、服务层、数据层、外部依赖。每层给一个主色，再给一个浅色作为填充、一个深色作为边框。这样即使图里元素很多，读者也能通过颜色快速定位到“这是哪一层的东西”。

这张表一旦定下来，就贴在团队 wiki 里。任何人画图之前先查表，不允许自由发挥。你可能会觉得这样太死板，但实际用下来，正是这种“死板”换来了跨图一致性。而且当所有人都遵守同一套颜色规则时，图与图之间的对比、拼接、复用会变得非常顺畅。

还有一个细节：颜色数量要克制。我见过一些图用了七八种颜色，结果读者根本记不住哪个颜色代表什么。一般来说，主色不超过五种，加上黑白灰作为辅助，足够了。如果确实需要区分更多类别，优先用形状或标签来区分，而不是继续加颜色。

2.2 形状承载角色，圆角方角都有讲究

颜色之外，形状是第二层语义。在 diagram-design 里，不同形状代表不同角色，这个规则也要提前定好。比如：

• 矩形：普通服务、模块、组件
• 圆角矩形：有状态的东西，比如数据库、缓存
• 圆柱体：传统数据库的经典符号，但现代图里也可以用圆角矩形替代
• 菱形：判断节点，用于流程图
• 平行四边形：输入输出，用于数据流图
• 虚线框：外部系统或边界之外的东西

这些规则看起来是常识，但实际画图时很容易被忽略。我见过有人用菱形表示服务，用矩形表示判断，结果读者完全懵了。所以我的建议是：在项目开始前，把形状规则写成一页纸的规范，附上示例图，让所有人照着做。

另外，形状的尺寸也要有层级。核心模块可以画大一点，辅助模块画小一点，但同一层级的模块尺寸要一致。不要出现“这个服务框比那个服务框大一圈”的情况，除非你确实想表达“这个服务更重要”。但即便如此，也建议用颜色或标签来表达重要性，而不是用尺寸，因为尺寸不一致会破坏整体视觉节奏。

2.3 排版决定可读性，字体和间距不能随意

图表的排版包括字体、字号、对齐方式、间距、留白。这些东西在单张图里可能不明显，但多张图放在一起时，排版混乱会非常刺眼。

字体方面，我强烈建议全项目统一使用一种无衬线字体，比如思源黑体、Noto Sans、Inter 这类。不要在一张图里混用宋体和黑体，也不要用艺术字体。字号一般分三档：标题 16-18px，正文 12-14px，注释 10-11px。同一层级的文字必须用同一字号，不能因为“这个标签字多就缩小一点”。

对齐方面，能对齐就对齐。模块之间的水平间距、垂直间距要一致，文字在框内要居中或左对齐统一。我见过一些图，模块位置全靠手动拖拽，结果间距忽大忽小，看起来像随手撒上去的。正确的做法是使用工具的“对齐分布”功能，或者直接用网格布局。

留白也很关键。图不要太满，边缘留出至少 20px 的空白，模块之间留出至少 30px 的间距。如果图很复杂，可以考虑分块，用浅色背景或虚线框把相关模块圈在一起，形成视觉分组。

2.4 连线是图的血管，箭头和路由要统一

连线是最容易被忽视的部分。很多人画图时只关心框画得对不对，连线随便拉一条，结果线交叉、线穿框、箭头方向混乱。

diagram-design 对连线的要求有三条：方向明确、路由清晰、样式统一。方向明确是指箭头必须指向数据或控制流的方向，不能双向箭头满天飞。路由清晰是指连线尽量走直角或平滑曲线，避免斜线和交叉。样式统一是指所有同类连线用同一种线型、线宽、箭头样式。

比如，同步调用用实线箭头，异步消息用虚线箭头，数据流用带圆点的线。这些规则定好之后，图的可读性会大幅提升。另外，连线上的标签要放在线的上方或旁边，不要压在线上，也不要离得太远。

3. 工具选型：从手绘到代码化，哪条路适合你

3.1 手绘工具和在线白板的适用边界

说到画图工具，很多人第一反应是 ProcessOn、Draw.io、Excalidraw 这类。它们的特点是上手快、拖拽方便、适合快速表达。如果你的图不多，或者只是内部讨论用，这些工具完全够用。

但如果你要维护一个长期项目，图会频繁更新，那手绘工具的劣势就暴露了：版本管理困难、样式复用麻烦、批量修改几乎不可能。你改了一个模块的名字，得手动去每张图里找。你换了一个主色，得一张一张调。这种重复劳动在项目中期会让人非常烦躁。

我的经验是：探索阶段用手绘工具，固化阶段用代码化工具。前期讨论时，用 Excalidraw 快速画草图，大家看个大概。等结构定下来了，再用代码化工具生成正式图，纳入版本管理。

3.2 代码化绘图工具的核心优势

代码化绘图工具，比如 Mermaid、PlantUML、Graphviz、D2 这些，最大的优势是图即代码。你可以把图的定义写在文本文件里，用 Git 管理，用 CI 自动生成图片。改一个模块名字，只需要改一行文本，所有引用它的图都会自动更新。

以 Mermaid 为例，画一个简单的流程图只需要几行：

graph TD A[客户端] --> B[网关] B --> C[服务A] B --> D[服务B] C --> E[(数据库)] D --> E

这段代码生成的图，样式可能不如手绘工具那么精致，但胜在可维护。而且 Mermaid 支持自定义主题，你可以通过配置文件把颜色、字体、间距统一改掉，实现 diagram-design 的规范落地。

PlantUML 在时序图和类图上更强，Graphviz 在复杂拓扑布局上更灵活，D2 则是新兴的声明式绘图语言，语法更现代。选择哪个，取决于你的主要图类型和团队技术栈。

3.3 混合工作流：草图用白板，定稿用代码

实际项目中，我推荐一种混合工作流：先用白板工具快速勾勒结构，确认无误后，再用代码化工具重绘定稿。这样做的好处是，前期沟通效率高，后期维护成本低。

具体操作上，可以在项目仓库里建一个diagrams目录，里面放.mmd或.puml源文件，再配一个脚本，用命令行工具批量导出 PNG 或 SVG。每次 CI 跑的时候，自动检查图是否能正常生成，避免源文件语法错误导致图挂掉。

提示：代码化工具的布局算法有时会出人意料，比如把两个本该在一起的模块分得很远。这时候不要硬调，而是调整节点声明顺序或加一些不可见的辅助节点来引导布局。

4. 落地实操：从零搭建一套 diagram-design 规范

4.1 第一步：盘点现有图表，找出共性问题

在定规范之前，先把你项目里现有的图全部过一遍。不用细看内容，只看形式：颜色用了多少种？字体有几种？箭头样式有几种？模块命名是否一致？把这些问题列出来，你就知道规范需要覆盖哪些方面了。

我通常会做一个简单的表格，把每张图的问题记下来。比如“图3用了橙色表示数据库，图7用了蓝色表示数据库”“图5的箭头是实心三角，图9的箭头是空心三角”。这些问题就是规范要解决的重点。

4.2 第二步：定义最小可行规范

不要一上来就搞几百页的规范文档，没人会看。先定一个最小可行规范，覆盖最核心的几件事：颜色语义、形状语义、字体字号、连线样式。这四件事定下来，图的统一性就能提升 80%。

规范文档建议用 Markdown 写，放在项目仓库里，配上一张示例图。示例图要包含所有颜色和形状的用法，让人一眼就能看懂。比如：

## 颜色规范 - 蓝色 #4A90D9：数据存储 - 绿色 #50B86C：业务服务 - 灰色 #9B9B9B：外部依赖 ## 形状规范 - 矩形：无状态服务 - 圆角矩形：有状态组件 - 虚线框：外部系统

4.3 第三步：制作模板和片段库

规范定好之后，下一步是降低执行成本。如果每次画图都要手动调颜色、调字体，没人能坚持。所以要做模板和片段库。

在 Draw.io 里，可以做一个自定义形状库，把常用的模块做成拖拽即用的组件。在 Mermaid 里，可以写一个主题配置文件，把所有样式预定义好。在 PlantUML 里，可以用!include引入公共样式文件。

我自己的做法是，在项目仓库里放一个diagram-theme目录，里面包含：

• theme.json：颜色和字体定义
• shapes.xml：自定义形状库
• template.mmd：Mermaid 模板文件
• example.png：示例图

新成员加入时，直接把这个目录拷走，照着示例图改就行。

4.4 第四步：建立评审和更新机制

规范不是定完就完了，还需要评审和更新机制。每次新增图或修改图，都要检查是否符合规范。可以在代码评审时加一条：如果 PR 里包含图表变更，必须检查颜色、形状、字体是否合规。

同时，规范本身也要定期回顾。如果发现某条规则在实际使用中经常被违反，可能是规则本身不合理，需要调整。比如我们曾经规定“所有外部依赖必须用灰色虚线框”，后来发现有些外部依赖很重要，用灰色显得太弱，就改成了“核心外部依赖用灰色实线框，非核心用灰色虚线框”。

5. 踩坑实录：那些年我们在图表设计上犯过的错

5.1 颜色太多导致图例失效

早期做项目时，我们觉得颜色越多越好看，结果一张图里用了九种颜色。读者看的时候，根本记不住哪个颜色代表什么，每次都要回头看图例。后来我们砍到四种主色，图例直接省了，因为读者看一眼就能猜到“蓝色是数据库、绿色是服务”。

这个坑的本质是把颜色当装饰而不是语义。颜色一旦超过五种，人的短期记忆就跟不上了。所以我的建议是：主色不超过五种，辅助色用黑白灰，特殊强调用红色或橙色，但只用于标注重点。

5.2 模块命名不一致引发沟通成本

另一个常见的坑是模块命名。同一个服务，在架构图里叫“用户服务”，在时序图里叫“UserService”，在部署图里叫“user-svc”。看起来是小事，但每次评审都要花时间确认“这三个是不是同一个东西”。

解决办法是建立术语表，把所有模块的正式名称、缩写、别名都列出来，画图时统一使用正式名称。如果图里空间不够，可以用缩写，但缩写也必须在术语表里定义。

5.3 连线交叉导致的阅读障碍

连线交叉是图表可读性的头号杀手。我见过一张图，十几条线交叉在一起，像一团乱麻。读者根本分不清哪条线连哪里。

解决连线交叉的方法有几个：一是调整模块位置，把有连线的模块放近一点；二是使用正交路由，让线走直角而不是斜线；三是分层布局，把不同层的模块放在不同水平线上；四是如果实在太多，拆成多张图，不要硬塞在一张图里。

5.4 过度追求美观导致维护困难

有些人为了图好看，用了大量渐变、阴影、3D 效果。单张图确实漂亮，但一旦要修改，就得重新调所有样式。而且不同人做的图，渐变方向、阴影深度都不一样，放在一起反而更乱。

我的观点是：图表的首要目标是清晰传达信息，美观是第二位的。扁平化、简洁的风格不仅好看，而且好维护。少用特效，多用留白和对比，效果反而更好。

6. 让 diagram-design 融入团队工作流

6.1 把图表源文件纳入版本管理

图表源文件一定要放进 Git 仓库，和代码一起管理。这样做的好处是：每次修改都有记录，可以回滚，可以对比差异。如果图是二进制文件，至少也要把源文件放进去，导出的图片可以放文档目录。

对于代码化工具，源文件本身就是文本，天然适合版本管理。对于手绘工具，可以导出为 XML 或 JSON 格式，也能纳入 Git。

6.2 在 CI 中自动生成和检查图表

如果使用代码化工具，可以在 CI 里加一步：自动生成图表并检查是否有语法错误。这样能避免源文件改坏了没人发现。更进一步，可以把生成的图自动发布到文档站点，保证文档里的图永远是最新的。

# 示例：用 Mermaid CLI 批量生成图表 for file in diagrams/*.mmd; do mmdc -i "$file" -o "docs/images/$(basename "$file" .mmd).png" done

6.3 定期做图表审计

每隔一个季度或半年，把项目里的图全部过一遍，检查是否有过时的、重复的、不符合规范的。过时的图直接删掉或归档，重复的图合并，不符合规范的图重绘。这个工作看起来繁琐，但能避免文档里堆积大量无效信息。

我自己的习惯是，每次大版本发布前，花半天时间做一次图表审计。把审计结果记在一个清单里，逐项处理。这样文档里的图始终是“活”的，而不是一堆没人看的旧图。

6.4 培养团队的图表设计意识

最后一点，也是最重要的一点：规范再好，没人执行也没用。所以要在团队里培养图表设计意识。新成员入职时，把 diagram-design 规范作为培训材料之一。代码评审时，把图表质量作为评审项之一。定期分享一些好的图表案例和坏的案例，让大家有直观感受。

我见过最有效的做法是，在团队里设一个“图表守护者”的角色，由一个人负责维护规范、审核图表、解答疑问。这个人不一定是领导，但一定是对视觉表达有敏感度的人。有了这个角色，规范才能真正落地。

7. 一些让我少走弯路的实操心得

第一，先定规范再画图，不要边画边定。很多人觉得“我先画几张，画着画着规范就出来了”。但实际情况是，画着画着就画歪了，后面再回头统一，成本更高。正确的顺序是：先花半天定规范，再花半天画图，总时间反而更短。

第二，规范要配示例，不要只写文字。文字描述“蓝色代表数据存储”，不如直接放一张示例图，用蓝色框标出数据库。人是对图像敏感的动物，示例图比文字管用十倍。

第三，工具选型不要追求最新最酷，要追求团队能用起来。我见过团队引入了一个很强大的绘图工具，结果学习成本太高，没人用，最后还是回到 Draw.io。工具是手段，不是目的。

第四，图表不是越详细越好。一张图如果塞了五十个模块，读者根本看不过来。该拆就拆，一张图讲清楚一件事就够了。细节可以放在附录或单独的图里。

第五，定期清理旧图。项目迭代过程中，会产生大量过时的图。这些图如果不清理，会干扰读者，也会增加维护负担。我的做法是，每次大版本发布时，把旧图移到archive目录，文档里只保留当前版本的图。

第六，颜色要考虑色盲用户。红绿色盲是最常见的色盲类型，如果只用红绿区分，这部分用户会看不懂。解决办法是颜色加形状双重编码，比如红色用圆形、绿色用方形，这样即使分不清颜色，也能通过形状区分。

第七，图里的文字要能选中和搜索。如果导出的是图片，文字就变成了像素，无法搜索。所以尽量导出 SVG 格式，或者在文档里同时提供源文件和图片。这样读者可以搜索关键词，快速定位到相关图。

第八，不要忽视图例的作用。如果图里用了多种颜色或形状，一定要加图例。图例放在图的角落，不要太大，但要清晰。图例的样式也要统一，不要这张图图例在左上，那张图图例在右下。

第九，连线上的标签要精简。我见过连线上写了一大段话，结果线被文字挡住，根本看不清。标签最好控制在五个字以内，比如“HTTP”“异步”“写入”。详细说明可以放在图下方的注释里。

第十，多看图，多借鉴。平时看到好的图，随手保存下来，分析它为什么好。是颜色用得好，还是布局清晰，还是连线简洁。积累多了，自己的图表设计能力自然就上去了。

这套 diagram-design 的思路，我从第一次尝试到现在，已经用了好几年。中间踩过不少坑，也总结了不少经验。最大的感受是：图表设计不是天赋，而是可以习得的技能。只要有一套清晰的规范，加上持续的实践和迭代，任何人都能画出专业、清晰、易维护的图。希望这些内容能帮你在下一个项目里少走一些弯路，把更多时间花在真正重要的事情上。