画架构图这件事我折腾过好几轮了。最开始用设计软件拖框框画完倒是挺好看但产品需求一变整张图就得重画后来改用纯文本图表工具流程图还行可一到需要精确控制布局的架构图、线框图就抓瞎——坐标不给控制连线全靠猜。直到我认真用起了diagram-design 这一类代码驱动设计工具才觉得终于找到了一条能把绘图和工程化真正揉在一起的路子。简单说这个工具的核心形态是用 Python 代码描述图形元素最终输出 SVG 矢量图。画布、矩形、连线、文字、颜色全部以代码对象的形式组织和呈现你把图当作程序来写改一改变量就能重新渲染一张新图出来。对于要画系统架构图、模块关系图、流程示意、UI 线框图的开发者和技术写作者来说它直接解决了三个长期痛点图与代码版本不同步、手工排版难复用、批量修改费时费力。接下来我会从设计思路、核心 API 拆解到完整实操案例把这一套工作流从头讲透。1. 项目整体思路与设计定位想要真正用好 diagram-design首先要理解它为什么选择代码生成图形这条路。这一步想通了后面写代码的心态和思路都会完全不同。1.1 为什么需要代码驱动设计传统画图工具哪怕是专业级的设计软件本质上都是所见即所得。它的心智模型是我直接用鼠标在画布上摆放元素调整位置、颜色、大小。这个模型对一次性出图很友好但对持续演进的图非常不友好。举个实际例子我给某内部系统画模块架构图第一版是六个模块后来迭代到十一个模块每加一个模块所有相关连线和标注都得手工重排一次。一张图花一上午其中四十分钟都在做对齐网格微调间距这种毫无创造力的机械劳动。代码驱动设计把这个问题彻底翻转了。你在代码里定义的不只是这里有一个矩形而是这里有一个矩形它的横坐标是左边矩形的右边加上 20 像素。当模块数量变化时只需要修改数组长度或循环次数坐标关系会自动重新计算所有元素各归其位。我个人的体会是一旦图的结构和布局逻辑被代码固化下来修改成本会低一个数量级。而且代码本身天然适合放进 Git 仓库做版本管理哪天改出了问题git diff一查就知道哪一行导致图形变化了。用代码画图还有一个隐形好处可参数化。比如我想看三个方案每个方案的模块间距分别是 30、50、80 像素在图形界面里得手动拖三次在代码里就是改一个变量循环生成三张 SVG。这种设计即程序的思路恰恰是很多图形软件的封闭格式永远给不了的。1.2 为什么输出目标是 SVG可能有人会问为什么不直接输出 PNG、JPEG 这种位图格式这里得先明确一点diagram-design 这类工具选择 SVG 作为输出格式是有深层原因的。SVG 是一种基于 XML 的矢量图格式它记录的是图形是什么而不是图形长什么样。同样是一个圆位图保存的是像素点阵放大两倍就模糊SVG 保存的是圆心坐标和半径无论放大到多大尺寸边缘都清晰锐利。最关键的是SVG 可以以纯文本形式写进文件可以被代码处理、被版本管理、被动态修改。这意味着 SVG 可以天然嵌入到网页、Markdown 文档、桌面应用图标体系里而且完全不需要额外的渲染引擎。和位图相比SVG 的文件体积极小。一张复杂一点的架构图PNG 可能要几百 KBSVG 往往几十 KB 就搞定了。另一个隐藏优势是样式化能力你可以修改 SVG 里的fill或stroke属性来改变颜色和描边可以给它加 CSS 动画可以用 JavaScript 操作 DOM 实现交互效果。这些扩展空间是普通位图完全给不了的。如果把画图比作做建筑模型位图像是拍一张照片——好看但不可拆解SVG 则像是交付了一套图纸加材料清单——你想改哪里就改哪里尺寸缩多少都不变形。在实际工程中我往往先把 SVG 作为母版需要位图时再用工具转换输出既保证了质量又兼顾了灵活性。1.3 适用场景与目标读者根据我的实践代码驱动框图设计最适用的场景主要集中在这样几类系统架构图模块多、层次多、连线复杂适合用代码定义布局规则自动生成。流程与状态图特别是需要精确控制位置、不希望自动布局打乱顺序的时候。线框图和原型图不需要精美的视觉表现更看重结构示意和快速迭代。教学示意图与文档插图需要统一风格、可以批量更新。我把这套工作流推荐给所有对精确排版有执念的人。如果你平时写技术文档需要画架构图又希望图能和文档一起走版本管理那它就是非常顺手的工具。即使你现在画的图不多只要你习惯写 Python 代码学习这个工具几乎零成本。它不需要图形编辑器的复杂工具栏只要求你会用字典、列表和函数——这些基础在写任何脚本时都已经用烂了。2. 核心设计模型与关键概念拆解理解 diagram-design 怎么用其实只需要抓住几个核心抽象。它跟设计软件不一样设计软件给你的是画布和一堆工具栏按钮它给你的是几个基础的 Python 对象和一套坐标系规则。下面逐层拆开看。2.1 画布、坐标系与基础元素一切图形都发生在画布上。在代码里画布就是一个带有宽高的虚拟空间。初始化画布时我会先想清楚这张图最终会被用在哪里如果是给文档用的我常用 1200x800如果要贴在网页侧边栏可能就要用 800x600。尺寸对了后面所有坐标计算才不会紧张。坐标系是整个工具的地基。它遵循屏幕绘图惯例原点在画布左上角x 轴向右为正方向y 轴向下为正方向。所有单位都可以理解为 CSS 像素。这一点和数学课上学的笛卡尔坐标系不同——y 轴是向下的初学者第一次写我想把矩形往下移时往往会把 y 坐标写小结果元素跑到了上面。适应它最好的办法就是记住一个类比你是在一张方格纸上作画原点在左上角行号增加方向是往下。只要这个参照系刻在脑子里坐标计算就再也不会错。基础元素分三类分别是形状、线条和文本。形状最常见的自然是矩形和圆它们决定了图的块线条用来表示连接关系通常还会带箭头文本负责给图和线条加标注。在设计软件里这三类元素散落在不同的工具面板中在代码里它们都是对象可以放进同一个列表统一管理。我通常给每个元素起一个清晰的变量名比如module_a_box、arrow_ab这样后续维护时一眼就能看出哪个元素对应图上的哪个部分。2.2 样式系统与配色方案图形好不好看七分靠样式。diagram-design 的样式系统继承了不少 CSS 的思想。核心属性无非是这几类填充色fill、描边色stroke、描边宽度stroke_width、透明度opacity以及文本专用的字号、字体和对齐方式。这些属性都是可选的不设置就使用默认值但对于导出文档里的图我强烈建议显式设置。从经验来看架构图和流程图的配色最忌讳的是花。高饱和的红色、绿色、蓝色堆在一起会严重干扰读者理解关系。我常用的方案是主色一种、辅色一种、警示色一种其余全部用灰色系。比如背景块用淡灰、核心模块用品牌主色、外部依赖用另一辅色、异常分支才用警示色。这样整张图看起来干净信息的层级也一目了然。关于样式还有一个非常实用的做法尽量不要硬编码颜色和字体而是把它们定义成顶部常量。例如COLOR_PRIMARY #2c7fb8 COLOR_BG #f5f5f5 FONT_FAMILY Helvetica, Arial, sans-serif这样改配色方案只需要动一个文件的一个区域所有元素统一变化绝不会出现图上有三个矩形忘改了这种尴尬。我踩过这种坑之后就再也不敢把颜色散着写了。2.3 从拖拽思维切换到计算思维这是很多从图形界面转过来的用户最难适应的一步。在图形界面里你想把模块放在右上角鼠标拖过去就行在代码里你需要问自己右上角到底是多少 x、多少 y我在画图时脑子里始终保持这样几个计算公式水平居中x (画布宽度 - 元素宽度) / 2垂直居中y (画布高度 - 元素高度) / 2左右并排右边元素的 x 左边元素的 x 左边元素的宽度 间距上下堆叠下面元素的 y 上面元素的 y 上面元素的高度 间距这些公式用一个生活化的类比来说就像拼乐高。你不关心每一块积木在最终成品上的绝对位置你只关心它相对于旁边那块积木的偏移量。只要相对关系正确把它放在 1 米还是 2 米的桌面上并不重要。在代码里这种相对关系完全可以定义为变量margin 40 box_width 180 box_height 60 x_start margin y_start margin second_box_x x_start box_width margin我最开始画图时总是忍不住想先把所有元素的绝对坐标画出来结果间距一改全线崩盘。后来改成这种相对计算写法图的可维护性直接上升一个档次。这也是代码画图和手工画图最本质的区别你写的其实不是坐标而是布局逻辑。3. 实操从零搭建一个系统架构图理论说再多不如直接上手画一张图。下面我们用 diagram-design完整走一遍初始化、定义模块、连接关系、导出 SVG的真实流程画的是一张三模块的系统架构示意图。3.1 环境准备与最小工作流环境准备非常简单。需要一个 Python 环境然后安装依赖。安装好后一个最小可用的工作流只有四步创建画布对象指定宽高。用代码添加矩形、文本、线条等元素。调用渲染方法把图形序列化成 SVG 内容。把 SVG 内容写入.svg文件用浏览器打开预览。我把这个流程写成了一个小脚本每次画新图都从这套骨架开始。骨架的意义在于让你少想从哪里开始的问题把注意力集中在图形本身的设计上。等到你画多了完全可以把它封装成自己的工具模块把常用的加圆角矩形加箭头连线都做成函数。3.2 三模块架构图的完整实现下面这段代码是我基于常见实践整理的示例直接改数值就能用于大部分架构图场景from diagram_design import Canvas, Rect, Text, Line, Arrow # ---- 基础配置 ---- canvas_w, canvas_h 1000, 500 box_w, box_h 200, 70 margin_x, margin_y 60, 50 gap 80 # ---- 创建画布 ---- canvas Canvas(widthcanvas_w, heightcanvas_h, background#ffffff) # ---- 定义模块位置相对计算---- positions [] for i in range(3): x margin_x i * (box_w gap) y (canvas_h - box_h) / 2 positions.append((x, y)) # ---- 添加模块矩形与文本 ---- module_names [接入层, 业务层, 数据层] for i, (x, y) in enumerate(positions): box Rect( xx, yy, widthbox_w, heightbox_h, fill#eef4fb, stroke#2c7fb8, stroke_width2, radius8, # 圆角矩形 ) canvas.add(box) label Text( contentmodule_names[i], xx box_w / 2, yy box_h / 2, font_size18, text_aligncenter, vertical_alignmiddle, fill#222222, ) canvas.add(label) # ---- 添加连线与箭头 ---- for i in range(len(positions) - 1): start_x positions[i][0] box_w start_y positions[i][1] box_h / 2 end_x positions[i 1][0] end_y positions[i 1][1] box_h / 2 arrow Arrow( start(start_x, start_y), end(end_x, end_y), stroke#666666, stroke_width2, arrow_size8, ) canvas.add(arrow) # ---- 渲染与导出 ---- svg_content canvas.render() with open(architecture.svg, w, encodingutf-8) as f: f.write(svg_content)这段代码里最值得讲清楚的有三个地方。第一个是相对计算的坐标位置。我没有硬编码三个矩形的坐标而是用循环和公式生成x margin_x i * (box_w gap)。这意味着如果我把gap从 80 改成 30三个矩形会自动靠拢不需要手动逐个修改。真实的 diagram-design 项目里模块多到十几个的时候这种写法几乎是必须的——你不可能手动逐一算坐标。第二个是文本元素的定位。文本的 x 和 y 我设置的是box_w / 2和box_h / 2再配合text_aligncenter和vertical_alignmiddle文本就会精确出现在矩形正中央。这个居中组合拳是画图时最常用的值得单独记一下。第三个是连线的起点终点计算。从左边模块的右边缘中点连到右边模块的左边缘中点。计算公式直观且精准start_x 左模块x 模块宽end_x 右模块x。如果你不想箭头紧贴矩形边框还可以把start_x和end_x各向内收缩几个像素留出呼吸感。3.3 导出、预览与文档嵌入代码跑完后工作目录下会生成一个architecture.svg。此时用浏览器直接打开文件就能看到渲染出来的效果。如果要在网页文档里展示SVG 可以直接内嵌img src./architecture.svg alt系统架构图 /也可以直接把 SVG 标签内容复制粘贴到 HTML 文件里。对于 Markdown 文档绝大多数平台都支持使用图片相对路径引用 SVG 文件。个人经验是文档仓库中单独建一个diagrams/目录统一存放 SVG 源文件。配合脚本自动更新文档里的架构图永远是最新版本。有一点要特别注意当心字体。SVG 里使用的字体如果目标机器上没有安装浏览器会自动替换成默认字体可能造成文字宽度变化甚至换行异常。稳妥的做法是使用跨平台通用的字体列表比如Helvetica, Arial, sans-serif或者将文本转为路径。对于大多数内部文档场景通用字体列表已经足够了。4. 常见问题与排查技巧实录用 diagram-design 画图踩坑是难免的。我把自己经常遇到的问题整理成了一份速查清单每一类都是从实际体验里总结出来的希望对你有用。4.1 坐标偏移与文本溢出症状模块排列不齐文本区域超出矩形边界图形整体不在画布中间。原因大多数时候是坐标系没梳理清楚。比如 y 轴方向记反、忘记把文本高度的因素计入坐标、用了绝对坐标但改了画布尺寸导致布局错位。排查路径先在纸上把目标布局画成方格图标注关键坐标点再去对照代码里计算出的坐标。打印调试也是一个好办法把每个元素的x, y, width, height打印出来逐一核对。文本溢出最常见的原因是对文本宽度的估算是拍脑袋而不是用真实渲染信息。比较稳妥的做法是给文本元素预留足够的水平空间或者根据内容预估宽度后反推盒子尺寸。心得我后来给自己定了一个小规矩所有布局计算都用一个layout()函数集中完成不在各个元素定义处散落魔法数字。这样一旦出现问题只需检查这一个函数即可。4.2 SVG 在不同环境下的显示差异症状同一张 SVG在浏览器里显示正常在文档预览插件里模糊或错位Retina 屏上图片发虚嵌入某些应用时多出透明边距。原因不同宿主环境对 SVG 的缩放策略不一样。浏览器按 CSS 像素渲染文档预览插件可能按物理像素渲染Retina 屏又需要两倍分辨率而某些应用还会对 SVG 的宽度高度属性做二次处理。排查路径先确认 SVG 根元素是否显式设置了width和height。如果没设置部分环境会按照默认尺寸渲染导致失真。检查viewBox是否与画布尺寸一致如果viewBox小于画布宽高浏览器会自动放大图形清晰度一般没问题但如果viewBox包含的区域外还有元素那些元素会被裁剪掉。还要留意文字是否被转换成路径某些环境不加载外部字体文本会以系统默认字体代替导致排版效果完全不同。心得如果目标使用场景包含文档系统我建议生成一张 SVG 后在目标系统里实际预览一遍再继续画下一张。等批量画图后才发现字体渲染问题返工成本非常高。4.3 复杂图形的维护与迭代症状图越画越复杂代码越来越乱改一个参数导致无关模块联动错位。原因典型的面条式代码问题。所有元素没有分层、没有分组位置计算被散落在各处修改一个尺寸常量时依赖链条上的任何一环出错都会引发连锁反应。排查路径把代码重构为配置 构建 渲染三层结构。将尺寸、颜色、间距集中到配置区构建层用函数组织比如build_header()、build_module_box()、build_arrow()渲染层只负责最终输出。这样每一步的逻辑清晰出问题时也能快速定位。心得超过五个模块之后我开始强制使用生成循环而不是逐个手写。比如模块名称列表化之后用一个for循环生成所有模块新增和删除都只改列表即可。手写十个模块的代码是不酷的但用循环生成十个模块的代码是省力的。4.4 常见问题速查表问题现象可能原因快速解法元素位置不符合预期坐标计算错误或坐标系理解偏差打印坐标对照纸稿逐项核对文本溢出矩形文本宽度估算不足或字号过大给文本预留空间或先测量再设定盒子宽度导出图片模糊环境按位图缩放 SVG 时拉大确保设置了合适宽高必要时转换高分辨率 PDF/PNG字体显示不一致目标环境缺少字体使用通用字体栈或转为路径修改常量后布局崩坏布局中存在散落的硬编码坐标重构代码统一走layout()函数箭头没有贴合模块边缘起点终点坐标计算忽略了线宽/箭头大小显式计算矩形边缘坐标并预留箭头长度这张表是我每次排查问题的第一手索引。实际上很多问题都可以通过前两行解决——坐标计算正确图就成功了一半。5. 从图形到系统几个扩展思路当你能熟练地通过代码生成一张精美的 SVG 架构图之后你就站在了一个更大的可能性边缘上。最直接的扩展是批量生成。假设你是某个技术团队里负责画架构图的人每次迭代都要更新一版架构图。如果把图定义成代码再加上自动化脚本每次发布前只需要跑一条命令就能基于最新配置生成新的 SVG 并自动替换文档中的引用。我把这套流程接到一个小脚本里后再也不用手动导出、重传、替换了。第二个扩展方向是参数化探索。有了图即代码的基础你可以把布局参数、配色方案、是否显示某些模块全部做成配置项。想看看极简风格是什么效果换一套配色常量生成一张新图对比后再决定。这在图形界面工具里需要来回切换多个文件在代码世界里就是一个函数调用。我通常会为每个方案生成独立的 SVG 文件按时间或版本号命名方便回看演进过程。第三个方向是与网页深度整合。SVG 本质上就是网页元素你可以用 JavaScript 给它增加交互点击某个模块显示详细说明、缩放和平移、动态高亮某条链路。如果你正在做技术产品的官网或内部运维可视化页面这几乎是最低成本的图表动起来方案。我尝试过给架构图加上简单的 hover 高亮效果整个过程比我想象中更顺手因为 SVG 的元素结构完全由代码控制加事件监听就像操作普通 HTML 元素一样自然。不过我也要说句实话代码驱动图形并不是万能的。如果一张图追求的是手绘温度、艺术表现力或者非常复杂的自由排版那图形设计软件仍然是更合适的工具。diagram-design 解决的是结构清楚、关系复杂、需要持续维护的工程图场景。拿它来做数据可视化仪表板是拿错了锤子拿它来画平时随手一涂的示意图又有点大材小用。关键是明确你的场景。在我个人实际用过多次之后最深的体会是代码画图最大的价值不是省力而是让图进入了工程体系。它跟代码一样可以被审查、被重构、被版本化可以像软件一样持续演进。如果你平时一直被文档里的架构图又过期了这个问题困扰我强烈建议你用这个思路把自己的图表体系重构一遍。第一次写布局计算时可能比拖鼠标慢十分钟但改第三次、第四次的时候你就知道这十分钟花得太值了。