1. diagram-design从“画图”到“设计图”的转变diagram-design 是我最近在团队文档体系里专门负责的一类工作——把散落在需求文档、口头沟通和技术方案里的信息整理成一套结构清晰、视觉一致、可长期维护的图表。很多人觉得画图不就是拖几个框、连几条线的事但真到用的时候才发现问题一大堆流程图箭头指向混乱架构图层级不清看的人五分钟都找不到核心链路。diagram-design 这个项目要解决的恰恰就是“一张图能不能在十秒内被看懂”这件事。这个项目适合三类人参考一是经常写技术方案、要给上下游讲清楚设计的工程师二是做产品规划、需要把复杂规则画成业务逻辑的产品经理三是想把文档里的插图从“随手画”升级成“规范化组件”的技术写作人员。说白了只要你的工作里离不开图这套思路就能用得上。我最早也是“打开画板就开画”的类型后来迭代了几轮才发现真正稳定的图表产出靠的不是手感和灵感而是一套可复用的设计规则先定图型、再分层、后定视觉参数最后落到工具和脚本里。这篇文章就把我从 diagram-design 这个项目里沉淀出来的完整思路、参数规范和踩坑记录摊开来写尽量做到你看完就能直接套用。2. 图型选型先别拿鼠标先想清楚画什么2.1 常见图型的适用场景很多图之所以难看不是因为线条画得不直而是压根选错了图型。比如有人把系统模块关系画成一张思维导图中心一个节点、四周全是子节点这种图表达上下层关系还行但表达模块间的数据流向就非常别扭。我在项目里先把高频场景做了归类整理成下面这份选型清单图型适用场景不适用场景典型例子架构图展示系统分层、模块归属表达时序变化后端服务分层、前后端依赖流程图表达步骤、分支、异常处理表达复杂网状依赖登录流程、工单审批流程时序图展示跨对象交互顺序表达静态归属下单接口调用链、第三方回调实体关系图ER图建模数据表之间的关联表达业务活动顺序用户、订单、商品模型状态图表达对象状态流转表达并发分支订单状态、任务状态思维导图头脑风暴、结构拆解表达严格依赖关系需求拆解、知识梳理这张表我贴在工位旁边很久了每次动手前都会对着它问自己一句“我要表达的核心关系到底是什么”如果是“谁包含谁”优先看架构图如果是“先做什么、再做什么”优先看流程图如果是“数据表之间怎么关联”老老实实用 ER 图。选对了图型整张图的信息传达效率就成功了一半。2.2 图型选型的三个判断维度光靠场景表还不够我在实际项目中慢慢发现选型其实可以拆成三个更底层的维度组合起来判断会更稳。第一个维度是“信息的核心关系”。任何一张图都可以被抽象成三种关系之一层级关系包含/归属、流程关系先后/条件、网状关系双向/多对多。如果是混合关系不要硬塞进一张图里宁可拆成主图和子图后面维护也会轻松很多。我见过太多人想一张图画尽天下事最后每个关系都没讲清楚。第二个维度是“看图人的使用习惯”。如果是给开发同事对着做接口设计时序图远比思维导图好沟通如果是给业务方同步一个决策路径流程图比架构图更直观。看图人决定了信息的粒度也决定了你能不能省掉那一堆“众所周知”的细节。第三个维度是“变更频率”。我通常在选型时会额外问一句这张图多久会变一次如果每周都要跟着需求改尽量选文本化、可 diff 的表达方式比如声明式脚本生成的图如果一年都动不了几次手工绘制完全够用。我自己在 diagram-design 项目里定了条规矩带“数据关系”属性的图一律走脚本生成从源头规避改图时找不到原文件的尴尬。3. 信息分层与视觉参数让图经得起细看3.1 信息三层结构主视觉层、辅助层、注释层选好图型之后进入最容易被忽略的一步——信息分层。我一开始画图总是把所有信息堆在一起框里塞满文字每个框都要加个红框强调结果整张图看起来像打翻了的调色盘。后来在 diagram-design 的规范里我把一张图的信息拆成三层来组织主视觉层是图的骨架包括最核心的实体框、关键箭头和主导航路径。这一层的目标是人眼第一扫就能看到“从哪开始、到哪结束”。以一张订单流程图为例主视觉层就是“创建订单 → 支付 → 发货 → 完成”这条线其他东西都得给这条线让路。辅助层负责补齐主链路附近的重要分支和异常路径比如“支付超时”“库存不足”这些情况。这一层的视觉权重必须明显低于主链路常用做法是弱化描边颜色、降低图标饱和度必要时用虚线框归类。注释层放的是补充说明、数据指标、版本信息和来源备注。这一层要么沉到图底要么统一放到一个角标里绝不能和主视觉元素抢注意力。我见过不少团队把注释文字直接堆在主干线旁边导致图还没讲完观众的眼神已经飞了。这里有一个我在项目里反复用的判断标准把图拿给一个完全不了解业务的人看十秒钟后让他回答“这个图在讲什么”如果答不出来说明主视觉层没有做干净。3.2 色彩、字体、线条与网格的参数建议视觉参数是我在 diagram-design 里迭代最久的部分下面这组参数是我们目前比较稳定的默认方案你可以直接抄去用也可以作为底线再衍生出自己的调性。色彩方面我建议一张图里同时出现的颜色不超过四种并且每种颜色都要有明确的语义。比如蓝色表示“系统模块”、绿色表示“正常业务路径”、橙色表示“待确认或中间态”、红色表示“异常或阻断”。背景色一律用浅灰或纯白不用渐变。给实体加填充色时饱和度不要超过 70%否则打印出来或投到会议大屏上都会显得特别脏。字体方面中文字体优先使用无衬线体英文字体保持同一家族。标题字号 14 到 16正文 12注释 10 到 11层级之间至少差 2px。框内文字尽量控制在 10 个字以内一条线路上不要堆超过五个框如果超过就说明粒度太粗需要再加一层子图。线条与箭头是很多人不重视的细节其实是整张图的“语法”。我在规范里统一约定实线表示确定关系虚线表示条件或未来关系箭头指向数据流方向线宽默认 1.5px最短路径上的主干线可以用 2.5px。连接线禁止出现斜穿过实体框的情况尽量走正交折线也就是横平竖直的连线方式这样视觉上会清爽非常多。网格与留白是最后的收尾。所有实体框都对齐到同一套网格坐标系常见的网格间距我用 8px 或 12px。框之间至少保留 24px 的间距分组之间至少 48px。没有网格意识的图看起来总有一种说不出为什么的“歪”一旦对齐专业感立刻上来。4. 从手绘到可维护工具选型与脚本化生成4.1 工具全景对比图型选型和视觉规范定下来之后就该讨论用什么工具落地了。我在 diagram-design 项目里对比过四类方案各有各的适用场景直接列成表供你参考。工具类型上手门槛协作体验可维护性适用场景在线协作白板类极低多人实时同步较差画完难复用快速讨论、评审手稿桌面流程图软件低靠文件流转中等模板丰富低频插图、对外汇报声明式脚本绘图中等天然适配代码评审高文本可 diff架构图、数据关系图编程绘制库较高依赖脚本仓库高可动态生成批量产出、数据驱动图你会发现我最终把重心放在了“声明式脚本绘图”和“编程绘制库”这两类上原因是 diagram-design 项目里的图表大多需要跟随代码迭代。手工画一张图很快但三个月后改需求时找不到源文件、或者找到了但不知道改哪个图层这些隐性成本远比当初画图的半小时高得多。4.2 用声明式脚本维护架构图我先把最常用的架构图实现方式演示一遍。这一套用文本描述结构自动排版布局不依赖手工拖拽非常稳。digraph system_arch { rankdirTB; node [shapebox, stylerounded, filled, fillcolor#E8F0FE, color#5B7DB1, fontnameHelvetica, fontsize12, margin0.25,0.15]; edge [color#666666, arrowsize0.8, fontnameHelvetica, fontsize10]; subgraph cluster_frontend { label前端层; stylerounded, dashed; color#B0BEC5; web [labelWeb端, fillcolor#D9E8FF]; mini [label小程序, fillcolor#D9E8FF]; } subgraph cluster_biz { label业务层; stylerounded, dashed; color#B0BEC5; order [label订单服务, fillcolor#FFFFFF]; pay [label支付服务, fillcolor#FFFFFF]; } subgraph cluster_data { label数据层; stylerounded, dashed; color#B0BEC5; db [labelMySQL, shapecylinder, fillcolor#FDECEA]; cache [labelRedis, shapecylinder, fillcolor#FDECEA]; } web - order [label下单]; mini - order [label下单]; order - pay [label发起支付]; pay - db [label落库]; order - cache [label缓存状态]; }把这段文本保存成文件后用对应的命令行工具导出成 PNG 或 SVG整个过程不需要手动对齐任何一个节点。它的好处很具体一是改图时只改文本不会遇到图形软件里“找不到原始文件”的问题二是团队成员可以直接在代码评审里对这份图提意见线怎么连、节点叫什么全都在文本里清清楚楚三是可以用脚本批量生成多张版本图比如灰度环境一套、生产环境一套数据源是同一份定义。4.3 用编程绘制库生成数据驱动图表如果图表的数据本身是动态的比如每天要根据接口监控数据画一张调用频次图那就需要进入编程绘制库的范畴。我在项目里比较常用 Python 生态里的绘图库核心逻辑只有三步准备数据、设置样式、渲染输出。import pandas as pd import matplotlib.pyplot as plt plt.rcParams[font.family] [sans-serif] plt.rcParams[axes.unicode_minus] False # 准备数据接口名 调用次数 df pd.DataFrame({ 接口: [/cart/add, /order/pay, /user/login, /product/detail], 调用次数: [1200, 430, 980, 2100] }) # 设置样式与视觉规范保持一致 fig, ax plt.subplots(figsize(8, 4.5)) bars ax.bar(df[接口], df[调用次数], color#5B7DB1, width0.6) ax.set_title(核心接口调用热度, fontsize14) ax.set_ylabel(调用次数, fontsize11) ax.set_ylim(0, 2500) ax.spines[[top, right]].set_visible(False) # 高亮超过阈值的接口 threshold 1000 for bar, count in zip(bars, df[调用次数]): if count threshold: bar.set_color(#D96C6C) plt.tight_layout() plt.savefig(api_heatmap.png, dpi200)这份脚本看起来简单但里面已经内置了我在前面定的视觉规范颜色不超过两种、去掉了顶部和右侧的边框线、用了非衬线字体。输出结果不是那种“默认模板味”的图而是直接符合团队文档规范的数据图。这个方式的最大价值是以后数据一变重新跑一次脚本就能得到最新版图表不用再手工改数。4.4 我整理出的单人实操流程结合上面的工具经验我把自己每次做图的实际流程写成了一份清单大概五步第一步写图题。不动手画先在一句话里说清楚“这张图要表达什么关系”。这一步能筛掉一半思路不清就开始拖框的冲动。第二步画主干。用白板或草稿纸只画主视觉层的实体和连线不考虑配色和精确对齐。这个阶段的目标是把“骨架”立起来。第三步列分支。把异常分支、辅助节点和注释信息整理成清单标出哪些属于辅助层、哪些属于注释层。如果分支数量超过主干数量的一半就考虑拆子图。第四步套样式。回到脚本或绘图软件按照色彩、字体、线条、网格的规范开始正式制作优先保证主链路突出。第五步做检查。导出图片后我习惯把它缩到 50% 再放大到 100% 各看一遍。缩小时看整体结构是否平衡放大时看文字有没有出框、箭头有没有压线。这份流程看起来平平无奇但每一条都是从多次返工里换来的。我尤其推荐你试试第一步只写一句话描述图的目标。很多图改来改去最后发现根本不是画法的问题而是制图人自己都没想清楚要表达什么。5. 常见问题与排查技巧5.1 高频问题汇总在推行 diagram-design 规范的过程中团队里反馈最多的问题集中在下面几个我整理了一张排查速查表你可以对照着自检。现象可能原因解决思路图看起来“很乱”颜色过多 / 线条交叉 / 框未对齐色彩降为三种以内连线改正交折线启用网格吸附重点不突出所有元素视觉权重相同给主干线加粗平行分支降低饱和度注释沉底改了需求但找不到图图形文件是二进制格式没有源文件和版本切换成声明式脚本文本入库文字到处出框框边长宽比不合适 / 字号过大框内字数限 10 字超出就拆节点或修改措辞图太密、信息过载单张图承载了多种关系按关系类型拆图用子图维护细节评审时没人看缺少开场白和图题加一个简明标题并在正文里写清楚“读图顺序”这里我最想强调的就是“评审时没人看”这一条。技术评审会上一张没有图题、没有读图顺序的图扔上去观众挣扎几秒就放弃理解了。后来我在每张图的标题下面强制加一行小字说明比如“从下往上看先看数据层再向上看”效果立竿见影。5.2 针对脚本化绘图的排查笔记如果你也切到了声明式脚本或编程绘制库这条路上还会遇到一些文本绘图特有的问题。我把常踩的坑单独拎出来讲一下。第一个坑是乱码。脚本绘图里最经典的翻车现场就是中文标签全部变成了方块。原因基本都出在字体配置上系统没有找到你指定的中文字体文件。解决方法是显式指定一个系统存在的字体路径不要写完字体名就以为万事大吉。验证办法也简单命令行里先查一下字体是否存在再跑绘图脚本。第二个坑是布局溢出。声明式脚本绘图虽然自动排版但长文本节点偶尔会把图撑得非常宽。我的处理方法是给节点设置固定宽度并通过换行标签强制折行尽量避免一个框里堆二十个字的场景。第三个坑是版本兼容。升级绘图库版本之后之前的脚本偶尔会出现行为变化比如默认配色变了、边框样式不再生效。为了减少这类问题我习惯在项目里锁定绘图库的版本号把依赖写死。第四个坑是批量生成时样式不统一。如果脚本里散落着很多魔法数字比如颜色值到处写后期调起来会非常痛苦。我的习惯是把所有样式常量提取到一个单独的文件里用一个统一的配置对象去管理颜色、字号、线宽。5.3 复盘改进把每一张图当成一次小型设计评审diagram-design 做到现在我最大的体会是画图不是一个一次性交付而是一个持续收敛的过程。每次图被退回或者被指出“看不懂”我都会在复盘记录里写三件事第一是图型选错了还是分层没做干净第二有没有重复出现同类问题第三这次能不能沉淀出一条新的参数规则或检查项。比如我最初并没有“注释层”这个概念后来连续两次都被指“图上信息太杂”才意识到需要把注释统一压到底部。又比如“主干线加粗”这个规则也是因为评审时有人直接在会上说了一句“我不知道该看哪条线”才被正式写进规范。这些规则看似微小但累积起来就是一套团队能共同使用、新人三小时就能上手的图表设计语言。这里再分享一个我个人的小技巧每次正式发图前把图发给一个不在项目里的同事只问一个问题——“你看懂了什么”。对方复述出来的内容往往能一针见血地指出主视觉层到底有没有做对。这比我自己对着屏幕反复检查十分钟都管用。最后说说这套方法还能往哪走。diagram-design 目前主要覆盖了技术文档里的架构图、流程图和时序图但同样的思路完全可以平移去做产品说明书里的操作指引图、汇报材料的逻辑图、甚至是知识库的索引图。只要抓住“先定图型、再分层、后定参数”这条主线很多时候你会发现文档质量提升不一定需要写更多字把图画清楚就够了。