以图形用户界面(GUI)为先的架构存在的问题
多年来,C4 建模一直陷入一个悖论:我们倡导“架构即代码”,但大多数团队仍然通过在图形用户界面中拖拽方框来构建 C4 图表。这导致文档过时、二进制文件出现合并冲突,以及图表与实际系统之间的脱节。
现代开发团队需要一个这样的工作流程:对话激发设计并且代码维持其演进。通过结合 Visual Paradigm 的AI 聊天机器人与VPasCode,您可以在几分钟内从自然语言提示直接生成生产级的 C4 PlantUML 代码——全程无需使用鼠标。

本指南将通过具体的 PlantUML 示例展示该工作流程。
第一阶段:使用 AI 聊天机器人进行对话式设计
Visual Paradigm 中的 AI 聊天机器人充当您的架构副驾驶。您不是从空白画布开始,而是从明确意图开始。
✅ 有效的提示策略
不要要求 AI“绘制图表”。请要求它使用 C4 语义对系统进行建模。请明确说明边界、技术栈和数据流。
💬 AI 聊天机器人提示示例:
“请扮演一名软件架构师。为‘在线银行系统’创建一个 C4 容器图。包含 Web 应用(React)、移动应用(Flutter)、API 网关(Kong)、核心银行服务(.NET)以及 PostgreSQL 数据库。展示通过 OAuth2 进行的认证流程以及账户余额查询。输出使用官方宏的有效 C4-PlantUML 代码。”
🤖 预期的 AI 输出(优化后)
AI 将生成一个初稿 PlantUML 模型。请批判性地审查它——AI 擅长构建结构,但可能会虚构关系。使用后续聊天提示进行优化:“在 API 网关与核心银行服务之间添加 Redis 缓存以用于会话管理”或“将 PostgreSQL 数据库标记为已弃用,并添加一个新的 MongoDB 集群。”
第二阶段:使用 VPasCode 与 PlantUML 进行确定性建模
一旦 AI 生成了可行的初稿,就停止聊天并开始编码。将优化后的 PlantUML 代码复制到一个.puml由 VPasCode 管理的文件。这是您的唯一真实数据源。
以下是通过此工作流生成的可直接用于生产的 C4 PlantUML 示例。请确保您的 Visual Paradigm 项目包含C4-PlantUML 库.
示例 1:系统上下文图(第 1 层)
此图定义了您系统的边界及其外部参与者。

@startuml OnlineBanking_Context
!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Context.puml
title 系统上下文:在线银行平台
Person(customer, "银行客户", "查看账户、转账、支付账单")
Person(admin, "后台管理员", "管理用户、监控交易")
System(banking, "在线银行平台", "通过 Web 和移动设备提供互联网银行服务")
System_Ext(coreLegacy, "核心银行主机", "处理交易、维护总账")
System_Ext(email, "电子邮件服务", "发送通知和账单")
System_Ext(oauth, "OAuth2 提供商", "处理身份和认证")
Rel(customer, banking, "使用", "HTTPS/WebSocket")
Rel(admin, banking, "管理", "HTTPS")
Rel(banking, coreLegacy, "读取/写入", "REST/SOAP")
Rel(banking, email, "发送警报", "SMTP/API")
Rel(banking, oauth, "认证", "OIDC")
@enduml
示例 2:容器图(第 2 层)
将系统分解为运行时容器。请注意使用ContainerDb, ContainerQueue以及技术标签——这对现代云原生系统至关重要。

@startuml OnlineBanking_Containers
!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Container.puml
title 容器图:在线银行平台
Person(customer, "银行客户")
System_Boundary(banking, "在线银行平台") {
Container(webapp, "Web 应用", "React + Node.js", "用于基于浏览器的银行服务的单页应用")
Container(mobile, "移动应用", "Flutter", "iOS/Android 原生体验")
Container(api, "API 网关", "Kong", "路由请求、限流、认证验证")
Container(service, "账户服务", ".NET 8", "账户与余额的业务逻辑")
Container(cache, "会话缓存", "Redis", "存储 JWT 令牌与会话状态")
ContainerDb(db, "账户数据库", "PostgreSQL", "客户账户、余额、交易")
ContainerQueue(events, "事件总线", "RabbitMQ", "异步交易通知")
}
System_Ext(oauth, "OAuth2 提供商")
System_Ext(legacy, "核心银行主机")
Rel(customer, webapp, "使用", "HTTPS")
Rel(customer, mobile, "使用", "HTTPS")
Rel(webapp, api, "调用", "REST/JSON")
Rel(mobile, api, "调用", "REST/JSON")
Rel(api, oauth, "验证令牌", "OIDC")
Rel(api, service, "路由至", "gRPC")
Rel(service, cache, "读取/写入会话", "TCP")
Rel(service, db, "查询", "SQL/TCP")
Rel(service, events, "发布", "AMQP")
Rel(service, legacy, "同步总账", "SOAP")
@enduml
示例 3:组件图(第 3 层)——账户服务
聚焦于单个容器。这正是 VPasCode 大放异彩之处:组件可直接映射到代码模块。

