深夜同事往协作群里丢了一张调用关系图用来解释某个故障排查路径。单独看每个节点都讲得通但整张图铺开后线头从四个方向同时冲出来我盯着看了半分钟才勉强找到主线。这种场景在很多技术团队里太常见了画图时很爽评审时大家点头两周后回头再看已经没人敢改因为动一个方块可能牵出七八条不明不白的连线。我后来在项目里做了一套叫 diagram-design 的图表设计规范初衷特别朴素解决“图能看懂但长期看不懂”的普遍问题。它不是教你把图画得好看而是教你把图当成持续沟通的载体。任何画架构图、流程图、时序图、数据汇报图的人都会从这套思路里获得一套可落地的约束什么信息进图、什么信息留在正文、节点怎么分组、连线怎么排向、颜色负责表达什么。这篇文章就是我把 diagram-design 从零搭起来、又真实落地在团队文档体系里的全过程复盘既有底层原理也有可以直接抄走的检查清单。1. 为什么技术团队最终都需要一套diagram-design体系1.1 从“能看懂”到“长期看懂”的差距团队里大部分技术文章都配有图但这些图的质量波动极大。有人画图习惯好会用容器分组、统一箭头方向有人画图纯粹是“鼠标走到哪点到哪”节点随意摆放连线绕得密密麻麻。最麻烦的是这类图不是个例而是常态。大家默认“图嘛能看懂就行”于是图的生命周期就断在了发布那一刻。能看懂和长期看懂之间隔着一道坎第一眼把握主流程第二眼定位重点区域第三眼理解异常分支。普通随手图能过第一眼往往撑不过第二眼和第三眼。diagram-design 要解决的正是这个迭代问题。我给自己立过一个标准如果一张图发布三天后还需要原作者指着某个区域解释含义那这张图的设计就是失败的。带着这个标准去看图很多问题就暴露了。一张微服务架构图里同时放了类名、接口名、容器编号、数据库分片键读者在一个节点上被迫判断四五次这种图再详细也算不上好图。精于宽选的图表设计首先是在做减法让每个视觉元素都承担明确的沟通任务。1.2 图表也是一种代码资产很多团队对代码有一套完整的分层、命名、评审和重构流程但对文档里的图表完全放任。这在工程上是不合理的。图表和代码一样在表达复杂关系而且往往被更多人阅读它应该被当作一种可视化代码资产来运营。我把 diagram-design 当成代码规范来推进图有版本图有评审入口图有可解释的语义规则。需求调整时大家讨论的不再是“这个箭头怎么画”而是“这个箭头表示的调用是否还存在”。一旦讨论焦点从绘画技巧挪到业务语义图的质量自然就上去了。把图表当代码资产还有一个直接的收益图可以被复用和扩展。一个系统架构图拆成运行链路视图、数据流向视图、部署拓扑视图三个版本后每个视图能独立演进而不是所有信息挤在一张总览图里慢慢腐烂。diagram-design 的核心思想就是说清楚这个一张图只完成一种沟通任务多任务拆成多张图再通过统一的设计语言让多张图保持“同一家人”的视觉特征。2. 拆解diagram-design的五个底层设计变量任何图表无论简单还是复杂最后都可以拆成五个决定性的变量信息架构、形状与边界、颜色体系、连线与方向、字号与注释。这五个变量也就是我每次评审图时的固定切入点。2.1 信息架构先决定这张图想替读者做几次判断动手画图前我先问自己一句话读者看到这张图最快应该得到什么如果答案是“异常请求走到哪一步被拒绝”图里就不该出现完整的数据表结构如果答案是“哪条调用链路延迟指标最高”延迟数字就应该直接标在线或节点上而不是藏在正文里。信息架构说白了就是取舍。烂图的通病不是画错而是什么都想画。一个节点上同时挂着类名、接口名、IP地址、缓存键再配三条入边两条出边读者在没有导航的情况下基本只能放弃阅读。我给自己设置过一条可操作的阈值单张图的主节点数量控制在七加减二的认知带宽内超过二十个节点必须拆图或用容器分组。分组是信息架构最重要的手段。把同层角色包进一个大圆角矩形里整个容器就成为一个判断单元读者先判断容器之间的边界关系再进入容器内部看细节决策成本骤然降低。2.2 形状与边界矩形、圆角、容器背后的语义约定diagram-design 对形状有严格约定矩形代表实体或处理单元圆角矩形代表交互端点或外部系统菱形只留给决策判断圆柱体代表存储六边形代表适配器或转换过程。说实话一开始团队里有人觉得这套规定很死板但它的价值在于让视觉轮廓先于文字被读取。读者扫一眼边框形状不用逐字读标签就能判断“这是外部接口还是内部逻辑”。容器层级同样需要统一最外层容器表示系统边界第二层表示子系统或模块第三层表示部署单元。每一层容器的边框厚度和背景色深浅按层次递减避免外层抢走内部内容的风头。这里有一个我踩过的小坑容器圆角半径要跟随层级。外层用大圆角内层用小圆角视觉次序感才明显全图统一四像素圆角分层效果会弱到几乎没有。2.3 颜色体系不超过四种强调色的使用纪律黑白灰是默认信息层彩色全部留给强调这是 diagram-design 最基本的颜色纪律。很多人一画图就本能地给每个模块涂一个颜色成品就是一张彩虹图。问题是人眼对彩色的敏感度太高颜色一多读者会以为每个颜色都有业务含义结果发现只是随机装饰认知就被干扰了。我采用“背景灰阶层加语义色强调”的方案节点边框默认灰色主体默认浅灰到白渐变整张图只允许出现四种语义色——红色表示异常或故障链路蓝色表示外部依赖绿色表示成功路径或新增能力橙色表示待处理事项或风险。如果一张图需要第五种强调色说明它塞了太多需要同时表达的事情应该拆图。读者看到红色不需要看图例就能猜到是异常分支看到绿色自然知道是成功路径。颜色成了语言的一部分这才是它该有的作用。2.4 连线与方向正交、弯曲、交叉时的可读性控制连线是图表里最容易翻车也最容易被忽视的变量。diagram-design 对连线有一个硬性偏好优先使用正交折线夹角统一为九十度避免斜线和任意转角因为人眼追踪正交线的成本最低。两个节点之间的连线只表达一种关系需要标注协议、端口、数据量时写在线的中点上而不是散落在线的旁边。流向一致性同样重要。流程图按上到下、左到右的主方向推进架构图强调数据从上往下依赖从下往上时序图以时间轴为唯一方向。任何回路都必须绕过主干区从外侧空间回流不能直接穿回中间。两条线实在绕不开就在交叉处画一个小半圆弧跨越而不是十字穿过。这些习惯看似琐碎组合起来的效果是让读者能沿着视觉流一路走下去。2.5 字号与注释在屏幕和打印场景下平衡可读性字号是最容易被忽略、也最影响观感的变量。diagram-design 规定主标签字号不小于14px二级注释不小于12px大标题可以到18到20px整张图缩放到50%后关键信息仍然不需要放大镜就能读出来。很多原画布里字很清楚的图一插进文档页就被缩成一条细线就是因为没做缩放下沉测试。注释的写法也有讲究用名词短语不要写完整句子每条注释不超过十五个字同一个节点最多挂一条补充说明更多信息一律放进图下方的图例或正文段落。图例本身也要分主次核心图例放在右上角辅助说明放在底部。还有一个小技巧把最终画布尺寸固定成16比9或4比3这样无论插文档、投屏幕还是导图片都不会产生字被拉伸的副作用。3. 主流图表类型的差异化设计规则通用变量管住所有图但具体到流程图、架构图、时序图、数据图表、思维导图每家又各有各的脾气必须单独补定义。3.1 流程类图表状态转换图的单入口约束流程图和状态图最怕“从中间看懂”。diagram-design 要求任何流程类图必须画出入口节点和出口节点入口节点使用独立样式标出让第一次读图的人能找到起跳点。分支判断的分叉点尽量靠下或靠右因为人的阅读习惯是往下踩分叉方向要和阅读主方向一致。循环结构是重灾区。很多图喜欢把循环画成一根回线绕过大半个图面插回原点导致视觉混乱。我的做法是画一个“回到第N步”的标记既保住循环语义又保持图面干净。状态转换图则严格控制状态数量主状态不超过七个辅助状态不超过三个转换事件写在边上。如果某个事件说明超过三行就把它拆成子图。不少状态机图是程序自动导出的节点多且乱。这种图我一般建议改成“关键状态路径图加异常状态清单”两张图表达的信息一点不少读图的成本却低一大截。3.2 架构类图表分层与依赖方向的一致性架构图的本质是一个城市的街区规划先有路网和分区再谈建筑外形。diagram-design 对架构图的要求是层先于模块方向先于连接。先画出网关层、应用层、数据层、基础设施层四个横向泳道再把具体模块填进泳道依赖线只能向下跨层依赖必须画成带箭头的跳跃线并在图里注明原因。模块之间的连接不要画成总线式的握手大杂烩。我见过一张十六个节点的微服务图每两个节点都拉了一条线整张图几乎看不到留白。这种图必须用“分组加聚合连接线”重画把同类调用聚成一条粗链路链路上用数字标注调用次数或占用带宽节点上不展开细节。另一个高频问题是对部署视图和逻辑视图的混淆。IP地址、容器名出现在逻辑架构图里读者会误以为这个服务是单机部署其实它可能是三个实例。diagram-design 会强制把部署信息从逻辑视图里剥离出去两类信息各画各的图。3.3 时序类图表生命线与消息排序的横轴逻辑时序图的特别之处在于它用二维位置同时表达“谁参与”和“什么先发生”所以横轴顺序绝不是随意排的。diagram-design 对时序图定了三条规矩生命线按交互顺序从左到右排列不按模块权重复排序消息从上到下严格按时间排序同一条消息不允许斜线穿过另一条创建和销毁生命线的符号只用于描述生命周期管理不做装饰。垂直线上实体线和虚线也有严格语义实线表示同步调用返回用虚线异步消息用半箭头。这些语义在普通流程图里可能无所谓但在时序图里就是读者理解行为的钥匙。早期我画时序图喜欢把所有异常分支都塞进去结果主流程被淹没。后来改成“主成功路径用最粗线宽异常路径统一用暗红色细线收拢到一个泳道”整张图的可读性立刻提升。3.4 数据可视化图表坐标轴起点与数据墨水比例diagram-design 也覆盖数据可视化图表比如指标趋势图、占比图、明细对比图。它们的坑不在节点关系而在比例误导。我坚持几个原则柱状图和折线图的坐标轴从0开始除非有特殊原因坐标轴刻度要保证数据段可比不要用截断轴放大微小差异饼图扇区不超过五个更多类别一律改成横向条形图。还有一个重要概念叫“数据墨水比例”数据墨水指图表里真正表达数据信息的部分网格线、背景、装饰阴影都是非数据墨水。非数据墨水能少就少尽量去掉表格之外的多余边框、渐变和三维效果。三维饼图看起来酷炫但它让人无法精确比较面积是被第一个禁用的样式。读者要看的是数值关系不是渲染效果。3.5 思维导图与白板草图自由布局中的锚点设定思维导图和白板草图的自由度最高diagram-design 只做最小干预。中心主题放中心偏左上用最粗边框和最重字号定义所有一级分支以中心为圆心放射出去二级以下树枝状展开。颜色上每条一级分支占用一种强调色同一分支内不允许换色。自由布局不代表没有锚点。每个分支至少给一个关键词定位让读者在浏览时能快速回位。白板草图最重要的一条规则其实在画完之后“尽早转正”。手画线条天然乱适合讨论不适合长期保存。所以我的习惯是讨论结束的半小时内把白板照片整理成一张干净的架构图并追加版本日期如果一周内这张图又被修改就说明之前的讨论还没有足够收敛。白板是草稿纸不是终稿存放地。4. 一次真实的diagram-design改造复盘从“随笔画图”到统一规范4.1 现状盘点混乱的图恰恰是混乱的沟通之前有一个项目文档里累计了几十张图类型横跨流程图、架构图、时序图、统计图。我逐一盘点后发现三种典型病症同一种含义完全用了不同画法例如“用户身份校验失败”在一个图里是红色节点在另一个图里是黄色警告圈同一个系统实体在不同文档里叫法不统一有的叫“账户中心”有的叫“账号服务”跨图检索形同虚设还有一批图直接从白板拍照上传倾斜、模糊、没有版本根本谈不上复用。我先把所有图按沟通任务分类再统计每一类出现的视觉样式。整理出一张对照表后发现同样表示“外部系统”的节点存在四五种边框样式同样表示“异步消息”的连线存在三种箭头。混乱不是某个人不认真而是缺少一套所有人共同承认的语法。diagram-design 要建立的就是这套语法。4.2 制定规则用三张示例图立住全部约定方案讨论了很久最后还是放弃了写一本四十页设计规范文档的念头因为那种文档几乎不会有人读完。我换了一种做法只定三条根规则再用三张示例图把规则具象化。第一张是三层架构图示范容器、层次、方向对应关系第二张是跨系统调用时序图演示同步、异步、返回的约定第三张是业务流程图展示判断节点和异常分支的画法。这三张图本身就是规范的一部分后续所有新图都对照示例图评审。为了可执行我把规则压缩成一张A4记忆卡只保留五项内容形状语义表、四种语义色、连接线方向规则、字号规则、图例位置。这五项是评审时的“语法检查项”先过语法再谈内容准确性。这个做法比描述性文档好用得多因为绘图者能一边看图一边对照规则是从图里长出来的不是从文字里背出来的。4.3 落地工具把规范固化到绘图模板与代码驱动绘图脚本中规范不落地到工具就只是挂在文档站里的愿望。我把 diagram-design 固化成了几套绘图模板架构图模板、流程时序图模板、数据图表模板所有模板都内置统一字体、统一色板、统一线宽和统一图例容器。新图画图时直接从模板新建基本不会跑偏。对于经常出现的外部系统、存储节点、消息队列这类元素我定义成了可复用图形组件拖进来就能用。项目里还有不少图是用代码生成方式实现的例如把服务调用链自动转成图形。我把规范里的形状、颜色、线型封装成一组样式函数脚本生成的每个节点和连线都调用这些函数保证自动图和手工图长得像同一家人。这一步很关键自动图如果直接用默认样式会和手工图严重割裂接入规范后脚本一次生成十张图也能保持统一视觉语言。对团队来说这才是规范真正进入生产环境的表现。4.4 评审迭代让设计过检像代码评审一样有清单改造后第一次评审大家面对新模板有些不适唯恐自己图画得不对。我制定了四步评审流程先查语法用后文的自检清单再查信息完整性看每个节点是否都有上下文对应接着查读者视角请一位没有参与该模块的同学看图三十秒后复述核心信息最后查变更记录确认图名、日期、修改点都已登记。前几次评审确实有人抱怨“画个图还要走流程”但门禁跑通后优势立刻显现。最明显的变化在后续迭代以前改图是局部重画现在改图只需要在模板里替换组件连线自动保持正交和间距。新人不到一周就能画出合规的架构图因为他们不用自己发明形状含义和配色逻辑。同时要明确一点规范不是冻结的。每季度重新审视一次如果某种视觉形式在评审中反复被误解就直接改规则并同步更新模板。规范和代码一样需要版本管理。5. 可以马上抄走的diagram-design自检清单与避坑经验这一部分给所有想在项目里落地类似规范的同学可以直接复制成团队评审清单。5.1 发布前按层级过这八项我把图表发布前的检查做成八个提问从上到下逐项过任务聚焦这张图只回答一个问题吗如果要回答两个先拆图。节点边界节点数量是否在可读范围超过二十个是否已有分组容器形状语义每个形状是否遵守语义表有没有用矩形硬画判断、用菱形表达存储方向一致主干流程是否沿约定方向推进回流是否绕开核心区域配色纪律强调色是否保持在四种以内每个彩色是否都有明确语义而非装饰文字可读缩放到文档大小后字号是否可读注释是不是完整句子能否压成短语图例完备图中自创的缩写、图标、线型是否都写进图例图例位置是否统一版本信息图名、所属模块、日期、修改人是否完整是否存进了正确的文档目录这八项不需要全部精通只要发布前照着走一遍成图水平就会超过绝大多数随手画的版本。我自己每次发布前会花两三分钟做一次检查偶尔图省事跳过结果通常要花更多时间在沟通群里解释图意得不偿失。5.2 我踩过且不想你再踩的几个坑第一个坑是过度信任图例。有张图用了六种虚线和四种箭头类型我天真地以为图例写清楚就可以了结果读者还是频繁看错。后来把线型砍到三种实线表示调用长虚线表示异步短虚线表示返回。表达精度没有下降多少认知负担却明显降低。能用形状差异表达就不要只依赖线型差异线宽在截图压缩后很容易消失。第二个坑是没有给特殊形态留出可定位的视觉锚点。有些图为了避免杂乱把容器间距全部均分看起来整齐读者却找不到哪里是重点。diagram-design 允许重点模块用轻微阴影或更粗边框强调但每张图最多三处。如果重点超过三处问题通常不是图形设计而是这张图本身承载了过量信息必须拆开。第三个坑也最隐蔽为了规范而规范。有一阵我执着于让所有图都符合统一尺寸和间距甚至把不同语义的图强行拼成一张总览图。结果图确实漂亮阅读成本反而更高。规范的目的永远是降低认知摩擦而不是制造流程仪式感。如果某个场景真的需要更自由的处理完全可以申请特例只要在图例里注明例外原因。5.3 从单图规范到跨文档体系的延伸diagram-design 最后会在文档层面越滚越大因为图表很少孤立存在它前后的正文、图号、章节标题、引用方式都是体系的一部分。我在项目里追加了三条约定图必须被正文至少引用一次孤儿图一律删除图号与文档目录保持一致子图编号用父图编号加后缀多个文档引用同一张图时只保留一个权威版本绝不复制粘贴成两份。这三条能从源头上解决文档体系最常见的“两处图版本不一致”问题。我的实际体会是最难的从来不是定规则而是让每个参与者形成“图也有设计”的意识。代码写乱了可以靠重构挽回图画乱了却很少有人有动力返工所以只能在入口卡质量。如果团队节奏允许建议把图表评审直接绑定到真实需求设计会上专门留出十五分钟看架构图这比事后补一堆规范文档有效得多。现在回看项目里那些换了新规范的图我已经不需要再配大段解释文字这可能就是我想要的结果。每次遇到复杂的调用关系我都会先提醒自己先退一步想想读者要判断什么再去动鼠标。方向对了图自然就走得顺。
深夜同事往协作群里丢了一张调用关系图用来解释某个故障排查路径。单独看每个节点都讲得通但整张图铺开后线头从四个方向同时冲出来我盯着看了半分钟才勉强找到主线。这种场景在很多技术团队里太常见了画图时很爽评审时大家点头两周后回头再看已经没人敢改因为动一个方块可能牵出七八条不明不白的连线。我后来在项目里做了一套叫 diagram-design 的图表设计规范初衷特别朴素解决“图能看懂但长期看不懂”的普遍问题。它不是教你把图画得好看而是教你把图当成持续沟通的载体。任何画架构图、流程图、时序图、数据汇报图的人都会从这套思路里获得一套可落地的约束什么信息进图、什么信息留在正文、节点怎么分组、连线怎么排向、颜色负责表达什么。这篇文章就是我把 diagram-design 从零搭起来、又真实落地在团队文档体系里的全过程复盘既有底层原理也有可以直接抄走的检查清单。1. 为什么技术团队最终都需要一套diagram-design体系1.1 从“能看懂”到“长期看懂”的差距团队里大部分技术文章都配有图但这些图的质量波动极大。有人画图习惯好会用容器分组、统一箭头方向有人画图纯粹是“鼠标走到哪点到哪”节点随意摆放连线绕得密密麻麻。最麻烦的是这类图不是个例而是常态。大家默认“图嘛能看懂就行”于是图的生命周期就断在了发布那一刻。能看懂和长期看懂之间隔着一道坎第一眼把握主流程第二眼定位重点区域第三眼理解异常分支。普通随手图能过第一眼往往撑不过第二眼和第三眼。diagram-design 要解决的正是这个迭代问题。我给自己立过一个标准如果一张图发布三天后还需要原作者指着某个区域解释含义那这张图的设计就是失败的。带着这个标准去看图很多问题就暴露了。一张微服务架构图里同时放了类名、接口名、容器编号、数据库分片键读者在一个节点上被迫判断四五次这种图再详细也算不上好图。精于宽选的图表设计首先是在做减法让每个视觉元素都承担明确的沟通任务。1.2 图表也是一种代码资产很多团队对代码有一套完整的分层、命名、评审和重构流程但对文档里的图表完全放任。这在工程上是不合理的。图表和代码一样在表达复杂关系而且往往被更多人阅读它应该被当作一种可视化代码资产来运营。我把 diagram-design 当成代码规范来推进图有版本图有评审入口图有可解释的语义规则。需求调整时大家讨论的不再是“这个箭头怎么画”而是“这个箭头表示的调用是否还存在”。一旦讨论焦点从绘画技巧挪到业务语义图的质量自然就上去了。把图表当代码资产还有一个直接的收益图可以被复用和扩展。一个系统架构图拆成运行链路视图、数据流向视图、部署拓扑视图三个版本后每个视图能独立演进而不是所有信息挤在一张总览图里慢慢腐烂。diagram-design 的核心思想就是说清楚这个一张图只完成一种沟通任务多任务拆成多张图再通过统一的设计语言让多张图保持“同一家人”的视觉特征。2. 拆解diagram-design的五个底层设计变量任何图表无论简单还是复杂最后都可以拆成五个决定性的变量信息架构、形状与边界、颜色体系、连线与方向、字号与注释。这五个变量也就是我每次评审图时的固定切入点。2.1 信息架构先决定这张图想替读者做几次判断动手画图前我先问自己一句话读者看到这张图最快应该得到什么如果答案是“异常请求走到哪一步被拒绝”图里就不该出现完整的数据表结构如果答案是“哪条调用链路延迟指标最高”延迟数字就应该直接标在线或节点上而不是藏在正文里。信息架构说白了就是取舍。烂图的通病不是画错而是什么都想画。一个节点上同时挂着类名、接口名、IP地址、缓存键再配三条入边两条出边读者在没有导航的情况下基本只能放弃阅读。我给自己设置过一条可操作的阈值单张图的主节点数量控制在七加减二的认知带宽内超过二十个节点必须拆图或用容器分组。分组是信息架构最重要的手段。把同层角色包进一个大圆角矩形里整个容器就成为一个判断单元读者先判断容器之间的边界关系再进入容器内部看细节决策成本骤然降低。2.2 形状与边界矩形、圆角、容器背后的语义约定diagram-design 对形状有严格约定矩形代表实体或处理单元圆角矩形代表交互端点或外部系统菱形只留给决策判断圆柱体代表存储六边形代表适配器或转换过程。说实话一开始团队里有人觉得这套规定很死板但它的价值在于让视觉轮廓先于文字被读取。读者扫一眼边框形状不用逐字读标签就能判断“这是外部接口还是内部逻辑”。容器层级同样需要统一最外层容器表示系统边界第二层表示子系统或模块第三层表示部署单元。每一层容器的边框厚度和背景色深浅按层次递减避免外层抢走内部内容的风头。这里有一个我踩过的小坑容器圆角半径要跟随层级。外层用大圆角内层用小圆角视觉次序感才明显全图统一四像素圆角分层效果会弱到几乎没有。2.3 颜色体系不超过四种强调色的使用纪律黑白灰是默认信息层彩色全部留给强调这是 diagram-design 最基本的颜色纪律。很多人一画图就本能地给每个模块涂一个颜色成品就是一张彩虹图。问题是人眼对彩色的敏感度太高颜色一多读者会以为每个颜色都有业务含义结果发现只是随机装饰认知就被干扰了。我采用“背景灰阶层加语义色强调”的方案节点边框默认灰色主体默认浅灰到白渐变整张图只允许出现四种语义色——红色表示异常或故障链路蓝色表示外部依赖绿色表示成功路径或新增能力橙色表示待处理事项或风险。如果一张图需要第五种强调色说明它塞了太多需要同时表达的事情应该拆图。读者看到红色不需要看图例就能猜到是异常分支看到绿色自然知道是成功路径。颜色成了语言的一部分这才是它该有的作用。2.4 连线与方向正交、弯曲、交叉时的可读性控制连线是图表里最容易翻车也最容易被忽视的变量。diagram-design 对连线有一个硬性偏好优先使用正交折线夹角统一为九十度避免斜线和任意转角因为人眼追踪正交线的成本最低。两个节点之间的连线只表达一种关系需要标注协议、端口、数据量时写在线的中点上而不是散落在线的旁边。流向一致性同样重要。流程图按上到下、左到右的主方向推进架构图强调数据从上往下依赖从下往上时序图以时间轴为唯一方向。任何回路都必须绕过主干区从外侧空间回流不能直接穿回中间。两条线实在绕不开就在交叉处画一个小半圆弧跨越而不是十字穿过。这些习惯看似琐碎组合起来的效果是让读者能沿着视觉流一路走下去。2.5 字号与注释在屏幕和打印场景下平衡可读性字号是最容易被忽略、也最影响观感的变量。diagram-design 规定主标签字号不小于14px二级注释不小于12px大标题可以到18到20px整张图缩放到50%后关键信息仍然不需要放大镜就能读出来。很多原画布里字很清楚的图一插进文档页就被缩成一条细线就是因为没做缩放下沉测试。注释的写法也有讲究用名词短语不要写完整句子每条注释不超过十五个字同一个节点最多挂一条补充说明更多信息一律放进图下方的图例或正文段落。图例本身也要分主次核心图例放在右上角辅助说明放在底部。还有一个小技巧把最终画布尺寸固定成16比9或4比3这样无论插文档、投屏幕还是导图片都不会产生字被拉伸的副作用。3. 主流图表类型的差异化设计规则通用变量管住所有图但具体到流程图、架构图、时序图、数据图表、思维导图每家又各有各的脾气必须单独补定义。3.1 流程类图表状态转换图的单入口约束流程图和状态图最怕“从中间看懂”。diagram-design 要求任何流程类图必须画出入口节点和出口节点入口节点使用独立样式标出让第一次读图的人能找到起跳点。分支判断的分叉点尽量靠下或靠右因为人的阅读习惯是往下踩分叉方向要和阅读主方向一致。循环结构是重灾区。很多图喜欢把循环画成一根回线绕过大半个图面插回原点导致视觉混乱。我的做法是画一个“回到第N步”的标记既保住循环语义又保持图面干净。状态转换图则严格控制状态数量主状态不超过七个辅助状态不超过三个转换事件写在边上。如果某个事件说明超过三行就把它拆成子图。不少状态机图是程序自动导出的节点多且乱。这种图我一般建议改成“关键状态路径图加异常状态清单”两张图表达的信息一点不少读图的成本却低一大截。3.2 架构类图表分层与依赖方向的一致性架构图的本质是一个城市的街区规划先有路网和分区再谈建筑外形。diagram-design 对架构图的要求是层先于模块方向先于连接。先画出网关层、应用层、数据层、基础设施层四个横向泳道再把具体模块填进泳道依赖线只能向下跨层依赖必须画成带箭头的跳跃线并在图里注明原因。模块之间的连接不要画成总线式的握手大杂烩。我见过一张十六个节点的微服务图每两个节点都拉了一条线整张图几乎看不到留白。这种图必须用“分组加聚合连接线”重画把同类调用聚成一条粗链路链路上用数字标注调用次数或占用带宽节点上不展开细节。另一个高频问题是对部署视图和逻辑视图的混淆。IP地址、容器名出现在逻辑架构图里读者会误以为这个服务是单机部署其实它可能是三个实例。diagram-design 会强制把部署信息从逻辑视图里剥离出去两类信息各画各的图。3.3 时序类图表生命线与消息排序的横轴逻辑时序图的特别之处在于它用二维位置同时表达“谁参与”和“什么先发生”所以横轴顺序绝不是随意排的。diagram-design 对时序图定了三条规矩生命线按交互顺序从左到右排列不按模块权重复排序消息从上到下严格按时间排序同一条消息不允许斜线穿过另一条创建和销毁生命线的符号只用于描述生命周期管理不做装饰。垂直线上实体线和虚线也有严格语义实线表示同步调用返回用虚线异步消息用半箭头。这些语义在普通流程图里可能无所谓但在时序图里就是读者理解行为的钥匙。早期我画时序图喜欢把所有异常分支都塞进去结果主流程被淹没。后来改成“主成功路径用最粗线宽异常路径统一用暗红色细线收拢到一个泳道”整张图的可读性立刻提升。3.4 数据可视化图表坐标轴起点与数据墨水比例diagram-design 也覆盖数据可视化图表比如指标趋势图、占比图、明细对比图。它们的坑不在节点关系而在比例误导。我坚持几个原则柱状图和折线图的坐标轴从0开始除非有特殊原因坐标轴刻度要保证数据段可比不要用截断轴放大微小差异饼图扇区不超过五个更多类别一律改成横向条形图。还有一个重要概念叫“数据墨水比例”数据墨水指图表里真正表达数据信息的部分网格线、背景、装饰阴影都是非数据墨水。非数据墨水能少就少尽量去掉表格之外的多余边框、渐变和三维效果。三维饼图看起来酷炫但它让人无法精确比较面积是被第一个禁用的样式。读者要看的是数值关系不是渲染效果。3.5 思维导图与白板草图自由布局中的锚点设定思维导图和白板草图的自由度最高diagram-design 只做最小干预。中心主题放中心偏左上用最粗边框和最重字号定义所有一级分支以中心为圆心放射出去二级以下树枝状展开。颜色上每条一级分支占用一种强调色同一分支内不允许换色。自由布局不代表没有锚点。每个分支至少给一个关键词定位让读者在浏览时能快速回位。白板草图最重要的一条规则其实在画完之后“尽早转正”。手画线条天然乱适合讨论不适合长期保存。所以我的习惯是讨论结束的半小时内把白板照片整理成一张干净的架构图并追加版本日期如果一周内这张图又被修改就说明之前的讨论还没有足够收敛。白板是草稿纸不是终稿存放地。4. 一次真实的diagram-design改造复盘从“随笔画图”到统一规范4.1 现状盘点混乱的图恰恰是混乱的沟通之前有一个项目文档里累计了几十张图类型横跨流程图、架构图、时序图、统计图。我逐一盘点后发现三种典型病症同一种含义完全用了不同画法例如“用户身份校验失败”在一个图里是红色节点在另一个图里是黄色警告圈同一个系统实体在不同文档里叫法不统一有的叫“账户中心”有的叫“账号服务”跨图检索形同虚设还有一批图直接从白板拍照上传倾斜、模糊、没有版本根本谈不上复用。我先把所有图按沟通任务分类再统计每一类出现的视觉样式。整理出一张对照表后发现同样表示“外部系统”的节点存在四五种边框样式同样表示“异步消息”的连线存在三种箭头。混乱不是某个人不认真而是缺少一套所有人共同承认的语法。diagram-design 要建立的就是这套语法。4.2 制定规则用三张示例图立住全部约定方案讨论了很久最后还是放弃了写一本四十页设计规范文档的念头因为那种文档几乎不会有人读完。我换了一种做法只定三条根规则再用三张示例图把规则具象化。第一张是三层架构图示范容器、层次、方向对应关系第二张是跨系统调用时序图演示同步、异步、返回的约定第三张是业务流程图展示判断节点和异常分支的画法。这三张图本身就是规范的一部分后续所有新图都对照示例图评审。为了可执行我把规则压缩成一张A4记忆卡只保留五项内容形状语义表、四种语义色、连接线方向规则、字号规则、图例位置。这五项是评审时的“语法检查项”先过语法再谈内容准确性。这个做法比描述性文档好用得多因为绘图者能一边看图一边对照规则是从图里长出来的不是从文字里背出来的。4.3 落地工具把规范固化到绘图模板与代码驱动绘图脚本中规范不落地到工具就只是挂在文档站里的愿望。我把 diagram-design 固化成了几套绘图模板架构图模板、流程时序图模板、数据图表模板所有模板都内置统一字体、统一色板、统一线宽和统一图例容器。新图画图时直接从模板新建基本不会跑偏。对于经常出现的外部系统、存储节点、消息队列这类元素我定义成了可复用图形组件拖进来就能用。项目里还有不少图是用代码生成方式实现的例如把服务调用链自动转成图形。我把规范里的形状、颜色、线型封装成一组样式函数脚本生成的每个节点和连线都调用这些函数保证自动图和手工图长得像同一家人。这一步很关键自动图如果直接用默认样式会和手工图严重割裂接入规范后脚本一次生成十张图也能保持统一视觉语言。对团队来说这才是规范真正进入生产环境的表现。4.4 评审迭代让设计过检像代码评审一样有清单改造后第一次评审大家面对新模板有些不适唯恐自己图画得不对。我制定了四步评审流程先查语法用后文的自检清单再查信息完整性看每个节点是否都有上下文对应接着查读者视角请一位没有参与该模块的同学看图三十秒后复述核心信息最后查变更记录确认图名、日期、修改点都已登记。前几次评审确实有人抱怨“画个图还要走流程”但门禁跑通后优势立刻显现。最明显的变化在后续迭代以前改图是局部重画现在改图只需要在模板里替换组件连线自动保持正交和间距。新人不到一周就能画出合规的架构图因为他们不用自己发明形状含义和配色逻辑。同时要明确一点规范不是冻结的。每季度重新审视一次如果某种视觉形式在评审中反复被误解就直接改规则并同步更新模板。规范和代码一样需要版本管理。5. 可以马上抄走的diagram-design自检清单与避坑经验这一部分给所有想在项目里落地类似规范的同学可以直接复制成团队评审清单。5.1 发布前按层级过这八项我把图表发布前的检查做成八个提问从上到下逐项过任务聚焦这张图只回答一个问题吗如果要回答两个先拆图。节点边界节点数量是否在可读范围超过二十个是否已有分组容器形状语义每个形状是否遵守语义表有没有用矩形硬画判断、用菱形表达存储方向一致主干流程是否沿约定方向推进回流是否绕开核心区域配色纪律强调色是否保持在四种以内每个彩色是否都有明确语义而非装饰文字可读缩放到文档大小后字号是否可读注释是不是完整句子能否压成短语图例完备图中自创的缩写、图标、线型是否都写进图例图例位置是否统一版本信息图名、所属模块、日期、修改人是否完整是否存进了正确的文档目录这八项不需要全部精通只要发布前照着走一遍成图水平就会超过绝大多数随手画的版本。我自己每次发布前会花两三分钟做一次检查偶尔图省事跳过结果通常要花更多时间在沟通群里解释图意得不偿失。5.2 我踩过且不想你再踩的几个坑第一个坑是过度信任图例。有张图用了六种虚线和四种箭头类型我天真地以为图例写清楚就可以了结果读者还是频繁看错。后来把线型砍到三种实线表示调用长虚线表示异步短虚线表示返回。表达精度没有下降多少认知负担却明显降低。能用形状差异表达就不要只依赖线型差异线宽在截图压缩后很容易消失。第二个坑是没有给特殊形态留出可定位的视觉锚点。有些图为了避免杂乱把容器间距全部均分看起来整齐读者却找不到哪里是重点。diagram-design 允许重点模块用轻微阴影或更粗边框强调但每张图最多三处。如果重点超过三处问题通常不是图形设计而是这张图本身承载了过量信息必须拆开。第三个坑也最隐蔽为了规范而规范。有一阵我执着于让所有图都符合统一尺寸和间距甚至把不同语义的图强行拼成一张总览图。结果图确实漂亮阅读成本反而更高。规范的目的永远是降低认知摩擦而不是制造流程仪式感。如果某个场景真的需要更自由的处理完全可以申请特例只要在图例里注明例外原因。5.3 从单图规范到跨文档体系的延伸diagram-design 最后会在文档层面越滚越大因为图表很少孤立存在它前后的正文、图号、章节标题、引用方式都是体系的一部分。我在项目里追加了三条约定图必须被正文至少引用一次孤儿图一律删除图号与文档目录保持一致子图编号用父图编号加后缀多个文档引用同一张图时只保留一个权威版本绝不复制粘贴成两份。这三条能从源头上解决文档体系最常见的“两处图版本不一致”问题。我的实际体会是最难的从来不是定规则而是让每个参与者形成“图也有设计”的意识。代码写乱了可以靠重构挽回图画乱了却很少有人有动力返工所以只能在入口卡质量。如果团队节奏允许建议把图表评审直接绑定到真实需求设计会上专门留出十五分钟看架构图这比事后补一堆规范文档有效得多。现在回看项目里那些换了新规范的图我已经不需要再配大段解释文字这可能就是我想要的结果。每次遇到复杂的调用关系我都会先提醒自己先退一步想想读者要判断什么再去动鼠标。方向对了图自然就走得顺。
平方复杂度无法被常规优化消除｜TaoToken 统一 Key 通道实测)
