1. 项目概述当AIGC遇上PlantUML画图这件事彻底变了作为一名在技术文档和架构设计领域摸爬滚打了十多年的老手我画过的图比我写过的代码行数可能还要多。从最初用Visio拖拽到后来用各种在线工具再到沉迷于代码画图的优雅我一直在寻找那个“终极”方案。直到最近我把AIGC人工智能生成内容和PlantUML结合了起来才真正体会到什么叫“高效画图”。这不再是简单的工具叠加而是一次工作流的彻底重构。简单来说这个方案的核心是你用自然语言描述你想要什么图AI帮你生成标准的PlantUML代码然后PlantUML引擎瞬间将其渲染成清晰、规范的图表。它完美解决了几个长期痛点一是构思与绘制脱节脑子里有想法手上画不出来或者画得慢二是维护困难图形化工具生成的图后续修改简直是噩梦三是风格不统一团队协作时十个人能画出十种风格的流程图。现在你只需要关心“逻辑”本身剩下的脏活累活交给AI和代码。这套方案适合所有需要频繁产出技术图表的人无论是软件架构师、产品经理、开发工程师还是技术文档工程师。如果你受够了反复调整框线对齐厌倦了因图表更新不及时而导致的文档过期那么接下来的内容就是你一直在等的“解药”。我们将深入拆解如何搭建这套自动化流水线并分享那些只有踩过坑才知道的实操细节。2. 核心思路与方案选型为什么是AIGC PlantUML在决定采用这个组合之前我评估过市面上几乎所有主流的画图方案。Visio、Draw.io、Lucidchart这类图形化工具优点是上手快、所见即所得但缺点同样明显效率瓶颈在“手”修改成本高难以版本化管理。Mermaid.js这类基于文本的图表工具是一大进步它用代码定义图表解决了维护和版本控制的问题。但它的语法依然需要学习和记忆对于复杂图表手写代码的脑力负担并不小。而PlantUML在这个领域堪称“隐藏的王者”。它是一门领域特定语言DSL语法极其丰富支持序列图、用例图、类图、活动图、组件图、部署图、状态图、对象图、定时图甚至还有思维导图和架构图。它的渲染效果专业、风格统一并且由于是纯文本可以完美融入Git进行版本控制差异对比一目了然。但它的学习曲线尤其是复杂布局和样式定制劝退了不少人。这时AIGC的价值就凸显出来了。以大语言模型LLM为代表的AIGC最擅长的就是理解自然语言并将其转化为结构化的指令或代码。我们不需要教会AI PlantUML的全部语法只需要让它学会将我们的设计意图“翻译”成正确的PlantUML代码。这相当于为PlantUML配了一个“理解你想法”的智能助手。我选择这个组合基于以下几个核心考量关注点分离人的大脑专注于高层逻辑和设计做什么AI负责将逻辑转化为规范语法怎么做PlantUML负责最终呈现做成什么样。各司其职效率最大化。质量与一致性AI生成的PlantUML代码遵循标准语法渲染出的图表在样式、间距、字体上天然保持一致极大提升了文档的专业度。可迭代性修改图表不再是重画而是修改描述或调整生成的代码。你可以对AI说“把用户模块改成蓝色并在数据库前面加一个缓存服务器”它就能给出新的代码。这种交互式的设计过程流畅得超乎想象。无缝集成PlantUML代码可以嵌入Markdown、Confluence、GitLab Wiki等几乎所有文档系统。结合CI/CD可以实现文档随代码自动更新。注意这里说的AIGC特指能够处理代码和结构化文本的大语言模型例如GPT-4、Claude 3、DeepSeek等通过API调用的模型或者是本地部署的Llama、Qwen等开源模型。绝对不涉及任何其他违规或敏感的技术领域。3. 环境搭建与工具链配置工欲善其事必先利其器。这套方案的落地需要一个稳定、高效的工具链。下面是我经过多次实践后总结出的最流畅的配置方案。3.1 PlantUML环境部署PlantUML本身是一个Java程序它需要Graphviz来执行布局渲染。因此第一步是搭建PlantUML的运行环境。方案一本地安装推荐给高频、离线用户这是最可控的方式。首先确保你的系统安装了Java运行环境JRE 8或以上。然后从PlantUML官网下载最新的plantuml.jar文件。接着安装Graphviz。在macOS上使用brew install graphviz在Ubuntu/Debian上使用sudo apt-get install graphvizWindows用户可以从Graphviz官网下载安装包。安装完成后你可以通过命令行测试java -jar plantuml.jar -tsvg test.txt。如果test.txt里有一段简单的PlantUML代码这条命令会生成一个SVG图片。方案二使用VS Code插件最适合日常开发对于绝大多数开发者而言在VS Code中集成是最佳体验。安装“PlantUML”插件作者jebbs。这个插件会自动在后台处理Java和Graphviz的依赖或引导你安装并提供实时预览功能。你新建一个.puml或.plantuml文件编写代码右侧就会同步渲染出图表保存时自动导出图片无比顺畅。方案三在线服务器/ Docker对于团队共享或集成到Web应用可以搭建PlantUML服务器。官方提供了Docker镜像docker run -d -p 8080:8080 plantuml/plantuml-server:jetty。之后你就可以通过向http://your-server:8080发送POST请求内容为PlantUML代码来获取图片。这在一些内部Wiki系统中非常有用。实操心得个人开发强烈推荐VS Code插件方案几乎零配置所见即所得。如果团队需要统一渲染服务比如用于CI中自动生成文档则采用Docker部署方案。本地JAR包方式更适合写脚本进行批量处理。3.2 AIGC工具接入与选择接下来是关键让AI理解并生成PlantUML代码。这里有两个主流路径。路径一使用通用大语言模型的API这是最灵活、能力最强的方案。你需要一个OpenAI、Anthropic或国内合规且能力相当的AI服务商API Key。核心是构造一个有效的提示词Prompt。例如你可以创建一个这样的系统提示词你是一个PlantUML专家擅长将自然语言描述转化为准确、简洁、规范的PlantUML代码。请遵循以下规则 1. 只输出PlantUML代码不要有任何解释。 2. 使用标准的PlantUML语法。 3. 对于时序图明确参与者participant和消息。 4. 对于类图注意属性和方法的可见性、-、#。 5. 如果描述中有不确定的地方按照最常见的软件设计模式来补充。然后用户的请求可以是“画一个用户登录的时序图包括用户、前端、后端服务和数据库。” AI就会返回一段完整的PlantUML代码。你可以用Python、Node.js等写一个简单的脚本将这段代码发送到本地或远程的PlantUML服务端生成图片一气呵成。路径二使用集成了AI的PlantUML工具现在已经有一些工具开始原生集成AI。例如某些在线的PlantUML编辑器增加了“AI生成”按钮你输入描述它直接在编辑框里生成代码。这类工具开箱即用适合快速尝试但灵活性和定制性不如直接调用API。路径三本地模型部署出于数据隐私或网络考虑你可以在本地部署一个开源的大语言模型如Qwen、Llama的某个量化版本并通过其API接口进行类似路径一的调用。这对硬件有一定要求但数据完全私有。注意事项无论选择哪种路径提示词工程Prompt Engineering都是成败关键。最初的AI回复可能不完美你需要通过迭代优化你的提示词。例如加入“使用skinparam将所有背景设为白色箭头为黑色”、“组件图使用rectangle并加上阴影”等样式指令可以让生成的图表更符合你的审美。3.3 自动化流水线构思当基础工具就位后我们可以构思一个完整的自动化流程这将把效率提升到另一个维度。输入你在IDE或笔记软件中用自然语言写下图表描述可能保存在一个Markdown文件里用特定的标记如!-- AI_UML: 描述文字 --包裹。处理一个本地脚本比如用Python写的定期扫描你的项目目录找到这些标记提取描述文字。生成脚本调用AI API将描述和优化后的提示词一起发送获得PlantUML代码。渲染与替换脚本调用本地plantuml.jar或HTTP请求PlantUML服务器将代码渲染成PNG或SVG图片保存到指定目录。同时用生成的图片Markdown链接替换掉原来的标记。输出你的Markdown文件现在包含了实时、准确的图表。结合Git每次提交都是文档和代码的同步更新。这套流水线听起来复杂但用脚本实现起来可能不到100行代码。它实现了“描述即图表”文档真正成为了“活文档”。4. 核心应用场景与Prompt实战技巧有了工具更重要的是知道怎么用。不同的图表类型需要不同的描述方式和Prompt技巧。下面我结合几个最常用的场景分享具体的操作方法和“咒语”。4.1 场景一快速生成系统架构图架构图是技术沟通的基石。以前画一个清晰的架构图调整布局就要花半天。现在你可以这样对AI说原始描述“画一个微服务架构图。有一个API网关接收外部请求。网关后面是四个微服务用户服务、订单服务、商品服务和支付服务。它们都连接到一个共用的Redis缓存集群和一个MySQL主从数据库。所有服务都注册到一个服务中心并由配置中心管理配置。使用矩形框表示组件箭头表示依赖关系给数据库和缓存加上不同的图标。”优化后的Prompt给AI的指令请生成PlantUML代码绘制一个组件图component diagram。 要求 1. 使用 rectangle 组件并加上 组件 的标记。 2. 组件包括API网关、用户服务、订单服务、商品服务、支付服务、服务中心、配置中心、Redis缓存集群、MySQL数据库。 3. 用箭头表示依赖方向外部请求 - API网关。API网关 - [用户服务 订单服务 商品服务 支付服务]。所有微服务 - 服务中心。所有微服务 - 配置中心。所有微服务 -- Redis缓存集群。所有微服务 -- MySQL数据库。 4. 使用 database 关键字和 (缓存) 标记来区分MySQL和Redis。 5. 整体布局从左到右逻辑清晰。 只输出PlantUML代码。AI可能会返回如下代码startuml !define RECT rectangle skinparam componentStyle rectangle rectangle “外部请求” as req rectangle “组件\nAPI网关” as gateway rectangle “组件\n用户服务” as user rectangle “组件\n订单服务” as order rectangle “组件\n商品服务” as product rectangle “组件\n支付服务” as payment rectangle “组件\n服务中心” as registry rectangle “组件\n配置中心” as config database “MySQL数据库” as db database “(缓存)\nRedis集群” as cache req -- gateway gateway -- user gateway -- order gateway -- product gateway -- payment user -- registry order -- registry product -- registry payment -- registry user -- config order -- config product -- config payment -- config user -- cache order -- cache product -- cache payment -- cache user -- db order -- db product -- db payment -- db enduml将这段代码放入PlantUML一张标准的架构图就生成了。如果对布局不满意你可以在生成的代码基础上微调或者给AI更详细的布局指令如“使用left to right direction布局将数据库放在最右边”。4.2 场景二梳理业务流程时序图时序图是理解复杂交互的利器。用自然语言描述交互流程AI能很好地将其转化为带生命线的时序图。原始描述“描述一个用户通过手机App扫码登录电脑端网站的过程。用户打开网站看到二维码。用户用手机App扫描二维码。App向认证服务器请求临时令牌。认证服务器生成令牌并返回。App将令牌和用户信息发送给网站后端。后端验证令牌并建立会话。最后网站页面跳转显示登录成功。”优化后的Prompt请生成PlantUML代码绘制一个序列图sequence diagram。 参与者包括用户、手机App、电脑网站前端、网站后端、认证服务器。 流程如下 1. 用户访问网站前端显示二维码。 2. 用户用App扫描二维码。 3. App向认证服务器请求临时令牌。 4. 认证服务器生成并返回令牌。 5. App将令牌和用户信息发送给网站后端。 6. 后端向认证服务器验证令牌。 7. 认证服务器返回验证结果。 8. 后端建立用户会话并通知前端登录成功。 9. 前端页面跳转。 请使用participant关键字并注意消息的先后顺序。可以适当使用note关键字在关键步骤加注释。 只输出PlantUML代码。通过这样的PromptAI生成的代码结构会非常清晰你几乎可以直接使用。如果流程有分支比如扫码失败可以在描述中加入“如果...否则...”AI通常也能处理。4.3 场景三设计数据库ER图虽然PlantUML不是专业的ER工具但其类图语法非常适合快速勾勒表结构关系。原始描述“设计一个博客系统的核心ER图。需要有用户表id用户名邮箱、文章表id标题内容作者id分类id、分类表id名称。用户和文章是一对多关系。文章和分类是多对一关系。再给文章加一个标签表文章和标签是多对多关系。”优化后的Prompt请使用PlantUML的类图class diagram语法生成一个实体关系图。 实体用class表示 1. User字段包括 id (主键) username email。 2. Article字段包括 id (主键) title content author_id (外键) category_id (外键)。 3. Category字段包括 id (主键) name。 4. Tag字段包括 id (主键) tag_name。 关系 - 一个User拥有多篇ArticleUser “1” -- “*” Article。 - 一篇Article属于一个CategoryArticle “*” -- “1” Category。 - 一篇Article可以有多个Tag一个Tag可以属于多篇Article需要中间关联表article_tags包含article_id和tag_id。 请清晰地表示出主键、外键和关系基数1, *。使用表示public字段。 只输出PlantUML代码。AI会根据这个描述生成带有字段和关联关系的类图代码。虽然不如专业ER工具美观但对于快速设计、沟通和文档化来说已经完全足够并且修改起来极其方便。实操心得对于AI生成PlantUML我的经验是“分步描述逐步细化”。不要试图在第一句Prompt中就描述一个极其复杂的图表。可以先让AI生成主干框架然后基于输出的代码再让AI进行“美化调整一下布局让线条不要交叉”、“给所有服务加上淡蓝色背景”等局部优化。这种“人机协同”的方式效果往往比一次性提出复杂要求更好。5. 高级技巧与样式深度定制当你能熟练生成基础图表后下一步就是让图表变得“好看”且“专业”。PlantUML的强大之处在于其丰富的样式定制能力而AI可以帮助我们管理这些样式。5.1 使用Skinparam统一全局样式PlantUML的skinparam指令可以控制几乎所有视觉元素。我们可以创建一个样式“模板”让AI在生成代码时自动应用。创建样式模板 你可以定义一个包含常用样式的代码块让AI在生成任何图表前先插入它。例如‘ 通用样式定义 skinparam backgroundcolor #F5F5F5 skinparam defaultFontName Helvetica skinparam defaultFontSize 12 skinparam shadowing false ‘ 序列图样式 skinparam sequence { ArrowColor #333333 ActorBorderColor #4A90E2 LifeLineBorderColor #CCCCCC ParticipantBackgroundColor #FFFFFF } ‘ 类图/组件图样式 skinparam class { BackgroundColor #E3F2FD BorderColor #1976D2 ArrowColor #1976D2 } skinparam component { BackgroundColor #FFF3E0 BorderColor #FF9800 }你可以将这个模板保存为一个单独的文件如common_style.puml然后在你的主文件中用!include引入。更高级的做法是在给AI的Prompt中直接加入“在生成的代码开头加入以下样式定义[粘贴上面的样式代码]”。这样AI生成的所有图表都会遵循统一的视觉规范。5.2 处理复杂布局与逻辑有时AI生成的布局可能不理想比如线条交叉过多。PlantUML提供了一些指令来手动调整。调整方向在图开头使用left to right direction或top to bottom direction改变整体布局方向。隐藏/显示元素使用hide/show指令可以控制某些参与者或消息的显示。手动排列对于组件图你可以使用[A] -up- [B]或[A] -left- [B]来指定相对位置。虽然不如拖拽直观但对于固定架构图一次调整后即可复用。你可以指示AI“在生成的代码中使用left to right direction并手动排列组件确保从API网关到微服务的箭头不交叉。” AI会在代码中加入相应的位置指令。5.3 构建可复用的模块库在大型项目中很多组件如“数据库”、“消息队列”、“网关”会反复出现。我们可以让AI学习这些“模块”的定义。方法创建一个“模块定义库”文件如modules.puml里面用!define和!procedure定义好这些组件的画法。!define RDS(name, color) database name as “RDS\n”name #color !procedure Kafka(name) rectangle “消息队列\n”name as name #lightblue !endprocedure然后在Prompt中告诉AI“请参考我们已有的组件定义如下在生成代码时使用这些宏。[粘贴modules.puml内容]”。这样AI生成的代码会调用RDS(“订单库”, “#FFE”)和Kafka(“日志队列”)使得所有图表中的同类组件外观完全一致。6. 集成到日常工作流与CI/CD让工具融入现有流程才能产生最大价值。以下是几种常见的集成姿势。6.1 与文档系统如Markdown, Confluence结合这是最直接的用法。在Markdown中你可以使用“代码块标记渲染插件”的方式。本地写作VS Code安装Markdown Preview Enhanced这类插件它支持直接渲染Markdown中的PlantUML代码块语言标记为plantuml。你写文档时预览窗格就能实时看到图表。GitLab/GitHub Wiki两者都支持PlantUML。GitLab需要管理员启用PlantUML集成使用自建或官方的PlantUML服务器。启用后在wiki或issue中使用plantuml代码块即可。Confluence需要安装PlantUML for Confluence插件。安装后使用{plantuml}宏包裹你的代码。自动化流程你的文档仓库里存放的是.puml源文件。在CI流水线如GitLab CI中可以添加一个生成图片的Job。这个Job遍历所有.puml文件调用PlantUML Docker容器或命令行生成PNG并将图片作为产物存档或提交到另一个分支。这样每次合并请求都能自动更新文档中的图表。6.2 与设计评审流程结合在设计阶段我们经常需要快速产出和迭代架构图。可以建立一个“设计文档模板”。模板中预留出图表位置用特定的占位符表示例如{{ARCH_DIAGRAM}}。设计师或架构师在对应的文本段落中用自然语言描述图表。运行一个脚本扫描文档找到描述调用AI生成PlantUML代码再渲染成图片最后替换占位符。生成的文档可以直接用于评审。评审者如果对图表有意见可以直接修改描述文字再次运行脚本即可更新极大提升了评审和迭代的效率。6.3 遇到的典型问题与排查清单即使方案再完美实践中也难免会遇到问题。下面是我踩过的一些坑和解决方案。问题现象可能原因排查与解决思路AI生成的代码无法渲染报语法错误。1. AI误解了描述生成了无效语法。2. AI使用了较新或实验性的PlantUML语法而本地版本不支持。1.简化Prompt要求AI“使用最基本、最通用的PlantUML语法”。2.分步验证先将AI生成的代码粘贴到PlantUML在线编辑器如www.plantuml.com测试排除环境问题。3.人工修正学习基础的PlantUML语法对AI生成的代码进行小范围修正这也是一个学习过程。图表布局混乱线条交叉严重。PlantUML的自动布局算法在复杂情况下可能不理想。1.使用布局指令在Prompt中要求AI“使用left to right direction布局”。2.手动调整在生成的代码中使用-up-,-down-,-left-,-right-来手动指定组件相对位置。3.拆分图表将一个复杂的图拆分成几个逻辑相关的子图用newpage分隔或在不同的文件中绘制。AI无法理解复杂的业务逻辑生成的图有偏差。自然语言描述存在二义性或者逻辑过于复杂。1.结构化描述改用列表或分步骤的方式描述流程。例如“第一步...第二步...分支情况如果A则...否则...”。2.提供示例在Prompt中给AI一个类似场景的正确PlantUML代码示例让它“参照此格式生成”。3.人机协作先生成主干框架再通过多次对话让AI补充或修改细节。例如“在上图的基础上在用户和网关之间增加一个负载均衡器。”生成的图表风格不符合公司规范。AI没有应用统一的样式。1.创建并引用样式文件如前所述创建common_style.puml并让AI在生成代码时通过!include引用。2.在Prompt中明确样式详细描述样式要求如“所有矩形背景为浅灰色#EEEEEE边框为深蓝色箭头为黑色实线”。3.后处理先让AI生成逻辑正确的代码然后自己或写脚本批量替换/添加skinparam指令。在CI/CD中自动生成图片失败。1. CI环境缺少Java或Graphviz。2. 网络问题无法访问PlantUML服务器。3. 脚本路径或权限错误。1.使用Docker在CI Job中直接使用plantuml/plantumlDocker镜像来运行这是最干净的方式。命令如docker run -v $(pwd):/data plantuml/plantuml -tsvg /data/**/*.puml。2.检查网络如果使用自建PlantUML服务器确保CI Runner能访问到。3.输出日志在脚本中增加详细日志查看是哪一步出错。这套AIGCPlantUML的方案我用了大半年它已经彻底改变了我创作技术文档的方式。从绞尽脑汁思考如何画图到专注于思考逻辑本身这种转变带来的效率提升是惊人的。更重要的是它让图表和文档都变成了“活”的资产可以随着设计的演进而轻松迭代。如果你也受困于画图的低效不妨花上一个下午按照上面的步骤搭建起你自己的环境从画一个简单的登录时序图开始你会立刻感受到那种“动动嘴皮子就把图画了”的畅快感。