最近把项目里那堆散得到处都是的图纸统一整理了一轮，发现一个特别有意思的现象：团队里明明有现成的架构设计、流程梳理，但一到评审会上，大家对着屏幕各说各话，因为每张图的画法都不一样——有人习惯从上往下画，有人从左往右画；有人用红色表示告警，有人用红色表示核心模块。归根结底不是画图能力的问题，是缺一套统一的图表设计规范。我把这套沉淀下来的东西叫作 diagram-design，它不是什么高深算法，也不是某个特定绘图软件的操作教程，而是一套"怎么把一张图画得让人快速看懂"的规则，外加一组能把规则自动落到图上的脚本工具。如果你经常要画架构图、时序图、状态图，或者团队里协作画图时总觉得"风格不统一、改起来想死"，这篇内容就是给你准备的。
1. diagram-design 到底在解决什么问题
1.1 图纸多但信息乱：先解决"能看懂"这件事
先复盘一下我去年的实际状态。当时我们在做一个跨平台系统，涉及前端、网关、多个后端服务、数据库和外部对接。一轮迭代下来，光架构图就有六个版本，分布在三个不同工具里。有的图把数据库画成圆柱体，有的画成桶，有的干脆用方框加个"D"字。表面看只是图形符号不统一，实际带来的连锁反应是：每次评审都要先花十分钟对齐符号含义，然后才能进入正题讨论方案。
diagram-design 解决的第一件事就是信息结构统一。它规定了一张图里必须有明确的分层：什么信息放在标题区，什么信息属于图例，核心节点和辅助节点如何区分。比如架构图里，用户侧、接入层、服务层、数据层这样的大分区是固定的，每一层用什么底色、什么边框风格都有明确约束。这么做的原因很简单，人的阅读习惯是逐步聚焦的，如果第一眼看到的信息量过大，大脑会直接放弃理解。把信息分好层级，等于先给读者搭了一个扶手。
第二件事是状态可追踪。业务图最怕画完就变"死图"——代码改了，图没人改。diagram-design 鼓励用"图即代码"的方式保存图源文件，每次改动的 diff 清晰可见，可以和代码提交关联起来。这样图不再是文档里的装饰品，而是随手可维护的开发资产。
注意：这里说的不是"图要画得多好看"，而是"图要经得起团队协作的检验"。一张只有你自己看得懂的图，不管多精美，在协作场景里都是负资产。
1.2 设计目标的取舍：不是追求好看，而是降低共识成本
做 diagram-design 的时候，我反复提醒自己一个原则：图的本质是沟通媒介，不是艺术作品。一张网络拓扑图，不需要渐变阴影，不需要毛玻璃效果，它需要的是让人三秒钟内看出关键路径在哪里，五秒钟内找出瓶颈点。
这个原则落到具体设计上，就是三个取舍。第一，牺牲装饰性换取规范性：所有节点统一直角圆角、统一阴影半径、统一线宽，不搞花哨的自定义样式。第二，牺牲自由度换取自动化：元素位置尽量由布局算法决定，手动拖拽只作为兜底方案，这样才能批量生成、批量修改。第三，牺牲"画得全"换取"看得懂"：一张图只表达一个核心主题，比如架构图就讲系统组成，时序图就讲一次请求的完整链路，不要把十件事塞进一张图里。
打个比方，这就像高速公路上的路牌。路牌本身的颜色、字体、安装高度都是国家统一标准的，驾驶员不需要在高速上花心思解码路牌，只需要根据颜色和形状快速反应。图也是一样，当所有的框都是同一种风格，读者节省下来的认知资源就能全部用在理解业务逻辑上，而不是费劲区分"这个颜色到底代表什么意思"。
2. 设计规范怎么定
2.1 网格与间距：所有元素都落在 8pt 网格上
diagram-design 的第一条硬性规定是：画布采用 8pt 网格系统，所有节点的位置、尺寸、间距都必须是 8 的整数倍。为什么是 8 而不是 10？因为 8 是偶数，能够整除 16、32、64 这些常见尺寸，四舍五入后不容易出现 0.5px 的毛边。更重要的是，8pt 在主流屏幕密度下恰好对应一个舒适的视觉节奏，不会太挤也不会太松。
具体到使用上，我一般把间距体系分成四个档位：
- 节点内部 padding：8pt，保证文字和边框之间留出呼吸感；
- 相邻节点间距：24pt，避免信息拥塞，又能让连线有足够空间；
- 分组区块边距：32pt，用于隔离不同语义区域；
- 画布留白：48pt，保证导出图片时边缘不裁切。
这套间距并不是拍脑袋定的，而是实测后的结果。我最早用的是 4pt 网格，结果两个节点之间的连线经常擦着边框擦过去，放大之后非常丑。换成 8pt 之后，所有元素都有了明确的落位，节点对齐只需设置坐标倍数，不用再手工微调。如果你的图需要容纳特别多的信息，可以把间距压缩到 4pt，但一律不允许出现类似 13.5、27 这种小数，因为小数坐标在缩放时一定会模糊，而且后期程序化生成时容易累积误差。
2.2 配色体系：主色铺底、强调色点睛、语义色警示
配色是 diagram-design 里最容易失控的部分。很多手绘的图配色非常随意，想表达"这个模块重要"就随手标个橙色，想表达"这里暂时没实现"就标个灰色。一个人这样画没问题，十个人这样画，同一张图里就会出现五六种颜色表达同一种状态。
我的解决思路是把颜色严格分为三类。第一类是中性色，用于画布背景、卡片底色、面板底色、辅助文字，这类颜色饱和度极低，承担"搭框架"的功能。第二类是主色，用于核心节点、主流程线条，通常取一个品牌色的中饱和版本，全图的主色建议不超过一种。第三类是语义色，用于表达状态——成功、失败、警告、禁用，这类颜色是固定的，任何表里都不允许出现第二种绿色表示成功。
我当时定的这套配色表，实测下来在所有主流屏幕上都有不错的辨识度：
| 用途 | 色值 | 说明 |
|---|---|---|
| 画布背景 | #FFFFFF | 白底最稳妥，深色模式单独适配 |
| 区块底色 | #F8FAFC | 极浅灰，用于分组面板 |
| 节点主色 | #2563EB | 中饱和蓝，负责视觉视觉锚点 |
| 强调色 | #F59E0B | 暖橙，用于热点标注、核心路径 |
| 成功 | #10B981 | 翠绿，表示正常态 |
| 危险 | #EF4444 | 红色，表示故障、拒绝逻辑 |
| 主文本 | #1E293B | 深灰蓝，正文标题 |
| 辅助文本 | #64748B | 中灰，注释说明 |
| 连接线 | #94A3B8 | 亮灰，避免抢正文风头 |
颜色还有个容易忽略的指标是对比度。节点上的文字和背景色之间的对比度至少要到 4.5:1，这是无障碍阅读的底线。比如在主色#2563EB上面写文字，就绝对不能再用黑色，正确做法是用白色。我在实际项目里踩过这个坑，蓝色底配黑字，看着是能认出来，但投影到评审室的大屏上，后排的人完全看不清。
2.3 字体、图标、连线：细节决定图的"高级感"
如果说网格和配色是图的骨架，那字体、图标、连线就是图的肌肉和皮肤。这三样东西单独看都不起眼，合在一起却是决定一张图是"专业工具产出"还是"临时白板截图"的关键分水岭。
字体方面，中英文混排时最忌讳的是直接使用系统默认字体。我推荐标题用无衬线中型字重，正文用常规字重，代码片段或服务名用等宽字体。具体到字号，图名、Section 标题、节点标题、注释四档分别用 20pt、14pt、12pt、10pt。记住，一像素的字体大小差异在普通屏幕上感知不明显，但在缩放的矢量图里会被成倍放大，所以字号也必须遵守倍数关系，不能出现 13pt 这种孤立值。
图标这块，很容易出现的错误是"混搭"。一套图里，有的图标来自开源图标库，有的来自商业图标库，还有的是自己画的简笔画，风格差异巨大。规定很简单：所有图标统一使用线性风格、统一描边粗细、统一圆角半径。我甚至建议临界情况把图标直接禁掉——服务名用文字表达往往比找个不贴切的图标更稳妥。
连线是最容易被轻视的部分。diagram-design 对线型有一整套约定：主数据流用实线加箭头，辅助流程用虚线，回退或拒绝路径用红色实线，依赖关系用无箭头的灰色实线。线宽统一为 1.5px，连接点统一在节点边界的中点，而不是直接连到节点中心。弯折的地方使用圆角而不是直角，圆角半径按间距档位取 8pt。这些约定初看繁琐，但它们保证了任何两张图拼接在一起时不会产生割裂感。
3. 把规范落到代码
3.1 核心数据模型：节点、边、画布
规范如果只停留在文档层面，执行起来靠自觉，那效果一定打折扣。diagram-design 真正起作用，是因为我把这套规范写进了一个小型生成工具里：你提供结构化的描述，工具负责计算坐标、渲染样式、导出图片。这条思路和很多现代绘图工具一脉相承，但我更愿意用自己可控的代码来实现，因为可以深度定制。
先看核心数据模型。我用 Python dataclass 定义了三个基础类：Node、Edge、Diagram。Node描述一个图形元素，包含唯一标识、标题、类型、关联数据；Edge描述两个节点之间的连接关系；Diagram是容器，负责组合节点和边并计算布局。
from dataclasses import dataclass, field from typing import Dict, List, Optional, Tuple @dataclass class Node: id: str label: str node_type: str = "default" # 可选：system / service / data / external x: float = 0.0 y: float = 0.0 w: float = 120.0 h: float = 56.0 style: Dict[str, str] = field(default_factory=dict) @dataclass class Edge: src: str dst: str label: str = "" edge_type: str = "solid" # 可选：solid / dashed / red_solid / gray_solid style: Dict[str, str] = field(default_factory=dict) @dataclass class Diagram: title: str = "" nodes: List[Node] = field(default_factory=list) edges: List[Edge] = field(default_factory=list) layout_mode: str = "layered" # 可选：layered / grid / free def add_node(self, node: Node) -> None: self.nodes.append(node) def add_edge(self, edge: Edge) -> None: self.nodes_ids = {n.id for n in self.nodes} if edge.src not in self.nodes_ids or edge.dst not in self.nodes_ids: raise ValueError(f"Edge {edge.src} -> {edge.dst} 引用了不存在的节点") self.edges.append(edge)这个模型把"画图"拆成了两个正交的部分：结构描述和视觉表现。结构描述只关心谁连谁，视觉表现由渲染器统一处理。这样带来的直接好处是，你可以用一份数据生成多种风格——彩色版、黑白打印版、深色模式版，甚至导出成 JSON 给前端页面做交互展示。
3.2 布局算法：如何让连线不乱
绘制图最痛苦的不是画节点，而是排位置。手动去摆坐标，二十个节点以内还应付得过来，一旦超过四十个，互相遮挡和连线交叉会把人折磨到崩溃。diagram-design 内置了一套分层布局算法，思路参考了经典分层绘图思想，但做了一些简化处理。
算法分四步。第一步给所有节点分配层级，通常从起始节点开始做广度优先遍历，层级相同的节点放在同一列。第二步在每一层内排序，排序的目标是让相邻层之间边交叉最小化，这里我用了一个简单的贪心策略：反复交换同层相邻节点的位置，如果交换后交叉数减少就保留。第三步根据每层最大节点尺寸计算 x 坐标，根据层数计算 y 坐标。第四步针对同一层内高度不一致的节点做垂直居中对齐，然后统一把坐标对齐到 8pt 网格。
这四步听起来简单，但实际效果却很稳：
def layered_layout(diagram: Diagram, node_gap: float = 48.0, layer_gap: float = 80.0) -> None: # 1. 分配层级（BFS，默认从第一个无入边的节点开始） layers: List[List[str]] = [] in_degree = {nid: 0 for nid in [n.id for n in diagram.nodes]} for e in diagram.edges: in_degree[e.dst] += 1 queue = [n.id for n in diagram.nodes if in_degree[n.id] == 0] visited: set[str] = set() while queue: next_queue = [] layer_nodes = [] for nid in queue: if nid in visited: continue visited.add(nid) layer_nodes.append(nid) if layer_nodes: layers.append(layer_nodes) for e in diagram.edges: if e.src in visited and e.dst not in visited: next_queue.append(e.dst) queue = [nid for nid in next_queue if nid not in visited] # 2. 每层内按原始顺序 + 简单冒泡消交叉 for _ in range(5): # 迭代轮数有限，保证收敛 for li in range(len(layers) - 1): left = {nid: idx for idx, nid in enumerate(layers[li])} edges_between = [(left[e.src], layers[li + 1].index(e.dst)) for e in diagram.edges if e.src in left and e.dst in layers[li + 1]] for i in range(len(layers[li + 1]) - 1): for j in range(i + 1, len(layers[li + 1])): def cross_count(a, b): cnt = 0 for sx, ty in edges_between: for sx2, ty2 in edges_between: if sx == sx2 and ty == ty2: continue if sx < sx2 and ty > ty2: cnt += 1 return cnt before = cross_count(i, j) layers[li + 1][i], layers[li + 1][j] = layers[li + 1][j], layers[li + 1][i] after = cross_count(i, j) if after >= before: layers[li + 1][i], layers[li + 1][j] = layers[li + 1][j], layers[li + 1][i] node_map = {n.id: n for n in diagram.nodes} x_cursor = 0.0 widths = [] for layer in layers: max_w = max(node_map[nid].w for nid in layer) widths.append(max_w) for col_idx, layer in enumerate(layers): max_w = widths[col_idx] if col_idx > 0: x_cursor += layer_gap x_cursor += max_w / 2 y_cursor = 0.0 layer_height = sum(node_map[nid].h for nid in layer) + node_gap * (len(layer) - 1) y_start = -layer_height / 2 for nid in layer: node = node_map[nid] node.y = y_start + y_cursor + node.h / 2 node.x = x_cursor y_cursor += node.h + node_gap x_cursor += max_w / 2这段代码并不复杂，但有一个关键细节值得注意：消交叉时不能只做一次。因为一次遍历只能消除相邻层之间的整体交叉，后面的调整可能又引入新的局部交叉，所以要在外层加上迭代轮数限制。实际使用中五六轮就足够收敛，对几百个节点的图也能在毫秒级完成。
3.3 渲染实现：直接输出 SVG
布局算完坐标之后，渲染就是最后一公里。我选择 SVG 作为主要输出格式，原因有三：它天然适配矢量场景，缩放不糊；它本质上是一段 XML 文本，方便程序生成；它可以直接嵌入 HTML 文档，或者在 GitHub 等代码托管平台直接预览。
渲染逻辑分成三步。第一步是量尺寸，根据节点标题和字体字号计算文本实际宽度，如果文本宽度超过节点宽度则自动换行。第二步是绘制节点，按节点类型填充背景色、描边色、阴影。第三步是绘制连线，根据两个节点的相对方位确定出入口位置，然后生成圆角路径。
def render_svg(diagram: Diagram, output_path: str) -> None: padding = 48.0 min_x = min(n.x - n.w / 2 for n in diagram.nodes) - padding min_y = min(n.y - n.h / 2 for n in diagram.nodes) - padding max_x = max(n.x + n.w / 2 for n in diagram.nodes) + padding max_y = max(n.y + n.h / 2 for n in diagram.nodes) + padding parts = [] parts.append(f'<svg xmlns="http://www.w3.org/2000/svg" ' f'viewBox="{min_x} {min_y} {max_x - min_x} {max_y - min_y}" ' f'width="{max_x - min_x}" height="{max_y - min_y}">') # 背景 parts.append(f'<rect x="{min_x}" y="{min_y}" width="{max_x - min_x}" ' f'height="{max_y - min_y}" fill="#FFFFFF" />') # 连线层优先，让节点压在线条上方 for e in diagram.edges: src = next(n for n in diagram.nodes if n.id == e.src) dst = next(n for n in diagram.nodes if n.id == e.dst) x1, y1 = src.x + src.w / 2, src.y x2, y2 = dst.x - dst.w / 2, dst.y dash = e.edge_type == "dashed" and 'stroke-dasharray="6,4"' or "" color = {"solid": "#94A3B8", "red_solid": "#EF4444", "gray_dashed": "#94A3B8", "dashed": "#94A3B8"}.get(e.edge_type, "#94A3B8") path = f'M {x1:.1f} {y1:.1f} L {(x1 + x2) / 2:.1f} {y1:.1f} ' \ f'L {(x1 + x2) / 2:.1f} {y2:.1f} L {x2:.1f} {y2:.1f}' parts.append(f'<path d="{path}" stroke="{color}" stroke-width="1.5" ' f'fill="none" {dash} />') for n in diagram.nodes: style_map = { "system": ("#2563EB", "#DBEAFE", "#FFFFFF"), "service": ("#FFFFFF", "#CBD5E1", "#1E293B"), "data": ("#F59E0B", "#FEF3C7", "#1E293B"), "external": ("#F8FAFC", "#94A3B8", "#64748B"), "default": ("#FFFFFF", "#CBD5E1", "#1E293B"), } border, fill, text = style_map.get(n.node_type, style_map["default"]) x, y, w, h = n.x, n.y, n.w, n.h parts.append(f'<rect x="{x - w / 2:.1f}" y="{y - h / 2:.1f}" ' f'width="{w:.1f}" height="{h:.1f}" rx="8" ry="8" ' f'fill="{fill}" stroke="{border}" stroke-width="1.5" />') parts.append(f'<text x="{x:.1f}" y="{y + 4:.1f}" text-anchor="middle" ' f'font-size="12" fill="{text}" ' f'font-family="Inter, PingFang SC, Microsoft YaHei, sans-serif">' f'{n.label}</text>') parts.append('</svg>') with open(output_path, "w", encoding="utf-8") as fp: fp.write("\n".join(parts))这段代码是一个最小可行版本，实际项目里我会再补充箭头标记、圆角连接、阴影滤镜等细节。有一点值得强调：SVG 的层叠顺序很重要。正确的顺序是先画连线、再画节点，否则连线会穿过节点的文字区域，视觉上显得非常脏。很多新手写 SVG 图，第一个版本都会犯这个错误。
3.4 实际用法：从结构化描述到一张成品图
为了让这套工具真正可用，我给它设计了一个简单的 JSON 输入格式。使用者不需要关心坐标，只需要描述节点和边。比如画一个最简单的下单链路：
{ "title": "下单主流程", "nodes": [ {"id": "client", "label": "买家App", "type": "external"}, {"id": "gateway", "label": "API网关", "type": "system"}, {"id": "order", "label": "订单中心", "type": "service"}, {"id": "inventory", "label": "库存服务", "type": "service"}, {"id": "db", "label": "订单数据库", "type": "data"} ], "edges": [ {"src": "client", "dst": "gateway", "label": "HTTP"}, {"src": "gateway", "dst": "order", "label": "RPC"}, {"src": "order", "dst": "inventory", "label": "核库存"}, {"src": "order", "dst": "db", "label": "写订单", "edge_type": "dashed"} ] }运行python diagram_design.py schema.json --output order-flow.svg，工具会自动完成布局和渲染。整个过程完全可复现，团队成员拿到的是统一的产物——无论谁执行，生成的图都一样。这一点对于协作的意义怎么强调都不过分：它从机制上消灭了"每个人画出来都不一样"的混乱。
4. 常见问题与排查技巧实录
4.1 问题速查表
用这套方案画了一段图之后，陆陆续续踩了不少坑，也帮一起用这套工具的同学排查了不少问题。我把高频问题整理成了一张速查表，方便你用到的时候直接对照：
| 现象 | 可能原因 | 解决建议 |
|---|---|---|
| 节点文字溢出边框 | 文本宽度没参与节点尺寸计算 | 渲染前先按字体实测宽度，动态扩宽节点 |
| 中文显示成方块 | 渲染环境缺中文字体 | 安装字体，或在font-family中显式声明中文字体 |
| 连线弯折处刺眼 | 用了直角折线 | 改为 8pt 圆角，或使用正交路由 |
| 导出的 PNG 模糊 | 未按devicePixelRatio放大 | 先渲染大尺寸 SVG 再缩放导出 |
| 自动布局后交叉仍然很多 | 贪心消交叉轮数不够 | 增大迭代轮数，或对同层做更精细的排序 |
| 颜色对比度不足看不清 | 文字和背景色太接近 | 按无障碍标准检查，低对比度直接替换色值 |
| 多张图风格不一致 | 样式信息散落在各处 | 把样式抽成统一 Theme 对象，不要写在具体节点上 |
4.2 几个印象深刻的实际案例
第一个案例是字体问题。我在本地跑得好好的图，换了一台服务器做定时任务渲染，导出图片里所有中文都变成了方块。排查到最后发现，问题不是代码逻辑，而是服务器上压根没装中文字体。从那以后，我在部署脚本里强制加了一句字体安装命令，记录在 README 的第一页，因为这个问题实在是太隐蔽了。
第二个案例是布局算法的交叉问题。有个大图总共一百多个节点，算法跑完之后，同一层里有一块区域的连线缠成蜘蛛网。排查下来发现，这些节点之间不是单纯的树状关系，而是存在大量跨层连接。最后我把跨层连线单独拎出来，延迟到最后统一直连，效果立刻好了很多。这也说明没有万能的布局算法，必要时得结合业务场景做调整。
第三个案例是导出图片模糊。原生的 SVG 是无限分辨率，但是为了给文档系统缩略图，我写了一个转换脚本，结果缩略图里的文字糊成一片。解决方案也很简单：先以四倍尺寸渲染 SVG 再缩小到目标尺寸，清晰度立刻达标。现在我的导出代码已经默认带了这个参数，不再依赖使用者手动配置。
5. 从一张图到一个图集
5.1 让图和代码保持同步
diagram-design 的价值不止于单张图，更重要的是它可以融入研发流程。现在我所在的项目组已经规定：涉及接口变更的代码提交，必须同时附带对应时序图的源文件变更。因为图和码同源，评审的时候直接看 diff 就能快速判别改动是否符合设计约束。
实现上很简单，就是给渲染脚本加一个--diff选项，保存图的同时输出一份消息摘要，把节点增删、边变化打印出来。这样在 CI 流程里就可以自动检查"图有没有更新"——如果代码变更影响了接口但图没有跟着改，流水线就会给出告警。这套机制落地之后，文档失效的情况大幅减少，因为"图也会编译失败"。
5.2 批量导出与管理
当图的数量多起来，手工逐张打开导出就变得很痛苦。diagram-design 支持批量模式，传入一个目录，自动识别所有的 JSON 描述文件，全部渲染成 SVG 和 PNG，并且根据title字段生成索引页。索引页本身也是一张图，所有模块图用缩略方块表示，点击可以放大。整个过程无需打开任何图形界面。
实际用下来，这个批量模式最适合两种场景：一种是为季度报告统一准备材料，另一种是为外部协作方打包交付文档。以前整理这些材料要半天，现在一条命令就搞定，而且每张图都严格遵守同一套规范，交付出去的专业度提升非常明显。
6. 最后再分享一点我自己的体会
diagram-design 这套东西，本质上不是某个工具或者某个脚本，而是一种思考方式：把"画图"从个人手艺变成可复用、可审查的工程资产。我在做这个项目的过程中，最大的收获不是写了几千行代码，而是意识到规范的价值从来不在于限制自由，而在于把低级的、重复的决策统一处理，让人能把精力放在真正需要创造力的地方——也就是业务逻辑本身。如果你也在为团队绘图风格不统一而头疼，不妨从一个小场景开始试点，比如只规范一种架构图的样式，跑通之后再逐步扩展。等你坚持到第三四个图种，就会发现团队里再也没有人拿着截图来回问"这张图是什么意思"了。
