使用C4模型与PlantUML进行生产级架构文档编写
执行摘要
本案例研究详细分析了实时生产部署一个现代高性能电子商务平台。该系统旨在通过网页和移动渠道同时服务数千名并发用户,采用微服务启发式架构,重点在于可扩展性、弹性、性能和运维清晰性.
该部署围绕C4模型——具体而言,是部署图——使用PlantUML和C4-PlantUML标准库来建模映射到物理/虚拟基础设施上的运行时容器。该架构集成了多语言后端(Java + Go), Redis缓存, PostgreSQL主从集群, gRPC和HTTP/2协议,以及基于Nginx的负载均衡.
关键成果:
- 实现每秒10,000+个请求在API网关处。
- 确保高可用性通过数据库复制和备用路径实现。
- 优化性能通过激进的缓存和协议选择实现。
- 实现开发人员敏捷性通过语言优化的服务实现。
- 支持跨平台体验(React SPA + React Native移动应用)。
本文档展示了C4部署图作为一个动态的、版本受控的产物,它能够统一技术团队,支持事件响应,并指导容量规划。
1. 业务与技术背景
业务目标
电子商务平台支持:
- 实时产品浏览和搜索。
- 动态库存检查和定价。
- 安全、可靠的订单提交和结账。
- 在浏览器和原生移动应用之间实现无缝体验。
目标用户:全球消费者期望低延迟交互, 实时更新,以及零停机 在高峰期事件期间(例如黑色星期五、季节性促销)。
由 Visual Paradigm AI 聊天机器人生成的部署图

