引言
在现代软件工程中,架构文档常常遭受“文档腐烂”的问题。在拖放工具中创建的图表一旦导出为静态图像,便立即过时,逐渐与实际代码库脱节。解决方案在于将架构视为代码。
“C4 模型提供了一种实用的分层方式来可视化软件架构,包含四个抽象层级:系统上下文, 容器, 组件,以及代码。通过将 C4 方法与PlantUML以及“图表即代码”工作流,团队可以直接在源代码旁边维护版本控制、高度同步的架构蓝图。

本指南探讨如何使用 PlantUML 实现 C4 建模,并借助现代工具如Visual Paradigm, VPasCode,以及AI 聊天机器人,确保你的架构始终成为开发过程中鲜活、动态的产物。
核心概念
在深入语法之前,理解该方法的核心支柱至关重要:
-
C4 层级结构:一种受数字地图启发的缩放隐喻。你从国家层级(上下文)开始,放大到城市层级(容器),再到街道层级(组件),最后是建筑蓝图(代码)。
-
图表即代码:使用基于文本的领域特定语言(如 PlantUML)编写图表,而非手动绘制。这使得差异比较、合并以及 CI/CD 集成成为可能。
-
VPasCode:Visual Paradigm 的脚本语言,弥合了基于文本的 PlantUML 与 Visual Paradigm 丰富的元数据存储库之间的差距,实现了双向同步。
-
AI 辅助建模:利用大型语言模型,根据自然语言需求生成初始的 C4 PlantUML 草稿,显著减少了样板代码的摩擦。
1. 开始使用 C4-PlantUML
要在 PlantUML 中使用 C4 模型,您需要从 GitHub 仓库引入官方的 C4 PlantUML 宏定义。这将提供专门的元素,例如系统, 容器, 组件以及关系连接器(Rel).
基本设置与模板

@startuml
!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Context.puml
' 布局指令
skinparam Linetype polyline
title 互联网银行系统系统上下文图
Person(customer, "银行客户", "拥有个人银行账户的银行客户。")
System(banking_system, "互联网银行系统", "允许客户查询账户、进行支付和管理个人资料。")
System_Ext(mail_system, "电子邮件系统", "用于发送确认邮件的内部 Microsoft Exchange 系统。")
System_Ext(mainframe, "主机银行系统", "存储核心银行信息和交易历史。")
Rel(customer, banking_system, "使用", "HTTPS")
Rel(banking_system, mail_system, "发送电子邮件", "SMTP")
Rel(banking_system, mainframe, "从...获取账户信息", "存储过程 / TCP/IP")
@enduml 💡 工具提示:虽然标准 PlantUML 可以完美渲染此内容,但将此代码导入到Visual Paradigm通过 VPasCode 编辑器,您可以将这些抽象元素链接到项目存储库中的实际 UML 类或数据库模式。
2. 第一级:系统上下文图
该系统上下文图位于最高层级。它将您的软件系统显示为中央的一个方框,周围环绕着其用户以及与之交互的其他软件系统。
-
人员: 表示系统的人类用户。
-
系统: 您正在构建的软件系统。
-
系统外部: 外部软件系统(例如:支付网关、遗留大型机、电子邮件服务提供商)。
示例:电商平台上下文

@startuml
!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Context.puml
LAYOUT_WITH_LEGEND()
title 电商平台系统上下文图
Person(shopper, "在线购物者", "浏览和购买商品的用户。")
Person(admin, "后台管理员", "管理库存、订单和客户查询。")
System(ecommerce, "电商平台", "允许用户搜索商品、下单并进行安全支付。")
System_Ext(payment_gateway, "支付网关", "处理信用卡和数字钱包交易。")
System_Ext(shipping_provider, "全球物流 API", "计算运费并生成追踪标签。")
System_Ext(crm_system, "CRM 系统", "处理客户支持工单和营销活动。")
Rel(shopper, ecommerce, "浏览商品并购买商品", "HTTPS")
Rel(admin, ecommerce, "更新库存并管理订单", "HTTPS")
Rel(ecommerce, payment_gateway, "通过支付网关处理付款", "REST API")
Rel(ecommerce, shipping_provider, "通过物流 API 预订配送", "REST API")
Rel(ecommerce, crm_system, "同步客户资料并记录支持请求", "Webhook")
@enduml AI 聊天机器人集成
无需从头编写上述内容,您可以向 AI 聊天机器人发出提示:
“为包含购物者、管理员、支付网关和物流提供商的电商平台生成一个 C4 系统上下文 PlantUML 图。”
AI 将生成 90% 正确的语法,您只需细化具体的关系标签和技术协议。
3. 第二层:容器图
“容器”容器图将软件系统放大,以展示高层级的技术构建模块。“容器”是一个可独立运行/部署的单元(例如:单页应用、移动应用、微服务、数据库、无服务器函数)。
-
容器: 应用程序或数据存储。
-
容器数据库: 代表数据库或数据存储的专用容器。
示例:电商容器

