今年年初我们团队做了个在内部争论过一阵子的决定把用了好几年的 Astah 全部卸掉画图这件事统一改走 draw.io同时把 AI、Markdown、Mermaid 串成一条完整的协同设计闭环。起因很朴素——一次架构评审会上需求文档里的流程图、设计文档里的时序图、代码注释里的状态说明各说各话改一处要动三处Astah 的许可证费用、Windows 绑定、二进制工程文件又让同步成本雪上加霜。这篇文章不聊虚的就把我们这一年怎么把这条链路跑起来、draw.io 凭什么能替代 Astah 撑住 UML 建模的日常、以及中间踩过哪些坑完整讲一遍。适合正在用 Astah 或其他商业建模工具、又想把图纳入 Git 和 Markdown 流水线的团队参考。1. 告别 Astah 的决策复盘从 License 约束到文档割裂1.1 原来用 Astah 画图的两大痛点成本与合规是我先碰到的墙。Astah Professional 按年订阅按人头收费团队一扩就是不小的开销公司正版化审计越来越严新增席位要走采购流程经常等一两周才能下来。更尴尬的是有的同事只是偶尔打开看张老图也得占一个许可证这种支出很难向管理层解释清楚。文件格式则是更深的问题。Astah 的工程文件是私有二进制格式放到 Git 里既不能 diff也没法自动合并。几个人协同时图的最新版本经常躺在某个人电脑上谁改没改完全不知道。开完评审会只能导出 PNG 发到群里图上的修改意见谁落实、怎么落实全凭自觉过两周再回头对账就成了一笔糊涂账。第三点是场景局限。Astah 的强项是 UML但现代研发要画的图有很大一块根本不是 UML——系统架构图、云资源拓扑、业务泳道、上线流程。拿 Astah 画这些东西非常别扭默认样式又特别“工程”想放进方案 PPT 还得二次美化。图一旦脱离工具、变成静态图片和文档、代码之间的同步就是灾难这也是我们最终决定换掉它的根本原因。1.2 draw.io 为什么能顶上先给结论draw.io 在 95% 的日常场景里能替代 Astah剩下 5% 的 UML 高级语义和逆向工程可以用脚本和流程补上。draw.io 免费开源文件是.drawio的 XML 纯文本天然适合 Git 管理。这一点直接解决了“图的最新版在谁电脑上”的顽疾。它支持在线、桌面、VS Code 三种使用方式离线也能画。形状库方面UML 的类、用例、时序、活动、状态、部署一应俱全AWS、GCP、Azure 等云厂商图标也内置画架构图比以前顺手得多。更关键的是它的文本互转能力。draw.io 内置从 Mermaid、PlantUML 导入的功能也支持 CSV 表格批量生成图形导出方面除了 PNG还能导出带源信息的 SVG。这意味着图可以“从文本生成”也可以“以文本形式存放”为后面整条自动化流水线铺好了路。维度Astahdraw.io许可证成本按年订阅按人收费免费开源文件格式.asta私有二进制.drawioXML 文本Git diff / 合并基本不行文本可 diff、可合并UML 图形能力专业语义约束严格形状库齐全风格自由架构图 / 云图简陋很强云厂商图标内置嵌入 Markdown需要导出图片直接引用 SVGMermaid / PlantUML不支持原生导入逆向工程内置 Java/C 等靠脚本和 CI 取代需要说明的是替代不是零成本。Astah 对 UML 语义的约束很严格比如关联方向、多重性、泛化关系画错了它会拦你draw.io 不强约束画错了没人管。所以我们的做法是在流程上把关用 Mermaid 草稿承载逻辑用 draw.io 做呈现再用评审检查清单兜底。这个闭环后面会详细展开。2. 闭环的四大件AI 会话、Markdown 源、Mermaid 草稿、draw.io 定稿2.1 四个角色怎么分工闭环的顺序可以写成一句话需求输入 → AI 会话结构化→ Markdown承载→ Mermaid 草稿逻辑快照→ 评审 → draw.io 定稿 → 导出 SVG → 嵌回 Markdown → 归档进 Git → 回喂给 AI。四个角色各干一件事AI 负责把模糊变成清楚Markdown 负责让内容可管理Mermaid 负责让逻辑可快速验证draw.io 负责让成品可发布。缺了任何一个环节闭环都有裂缝——纯 Mermaid 的图进不了正式文档纯 draw.io 的图回不到代码评审没有 AI 的话需求到图之间的铺路工作全得靠人肉整理。一开始我们也想过两个工具行不行试了几天就放弃了因为每个人在开会时需要的图和交付文档时需要的图根本不是一个东西。2.2 AI 在闭环里具体干什么活AI 不是用来“一键出图”的。我们的用法是把 AI 当成一个不停留在口头上的结构化助手。第一个场景是需求消化。会议录音或 PRD 原文扔给模型让它提取“参与者、系统边界、关键交互”输出成列表。这个列表直接作为 Markdown 文档的“需求要点”章节省去自己整理的时间。第二个场景是生成 Mermaid 草稿。我们沉淀了一个固定提示词模板你是一个资深架构师。阅读下面的需求描述提取参与者、系统边界和关键交互用sequenceDiagram语法输出时序图草稿。不要解释直接给代码块。模型返回的代码基本就是A-B: 发送请求这种语义行我们复制到 Markdown 草稿区再在评审会上讨论。要强调一点AI 生成的图“逻辑可行但布局很丑”特别是有环形依赖和分支合并的时候画出来乱成一团。这没关系草稿本来就是给逻辑看的布局交给 draw.io 处理。第三个场景是评审检查单。改动图之后让 AI 按“模块职责是否重叠、边界条件是否覆盖、消息往返是否成对、是否存在死循环”生成检查项。这个检查单跟着 PR 走比口头评审可追溯得多。第四个用法很实用把 draw.io 导出的 SVG 里内嵌的 XML 片段交给 AI让它还原成 Mermaid 文本用来和上一版做逻辑 diff。图在文档里是 SVG在评审里是文本这个身份切换全靠 AI 搭桥没有 AI 之前我们根本做不到。2.3 Markdown 作为唯一事实源的管线我们仓库里固定了一套目录结构docs/ 00-index.md design/ order-center.md diagrams/ src/*.drawio export/*.svg约定非常严格文档正文里只允许写禁止出现“最终版v3.png”这种东西。图的源文件在diagrams/src发布产物在diagrams/export谁改源文件谁负责重新导出 SVG。这个流程看起来多了一步但换来的是所有人都知道去哪里找最新图。Markdown 作为事实源还有一个红利是发布渠道多GitLab 和 GitHub 直接渲染PR diff 里能看到文字和 Mermaid 草稿的改动需要交付 Word 时用 pandoc 转换企业微信、钉钉这类机器人通知也能直接发 Markdown 消息。系统告警、周报、技术方案都能从同一份源文件生成这是 Astah 时代想都不敢想的。2.4 Mermaid 草稿转 draw.io 定稿的策略具体操作步骤我们踩了不少次才固定下来在 Markdown 草稿区写完 Mermaid 代码逻辑评审通过。打开 draw.io用Arrange Insert Advanced Mermaid菜单把代码贴进去。draw.io 生成基础图元后先做结构和语义检查别急着调样式。统一字体、颜色、对齐全选后用Arrange Align和Arrange Distribute需要分组的用容器外套 swimlane。保存到diagrams/src文件名和文档保持一致。导出 SVGFile Export as SVG务必勾选 “Include a copy of my diagram”。回到 Markdown 里引用 SVG 路径。这里有几个关键细节。第一draw.io 的 Mermaid 导入不支持全部语法节点级样式、主题配置在导入时会被忽略所以草稿期不要在每个节点上写样式保持简单结构。第二导入后文本宽度计算经常出问题中文容易被截断要手动开启 Word Wrap。第三导出 SVG 的 “Include a copy” 选项很多人不注意勾选之后 SVG 文件里内嵌了完整的 draw.io XML别人直接用 draw.io 打开这个 SVG 就能继续编辑等于一份文件同时是“发布图”和“源文件”这个技巧强烈推荐。3. 从 Mermaid 到 draw.io 的迁移不是二选一是各干各的3.1 什么时候用 Mermaid什么时候用 draw.io很多人刚接触这个组合时会问既然 draw.io 都能画为什么还要写 Mermaid我们实际用下来有一条判断标准关键看图的用途和复杂度。场景推荐原因会议速写、PR 描述、Issue 评论Mermaid快、文本、GitHub 直接渲染正式架构文档、方案 PPTdraw.io布局可控、样式专业类图、大量关系连线draw.ioMermaid 的类图布局容易乱时序图、轻量流程MermaidsequenceDiagram语法最顺手状态机、状态迁移Mermaid 草稿 draw.io 定稿逻辑用文本、样式用画布云架构、拓扑图draw.io内置云厂商图标库原则就一句话频道里说几句就能讲清的小图用 Mermaid要进文档和 PPT 的图用 draw.io。开会时随手画的东西没必要进 draw.io 精修硬把每张图都做成“作品”反而是负担。反过来正式文档里的图也别偷懒只丢一行 Mermaid渲染出来节点重叠、线交叉评审体验很差。3.2 同一套图的“双层维护”技巧我们最终固定下来的做法是“一套图两层表达”。逻辑版是 Markdown 里的 Mermaid 草稿参与评审、被 AI 检查、被 Git diff发布版是diagrams/src里的 draw.io 文件导出 SVG 后进正式文档。有人会问这不是维护两份吗我们的经验是分情况小图只保留一层要么全 Mermaid 要么全 draw.io大图才上双层。而且 AI 可以做半自动同步——把 draw.io 的 XML 丢给模型还原成 Mermaid 文本人工核对差异反过来把更新后的 Mermaid 再导入 draw.io 调整布局。真正需要人工投入的只是布局调整不是逻辑重画。另一个反直觉的经验是越是大图越要维护“文本逻辑层”。因为我们发现纯 draw.io 图的 PR 很难评论——评论只能贴在图片上位置漂移严重而 Mermaid 草稿是文本可以在 diff 里精确引用某一行逻辑。所以正式评审我们永远看三层 diffMarkdown 正文、Mermaid 草稿、导出后的 SVG 预览。这个习惯一开始被认为很麻烦坚持半年后所有人都真香了。3.3 表格驱动的图元映射这一块其实是上一篇状态机经验的延伸。我们用 Markdown 表格维护状态迁移、接口调用、角色权限这类结构化事实表格列就是状态, 事件, 目标状态, 备注。然后让脚本或 AI 把表格转成 Mermaid 文本再进 draw.io 定稿。表格驱动最大的好处是图和事实永远同步。改需求时只改表格图重新生成不会出现“文档里的图早就过时了”的情况。而且表格状态下逻辑错误一眼就能看出来——比如某个状态没有任何事件能进入在画布上你要顺着连线找半天在表格里扫一眼就发现了。我们管这个叫“把图的问题降维成表的问题”本质上是在利用 Markdown 的表格生态而不是在画图工具里死磕。4. 用 draw.io 全面替代 Astah 的实操细节4.1 替代类图、用例图、时序图的建模方式类图方面draw.io 左侧搜索 UML选 ClassUML形状它有标准的类名、属性、方法三个分区。继承、聚合、组合分别有对应的关系线。一个小技巧是属性方法文本开启 HTML 格式可以在名字上做加粗方法名和返回值用不同颜色比 Astah 默认样式更悦目。Mermaid 草稿导入后类之间的关系会变成普通直线需要手工改成带空心箭头的泛化线。用例图Actor 形状就是标准小人用例用椭圆系统边界用一个透明矩形容器。draw.io 的容器可以把多个用例框在一起视觉上比 Astah 的 System Boundary 更灵活颜色可按模块区分。几个用例跨系统时泳道容器一嵌套谁负责哪个系统边界一目了然。时序图我们从不直接在 draw.io 里从零画永远是在 Markdown 里写sequenceDiagram确认消息顺序后再导入。导入后把 Lifeline 的虚线样式、Activation 条宽度、消息箭头的颜色统一。需要提醒的是Mermaid 对循环和 alt 分支的表达在 draw.io 里会变成普通文本块需要手工画回矩形框和分支线这一步没有捷径。活动图和泳道draw.io 的 swimlane 支持嵌套比 Astah 更适合跨部门流程。但要注意活动图里的泳道语义和容器语义不一样——泳道表示责任归属容器表示包含关系画的时候不要混用否则评审时会被问到怀疑人生。部署图就更简单了用云厂商图标直接拖节点比 Astah 那种抽象节点图生动得多放在运维手册里读者更容易看懂。4.2 逆向工程与代码同步的新做法Astah 的 Java 逆向工程确实强大但对我们来说使用频率不高而且现代 IDE 自带的类结构视图已经能满足日常查看需求。需要离线依赖图的时候我们改用代码分析工具生成文本再转图。比如 Python 项目用pyreversepyreverse -o svg -p myproject myproject/JS/TS 项目用 dependency-cruiser 输出 JSON再用一个简单的模板脚本转成 Markdown 表格或 Mermaid 文本。整个过程可以挂在 CI 里代码一变依赖图就重新生成。这些自动生成的图和手工画的架构图放在不同目录避免有人误以为它们是同一类东西——自动图反映代码现状手工图表达设计意图两者本来就该分开维护。4.3 版本管理与多人协作Git 工作流.drawio文件进 Git 之后我们配合 draw.io 桌面版的命令行做自动导出drawio --export --format svg --output diagrams/export diagrams/src/*.drawioCI 里跑这个命令SVG 自动刷新PR 页面里就能看到最新图片预览。GitHub 可以用现成的 drawio-export ActionGitLab 直接用 CI job 调 CLI效果一样。多人协作最大的坑是同时编辑同一个.drawio文件。我们的规避方式是改结构的人和调样式的人分开任务必须并行时用分支合并时接受 XML 冲突手工解决。好消息是.drawio是文本冲突能看到上下文比.asta的二进制合并友好太多。每次 commit 的 message 里必须写清楚“改了哪个图、为什么改、逻辑变化点是什么”这样后续有人 merge 时才有依据。4.4 导出与发布SVG / PNG / 嵌入文档导出 SVG 时勾选 Include a copy这个前面强调过还有一个更隐蔽的细节——SVG 里如果用了非系统字体在网页上可能显示不对。我们的做法是在 draw.io 的默认样式里把字体设成系统字体栈比如PingFang SC, Microsoft YaHei, Noto Sans CJK SC导出后在哪打开都不会乱。需要透明背景时PNG 导出要把背景色设为无SVG 天然透明。如果图要贴到公众号或知乎这类编辑器一般导出 PNG 两倍尺寸再压缩SVG 在这些平台的兼容性还不太好。需要 Word 交付物时SVG 可以嵌进 Markdown 再走 pandoc或者直接用 draw.io 导出 EMF/WMF 保底。写对外技术材料时矢量图放大不糊这个优势特别明显需求方要改图给源文件就行不用来回传图片。5. 踩坑实录从 Astah 迁到 draw.io 过程中我遇到的那些问题5.1 老图导入与批量转换很多人问 Astah 的图能不能自动转成 draw.io答案很遗憾基本不能。Astah 导出的是图片draw.io 只认图形文件没有语义转换通道市面上也没有靠谱的转换工具。我们的土办法是“底图重画”把 Astah 导出的大图插进 draw.io 作为底层图片降低透明度在上面重新描一遍。这个过程看起来笨但有两个意外收获一是重画时大家被迫重新审视每张老图结果还真揪出了两处架构文档和代码不一致的 bug二是顺手统一了全团队的图例和配色老图不再五花八门。重画完记得删底图别把旧图留在源文件里否则别人打开看到两层图会懵。5.2 中文字体和排版兼容这是迁移后的第一个丑 bug同一张图在 Windows 上正常换到 Mac 上字体就发虚导出的 SVG 挂到网页上中文偶尔变成方块。原因就是字体没有统一。我们最终在 draw.io 的Extras Configuration里配置了全局字体所有新图默认使用系统字体栈老图通过批量替换样式一次改完。另一个高频问题是中文不换行。Mermaid 导入的节点文本往往很长draw.io 默认不自动换行文字会顶出节点边界。解决办法是选中节点在右侧 Format Panel 里打开 Word Wrap然后手动拉框。没有更好的自动化方案只能养成习惯每次导入后先全局检查一遍文本溢出。5.3 图层、容器、泳道语义差异迁移中最大的语义坑Astah 里“包”是有命名空间含义的draw.io 的容器只是视觉分组。如果我们把 Java 包的层级映射成 draw.io 容器的嵌套反过来又用容器结构去理解代码分层就会得到一堆假依赖关系。我们的原则是容器只做视觉归组真实的依赖关系一律用连线和箭头表达绝不把嵌套当作架构语义。泳道也是类似的坑。活动图泳道如果只是并排的矩形导出 PDF 时可能出现泳道跨页被切断。我们的规避是设定画布宽度压平不必要的嵌套泳道重要泳道图尽量导出 PNG 而不是 PDF。另外draw.io 的泳道可以嵌套但嵌套层级多了以后导出 SVG 的图层顺序会乱元素遮挡关系经常不对所以尽量控制在两层以内。5.4 协作冲突和 Git 合并.drawio文件默认是压缩 XML一行内容读完完全没法手工合并。我们摸索出的办法是需要手工合并时把文件另存为不压缩格式File Save 时勾选 Uncompressed合并完再压缩回来。这一步没有 UI 快捷键但能救急。还有随机 ID 问题draw.io 每个图元都有唯一 ID两个分支各自编辑后合并diff 里会看到大段mxCell变动很难受。我们最后接受了这个现实承认“图标的 diff 永远不如文本 diff 直观”所以把真正需要评审的逻辑放在 Mermaid 草稿层draw.io 层只负责呈现。这个认知是整个闭环能成立的前提想通之后很多工具层面的摩擦就不那么难受了。6. 模版与提示词把闭环固化给团队6.1 Markdown 文档骨架模板我们内部规定每个设计必须按统一骨架来新人不许另起炉灶# 设计文档XXX ## 背景 ## 需求要点AI 从原始需求中提取 ## 交互流程草稿Mermaid 代码区评审后迁移 ## 正式架构图draw.io 导出  ## 评审记录检查单 结论 ## 变更历史时间、作者、改动点骨架的意义是强制流程没有“需求要点”就不允许画图没有“评审记录”就不允许定稿。看起来是文档规范实际是在管住“画图随手就画”的坏习惯。等团队习惯了这套骨架再写文档就是填空效率反而高了。6.2 AI 提示词模板我们沉淀了几个固定提示词模板直接贴在团队 Wiki 里你是资深架构师。把下面的需求描述转成sequenceDiagram格式的 Mermaid 草稿参与者用中文角色名消息用动词短语不要解释不要加备注。读取下面的 Markdown 表格表格列是“状态、事件、目标状态、备注”。用stateDiagram-v2语法生成状态迁移图缺失的目标状态要在备注里标出。下面是 draw.io 导出的 SVG 内嵌 XML。请忽略布局和样式提取图元之间的连接关系还原成 Mermaid 的classDiagram代码用于逻辑对比。提示词的关键不是多花哨而是要有三个约束角色设定、输出格式、禁止内容。特别是“不要解释直接给代码”这句能省掉大量废话。另外AI 输出的逻辑必须人工 review它不懂布局、审美和团队上下文它最擅长的就是把散乱需求变成结构化文本这个环节才是闭环里价值最大的一块。6.3 draw.io 模板库与样式预设团队风格靠模板和样式预设维持。我们把一套包含标准配色、字体、线宽的.drawio模板放进 Git 仓库新人第一次画图先打开模板再另存。约定如下核心层用蓝色系、平台层绿色、接入层橙色线宽 1.5pt字体 12pt圆角 4px。这套约定写进CONTRIBUTING.md评审时如果风格不符直接打回。样式预设还可以在Extras Configuration里补充自定义形状库比如公司内部的服务图标、规范化的组件样式。这样画出来的图不只有统一风格还带着公司特有的视觉资产。这块投入前期不大但收益最长尾团队所有图放一起看像同一个产品出的。6.4 团队推广的节奏与避坑推广别搞“一刀切”。我们的节奏是先拿一个小项目试点把闭环完整跑给团队看再挑两个影响力大的核心系统迁移让大家看到 PR 里图是可以 diff、可以评论的最后才把 Astah 的老流程正式下线。阻力主要来自用惯 Astah 的老人。我们给了一个缓冲期老图继续用 Astah 看但新图一律 draw.io三个月后谁也没再开 Astah。还有一个很有效的动作把 Astah 的 License 到期时间贴在群里到期不续费倒逼迁移完成。这个做法有点粗暴但确实好用省得一直纠结“要不要再保留一个”。我个人在这一年实操里最深的体会是工具迁移的表面是“换个软件画图”本质是重新定义“图是怎么被产生、被评审、被维护的”。Astah 把图当成独立资产而 draw.io 加 Markdown 加 Mermaid 加 AI 这套组合把图变成了文档流水线上的一环——图不再是终点而是需求到代码之间一层可追溯的中间产物。如果你现在正在犹豫要不要从 Astah 迁移我的建议是先别急着续费花两天时间用 Mermaid 画一张你最常用的真图再放进 draw.io 精修一下你就知道这套闭环值不值得了。