由 Visual Paradigm AI 聊天机器人生成的 PlantUML 代码
@startuml
!include https://static.visual-paradigm.com/plantuml-stdlib/C4-PlantUML/master/C4_Deployment.puml
title 电子商务平台 - 生产环境的部署图
AddElementTag("fallback", $bgColor="#c0c0c0", $fontColor="#666666")
AddRelTag("fallback", $textColor="#c0c0c0", $lineColor="#438DD5")
Deployment_Node(deploymentnode_live, "电子商务生产环境", "生产环境", "位于西雅图的生产数据中心") {
AddProperty("位置", "西雅图,华盛顿州")
AddProperty("网络", "高速光纤")
Deployment_Node_L(deploymentnode_api_gateway, "api-gw-01", "Ubuntu 22.04 LTS", "用于将请求路由到后端服务的 API 网关。") {
AddProperty("流量", "每秒10,000+请求")
AddProperty("协议", "HTTP/2 和 gRPC")
Deployment_Node_L(deploymentnode_order_service, "订单服务", "Java Spring Boot", "处理订单创建、处理和履约。") {
Container(container_order, "订单管理", "Java 和 Spring Boot", "管理订单生命周期,包括创建、状态更新和交付。")
}
Deployment_Node_L(deploymentnode_product_service, "产品服务", "Go with Gin", "提供产品目录和搜索功能。") {
Container(container_product, "产品目录", "Go 和 Gin", "提供产品详情、价格和可用性信息。")
}
}
Deployment_Node_R(deploymentnode_db_primary, "db-prime-01", "Ubuntu 22.04 LTS", "主数据库服务器。") {
Deployment_Node_R(deploymentnode_postgresql_primary, "PostgreSQL - 主", "PostgreSQL 15", "主数据库,存储订单、产品和用户数据。") {
ContainerDb(container_db_primary, "数据库", "PostgreSQL 15", "存储订单历史、库存和产品目录。")
}
}
Deployment_Node_R(deploymentnode_db_secondary, "db-replica-02", "Ubuntu 22.04 LTS", "备用数据库服务器。", $tags="fallback") {
Deployment_Node_R(deploymentnode_postgresql_secondary, "PostgreSQL - 备用", "PostgreSQL 15", "故障转移时的备用副本。", $tags="fallback") {
ContainerDb(container_db_secondary, "数据库", "PostgreSQL 15", "主数据库的副本,用于读取扩展和灾难恢复。", $tags="fallback")
}
}
Deployment_Node_L(deploymentnode_cache_service, "cache-srv-01", "Redis 7.0", "缓存层,用于减少数据库负载。") {
Container(container_cache, "缓存层", "Redis 7.0", "存储频繁访问的产品和订单数据。")
}
Deployment_Node(deploymentnode_web_server, "web-srv-01", "Ubuntu 22.04 LTS", "前端 Web 服务器。") {
AddProperty("CORS", "已启用")
AddProperty("SSL", "已启用")
Deployment_Node(deploymentnode_nginx, "Nginx", "Nginx 1.25", "反向代理和负载均衡器。") {
Container(container_frontend, "前端应用", "React 和 Node.js", "提供购物车、产品页面和结账体验。")
}
}
}
Deployment_Node(deploymentnode_mobile_device, "客户移动设备", "iOS 或 Android") {
Container(container_mobile_app, "移动应用", "React Native", "在移动设备上提供购物、产品浏览和结账功能。")
}
Deployment_Node(deploymentnode_customer_computer, "客户计算机", "Windows 或 macOS") {
Deployment_Node(deploymentnode_browser, "Web 浏览器", "Chrome、Safari、Edge") {
Container(container_spa, "单页应用", "React 和 Redux", "通过 Web 浏览器提供完整的电子商务体验。")
}
}
Rel(container_mobile_app, container_order, "调用 API", "gRPC")
Rel(container_mobile_app, container_product, "调用 API", "gRPC")
Rel(container_spa, container_order, "调用 API", "HTTP/2")
Rel(container_spa, container_product, "调用 API", "HTTP/2")
Rel(container_order, container_db_primary, "读取和写入", "JDBC")
Rel(container_order, container_db_secondary, "读取和写入", "JDBC", $tags="fallback")
Rel(container_product, container_db_primary, "读取和写入", "JDBC")
Rel(container_product, container_db_secondary, "读取和写入", "JDBC", $tags="fallback")
Rel(container_cache, container_db_primary, "缓存数据来自", "Redis")
Rel(container_cache, container_product, "缓存数据来自", "Redis")
Rel_R(container_db_primary, container_db_secondary, "复制数据到")
SHOW_LEGEND()
@enduml 技术需求
| 需求 | 目标 |
|---|---|
| 峰值吞吐量 | API 网关处达到 10,000+ 每秒请求 |
| 数据一致性 | 订单和库存的 ACID 兼容性 |
| 高可用性 | 99.99% 正常运行时间 SLA |
| 可扩展性 | 服务和数据库的横向扩展 |
| 性能 | 关键路径响应时间低于 100 毫秒 |
| 开发人员灵活性 | 按领域使用最合适的语言 |
2. 高层级部署结构
生产环境在逻辑上划分为三个层级:核心后端与数据, 数据持久化,以及前端交付.
核心后端与数据层(左侧)
| 节点 | 技术 | 功能 |
|---|---|---|
api-gw-01(Ubuntu 22.04 LTS) |
Nginx 1.25 + gRPC/HTTP/2 代理 | 所有客户端流量的入口;将流量路由至订单服务和产品服务 |
| 订单服务 | Java Spring Boot | 管理完整的订单生命周期:创建、支付处理、履约、状态跟踪 |
| 产品服务 | Go + Gin | 处理目录管理、产品搜索、定价、可用性及推荐 |
✅ 两个服务均通过 JDBC 连接到主 PostgreSQL 实例。
缓存层
| 节点 | 技术 | 角色 |
|---|---|---|
cache-srv-01 |
Redis 7.0 | 缓存热门产品数据、会话状态和临时订单信息 |
🔥 性能影响:产品查询的数据库读取负载可降低高达 70%。
数据持久化层(右侧)
| 节点 | 技术 | 目的 |
|---|---|---|
db-prime-01 |
PostgreSQL 15(主节点) | 订单、库存、用户和产品数据的唯一可信来源 |
db-replica-02 |
PostgreSQL 15(副本) | 读取扩展和自动故障转移;图中标记为“备用” |
⚠️ 复制模式:同步流式复制确保数据持久性。
🔄 故障转移:主节点故障时,手动或通过 Patroni 等工具自动切换。
前端交付层
| 节点 | 技术 | 功能 |
|---|---|---|
web-srv-01 |
Nginx 1.25(反向代理) | 通过 SSL/TLS 终止、CORS 策略强制执行和负载均衡提供 React 单页应用 |
🌐 客户端:
- Web:基于浏览器的单页应用,使用HTTP/2(头部压缩、多路复用)。
- 移动:使用gRPC(高效二进制协议,强类型)。
3. 主要交互与数据流
客户端到服务端的通信
| 客户端类型 | 协议 | 原因 |
|---|---|---|
| 移动应用 | gRPC | 高效的二进制编码,减小负载大小,提升电池使用效率 |
| 网页浏览器 | HTTP/2 | 原生浏览器支持,多路复用,服务器推送功能 |
🔄 gRPC 用于移动专用 API(例如,结账流程、购物车更新)。
服务端与数据库的交互
- 主路径:所有写操作和关键读取操作均发送至
db-prime-01. - 读取扩展:非关键读取操作(例如,产品详情、目录视图)被路由至
db-replica-02通过连接池逻辑。 - 备用路径:在主节点故障时,服务可切换至
db-replica-02(在图中标记为“备用”)。
📌 注意:写操作仍保持单主节点——不会将写操作拆分到副本。
缓存策略
- Redis 缓存键:
product:12345:details→ 缓存 5 分钟inventory:12345→ TTL:30 秒cart:session:abc123→ 会话特定,1 小时后过期
- 缓存失效:
- 在产品更新、库存变更或订单完成时触发。
- 通过消息队列(例如 Kafka)或直接的数据库触发器实现。
⚠️ 权衡:最终一致性——数据库更新与缓存同步之间存在轻微延迟。
复制与故障转移
- 主节点 → 副本节点:持续的 WAL(预写日志)流式传输。
- 故障转移触发:每 5 秒进行一次健康检查;通过编排器(例如 Patroni)自动执行。
- 恢复时间:约 30–60 秒将副本提升并重定向流量。
🧩 视觉提示:图中的“备用”标签和灰度样式强调了在正常情况下这是非主路径在正常情况下。
4. 关键架构决策与权衡
| 决策 | 理由 | 权衡 / 考虑 |
|---|---|---|
| 多语言后端(Java + Go) | Spring Boot 为订单处理提供了成熟的事务支持和生态系统。Go + Gin 为产品搜索提供了高吞吐量和低延迟。 | 运营复杂度增加:两个运行时环境、构建流水线、监控堆栈。 |
| 主节点 + 副本 PostgreSQL | 确保金融数据的 ACID 兼容性。复制功能支持读取扩展和灾难恢复。 | 单一写入主节点在极端写入高峰期间可能成为瓶颈。 |
| Redis 缓存层 | 分担频繁的产品读取请求;降低数据库负载并改善延迟。 | 缓存失效机制复杂;需要精心设计以避免数据过期。 |
| gRPC(移动端),HTTP/2(Web 端) | gRPC 非常适合移动端(数据包更小,解析更快)。HTTP/2 在浏览器中普遍支持。 | 双协议栈增加了开发和测试的开销。 |
| Nginx 反向代理 | 集中处理 SSL 终止、负载均衡、CORS 和限流。 | 除非以高可用模式部署,否则会引入单点故障(SPOF)。 |
| 标记的备用节点 | 清晰地标识故障转移路径,便于事故分析和新员工入职。 | 在基础设施变更期间,需要严格纪律来保持图表的更新。 |
5. 强调的非功能性特性
| 特性 | 实现方式 |
|---|---|
| 性能 | 高吞吐量的 Go 服务、Redis 缓存、gRPC 的高效性、HTTP/2 的多路复用 |
| 可用性 | 数据库复制、备用路径、冗余节点 |
| 可扩展性 | 通过副本实现读取扩展,服务具备横向扩展的潜力 |
| 可观测性 | 清晰的协议、流量体积指标、节点位置和标签 |
| 安全 | 强制启用SSL/TLS,应用CORS策略,数据库连接安全 |
| 可维护性 | C4图示由版本控制,具备自文档化特性,并与代码库保持一致 |
💡 这些特性并非默认存在——它们被明确地设计进部署结构中。
6. C4模型对齐与核心概念图示
此部署图是一个C4部署图的规范示例,C4模型(上下文、容器、组件、部署)四个层级之一。
✅ 核心C4部署图概念展示
| 概念 | 本图中的实现 |
|---|---|
| 部署节点 | 物理/虚拟服务器(api-gw-01, db-prime-01,等) |
| 容器实例 | 运行时服务(订单服务、产品服务、Redis、PostgreSQL)放置在节点内部 |
| 基础设施节点 | 隐含的负载均衡器(Nginx)、高速光纤网络、数据中心位置 |
| 关系 | 方向性箭头展示流量流向、协议(HTTP/2、gRPC、JDBC、Redis)以及故障转移逻辑 |
| 标签与样式 | "故障转移"标签及灰色样式用于db-replica-02 用于表示次要角色 |
| 属性 | 操作系统版本、软件版本、协议、流量规模、安全设置 |
| 环境聚焦 | 明确标注为“实时生产环境” |
🛠️ 遵循C4最佳实践
- 将容器映射到基础设施,而非重新创建组件逻辑。
- 嵌套结构:服务器 → 运行时 → 容器(例如,
api-gw-01→ Spring Boot → 订单服务)。 - 明确的故障转移和扩展路径 以可视化方式展示。
- 协议和技术 明确标注。
- 视觉提示(颜色、标签)用于区分主路径与备用路径。
- 元数据丰富 — 包括位置、版本和性能上下文。
📌 为何如此重要:此图回答了关键问题:
“这个系统在生产环境中实际运行在何处以及如何运行?”
它通过将高层级图示(例如,展示服务边界的容器图)建立在现实世界基础设施.
7. 结论与未来路线图
✅ 成功概要
- 该平台提供高性能, 弹性,以及开发者灵活性.
- 该C4 部署图充当动态文档资产,集成到CI/CD和版本控制中。
- 团队使用它来:
- 新工程师入职
- 事件响应与根本原因分析
- 容量规划与扩展决策
- 架构评审与合规性检查
🔮 未来增强
| 增强 | 优势 |
|---|---|
| 增加Kubernetes编排 | 支持自动扩展、自我修复和声明式部署 |
| 引入数据库分片 | 可突破单主节点限制,支持海量数据集扩展 |
| 增加可观测性节点 | 包含Prometheus、Grafana和OpenTelemetry导出器,实现全栈监控 |
| 创建预生产/测试环境图 | 支持环境特定的验证和变更管理 |
| 自动化图表生成 | 使用AI工具(例如Visual Paradigm的C4 PlantUML Studio)从代码或需求生成图表 |
🤖 像Visual Paradigm的C4 PlantUML Studio这样的AI驱动工具可以从自然语言描述中生成这些图表,加速文档编写并减少错误。
参考列表(Markdown格式)
- Visual Paradigm AI图表生成器:完整支持C4模型
发布说明,重点介绍由AI驱动的C4模型生成,包括系统全景图、上下文图、容器图和组件图。 - 关于AI驱动的C4 PlantUML Studio中的C4图表
全面概述AI如何生成C4图表,包括提示工程、输出验证以及企业应用场景。 - AI C4系统全景图生成器——Visual Paradigm指南
从自然语言输入生成系统全景图的逐步教程。 - Visual Paradigm C4 PlantUML Studio功能
官方功能页面,详细介绍AI生成、PlantUML集成、多层级图表支持以及协作工具。 - C4模型图表入门指南
通俗易懂地介绍C4模型的四个层级及其实际应用。 - C4 PlantUML Studio终极指南——革新软件架构设计
深入探讨AI辅助的架构设计如何为各类规模的团队变革工作流程。 - C4组件图:全面解析您代码内部结构的指南
强化了C4图表的层级结构,从系统全景图逐步细化到组件级别的细节。
最终思考
这个电子商务平台展示了如何现代软件架构可以清晰地传达, 在运营上高效,并且具有前瞻性——这一切都源于对C4 模型 和 PlantUML.
通过将部署图视为持续更新、版本控制的资产,组织可以:
- 缩短入职时间
- 加速事件响应
- 协调技术与业务利益相关方
- 自信地演进系统
🏁 架构文档的未来不仅仅是可视化——它更智能、自动化且高度集成。
借助像C4 PlantUML Studio这样的工具,团队可以从静态图示转向动态的、由人工智能增强的架构叙事——确保在整个软件生命周期中保持清晰性、一致性和连贯性。
📌 本案例研究是任何使用 C4 模型构建或记录生产级系统的团队的实用参考。请根据您的代码对其进行调整、扩展并持续维护。










