画架构图这件事，我折腾过好几轮了。最开始用设计软件拖框框，画完倒是挺好看，但产品需求一变，整张图就得重画；后来改用纯文本图表工具，流程图还行，可一到需要精确控制布局的架构图、线框图就抓瞎——坐标不给控制，连线全靠猜。直到我认真用起了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 可能要几百 KB，SVG 往往几十 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(width=canvas_w, height=canvas_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( x=x, y=y, width=box_w, height=box_h, fill="#eef4fb", stroke="#2c7fb8", stroke_width=2, radius=8, # 圆角矩形 ) canvas.add(box) label = Text( content=module_names[i], x=x + box_w / 2, y=y + box_h / 2, font_size=18, text_align="center", vertical_align="middle", 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_width=2, arrow_size=8, ) canvas.add(arrow) # ---- 渲染与导出 ---- svg_content = canvas.render() with open("architecture.svg", "w", encoding="utf-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_align="center"和vertical_align="middle"，文本就会精确出现在矩形正中央。这个"居中"组合拳是画图时最常用的，值得单独记一下。
第三个是连线的起点终点计算。从左边模块的右边缘中点，连到右边模块的左边缘中点。计算公式直观且精准：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 解决的是"结构清楚、关系复杂、需要持续维护"的工程图场景。拿它来做数据可视化仪表板，是拿错了锤子；拿它来画平时随手一涂的示意图，又有点大材小用。关键是明确你的场景。
在我个人实际用过多次之后，最深的体会是：代码画图最大的价值不是省力，而是让图进入了工程体系。它跟代码一样可以被审查、被重构、被版本化，可以像软件一样持续演进。如果你平时一直被"文档里的架构图又过期了"这个问题困扰，我强烈建议你用这个思路把自己的图表体系重构一遍。第一次写布局计算时可能比拖鼠标慢十分钟，但改第三次、第四次的时候，你就知道这十分钟花得太值了。