@startuml AccountService_Components
!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Component.puml
title 组件图:账户服务 (.NET 8)
Container(api, "API 网关", "Kong")
ContainerDb(db, "账户数据库", "PostgreSQL")
ContainerQueue(events, "事件总线", "RabbitMQ")
Component(auth, "认证中间件", "ASP.NET 过滤器", "验证 JWT,提取用户上下文")
Component(controller, "AccountController", "ASP.NET API", "/accounts 的 REST 端点")
Component(domain, "AccountDomainService", "C# 类库", "余额计算、转账规则")
Component(repo, "AccountRepository", "EF Core", "数据访问、查询优化")
Component(publisher, "EventPublisher", "MassTransit", "发布 TransactionCompleted 事件")
Rel(api, auth, "传递请求")
Rel(auth, controller, "转发已认证请求")
Rel(controller, domain, "调用业务逻辑")
Rel(domain, repo, "查询/持久化")
Rel(repo, db, "执行 SQL")
Rel(domain, publisher, "发出领域事件")
Rel(publisher, events, "发布", "AMQP")
@enduml
第 3 阶段:将 VPasCode 集成到您的开发工作流中
生成 PlantUML 只是成功的一半。以下是让其在现代团队中真正落地的方法:
对一切进行版本控制
存储所有.puml文件与您的应用程序代码一起存储在同一个仓库中。将图表视为基础设施即代码:
/docs/architecture/c4/
├── 01-context.puml
├── 02-containers.puml
├── 03-account-service-components.puml
└── README.md
在 CI/CD 中自动化渲染
使用 Visual Paradigm 的命令行工具或 GitHub Action,在每次拉取请求时自动渲染 PNG/SVG 文件。切勿手动提交已渲染的图像。
# GitHub Action 示例片段
- name: 渲染 C4 图表
run: |
vp-cli render -i docs/architecture/c4/*.puml
-o docs/architecture/output/
-f svg --c4-layout auto
与 VPasCode 实现双向同步
VPasCode 不仅仅是一个渲染器——它是一个模型同步引擎。当您更新 PlantUML 时:
-
Visual Paradigm 的中心模型会自动更新
-
交叉引用(例如,将组件链接到 Jira 史诗或 Git 仓库)将保持完整
-
使用图形界面的团队成员可以实时看到更改
-
AI 聊天机器人对话可以引用当前模型状态,而非过时的快照
⚠️ 重要警告:切勿让 AI 生成的 PlantUML 绕过人工审查。AI 经常编造不存在的 API、错误标记协议或遗漏关键安全边界。在提交之前,务必根据您的实际代码库和威胁模型验证生成的代码。
现代团队的采用检查清单
| 步骤 | 操作 | 工具 |
|---|---|---|
| 1 | 通过对话式提示引导初始化 C4 模型 | AI 聊天机器人 |
| 2 | 通过迭代对话优化和修正 AI 输出 | AI 聊天机器人 |
| 3 | 将验证后的 PlantUML 导出到版本控制仓库 | VPasCode |
| 4 | 配置 CI 流水线,在拉取请求时自动渲染 | VPasCode 命令行工具 |
| 5 | 将 C4 元素关联到代码仓库、工单和文档 | Visual Paradigm |
| 6 | 安排季度“模型维护”审查,利用 AI 进行批判性评估 | AI 聊天机器人 |
最终思考
C4 建模不应成为团队速度的负担。通过将 AI 视为创意的火花并将 VPasCode 视为确定性的锚点,您就能兼得两者之长:快速探索和可持续的文档。停止拖拽方框。开始以对话的速度进行架构设计。