@startuml
!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Container.puml
LAYOUT_WITH_LEGEND()
title 电子商务平台容器图
Person(shopper, "在线购物者", "在线购买商品。")
System_Boundary(ecommerce, "电子商务平台") {
Container(spa, "单页应用", "React, TypeScript", "通过浏览器向购物者提供所有功能。")
Container(api, "API 网关/后端", "Node.js, Express", "处理业务逻辑、路由和身份验证。")
ContainerDb(db, "数据库", "PostgreSQL", "存储用户资料、产品目录和订单数据。")
Container(cache, "缓存层", "Redis", "存储会话数据和产品目录缓存。")
}
System_Ext(payment_gateway, "支付网关", "处理信用卡支付。")
Rel(shopper, spa, "访问 shop.com", "HTTPS")
Rel(spa, api, "发起 API 调用", "JSON/HTTPS")
Rel(api, cache, "读取/写入会话状态", "TCP")
Rel(api, db, "读取/写入订单和用户", "SQL/TCP")
Rel(api, payment_gateway, "扣款信用卡", "REST API")
@enduml
4. 第三层:组件图
该组件图将单个容器放大,以显示内部组件(例如 Spring Bean、模块、控制器、服务)及其交互。
示例:API 网关组件

@startuml
!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Component.puml
LAYOUT_WITH_LEGEND()
title API 网关/后端服务组件图
Container(spa, "单页应用", "React, TypeScript", "提供 UI 功能。")
ContainerDb(db, "数据库", "PostgreSQL", "存储核心数据。")
Container_Boundary(api, "API 网关/后端") {
Component(auth_controller, "认证控制器", "Express 路由", "处理用户登录、令牌生成和 JWT 验证。")
Component(order_controller, "订单控制器", "Express 路由", "处理传入的订单创建请求。")
Component(order_service, "订单服务", "Node.js 服务", "包含核心结账和验证逻辑。")
Component(order_repo, "订单仓储", "数据映射器", "对 PostgreSQL 执行 SQL 查询。")
}
Rel(spa, auth_controller, "发送凭证", "JSON/HTTPS")
Rel(spa, order_controller, "提交订单负载", "JSON/HTTPS")
Rel(order_controller, order_service, "调用业务逻辑")
Rel(order_service, order_repo, "查询数据")
Rel(order_repo, db, "读取/写入行", "SQL/TCP")
@enduml
Visual Paradigm 与 VPasCode 的优势
虽然 PlantUML 会自动处理布局,Visual Paradigm通过 VPasCode 为企业增加价值。当您导入上述组件图时:
-
仓库链接:VPasCode 可以将
order_service映射到您 VP 项目中的实际 Java 类或 Node.js 模块。 -
影响分析:如果您更改
Order Repository接口,VP 可以将 C4 图标记为过时。 -
统一样式:使用存储在 VP 中的贵组织官方企业架构/架构样式模板,覆盖 PlantUML 的默认 skinparams。
5. 维护 C4 PlantUML 的最佳实践
-
将代码保留在源代码附近: 将您的
.puml图表文件直接存放在您的代码仓库中(例如,在/docs/architecture文件夹下),以便它们与您的代码库同步演进。 -
利用 AI 进行草图绘制: 使用自然语言提示词即时生成初始的 PlantUML C4 模块,然后手动细化边界和关系。
-
自动化渲染: 使用插件或命令行工具将 PlantUML 生成集成到您的 CI/CD 流水线中,自动将 SVG/PNG 图表输出到您的内部维基。
-
混合工具策略: 使用原始 PlantUML 进行快速 PR 级别文档编写,但通过 VPasCode 将关键架构决策同步到 Visual Paradigm,以实现长期治理和利益相关者报告。
-
标签与元数据: 使用 C4 标签(
$tags="...") 以实现过滤功能。在 Visual Paradigm 中,这些标签可驱动动态视图和合规报告。
结论
采用 PlantUML 进行 C4 建模,将架构从一种仪式性的交付物转变为持续的工程实践。通过从 C4 的结构化抽象开始,并利用AI 聊天机器人 进行快速草图绘制,PlantUML 进行版本控制的渲染,以及Visual Paradigm/VPasCode 进行企业级仓库管理,团队即可实现真正的架构对齐。
成功的关键不仅在于绘制方框,更在于将这些方框集成到您的开发生命周期中。从系统上下文图开始,在 CI 流水线中自动化其渲染,并随着团队架构成熟度的提升逐步细化。未来的您——以及您的新入职工程师——都会感谢您。











