c4-architecture

C4架构文档

使用Mermaid语法的C4模型图生成软件架构文档。

工作流程

1. 理解范围 - 根据受众确定所需的C4层级
2. 分析代码库 - 探索系统以识别组件、容器和关系
3. 生成图表 - 在适当的抽象级别创建Mermaid C4图
4. 文档化 - 将图表写入Markdown文件并附上解释性上下文

C4图表层级

根据文档需求选择合适的层级：

层级	图表类型	受众	展示内容	何时创建
1	C4Context	所有人	系统 + 外部参与者	始终（必需）
2	C4Container	技术人员	应用、数据库、服务	始终（必需）
3	C4Component	开发者	内部组件	仅当增加价值时
4	C4Deployment	DevOps	基础设施节点	用于生产系统
-	C4Dynamic	技术人员	请求流（编号）	用于复杂工作流

关键洞察： “上下文+容器图对大多数软件开发团队来说已经足够。” 仅在真正增加价值时才创建组件/代码图。

快速入门示例

系统上下文（层级1）

C4Context
  title 系统上下文 - 健身追踪器

  Person(user, "用户", "记录锻炼和运动")
  System(app, "健身追踪器", "用于记录力量和CrossFit锻炼的Vue PWA")
  System_Ext(browser, "Web浏览器", "将数据存储在IndexedDB中")

  Rel(user, app, "使用")
  Rel(app, browser, "持久化数据到", "IndexedDB")

容器图（层级2）

C4Container
  title 容器图 - 健身追踪器

  Person(user, "用户", "记录锻炼")

  Container_Boundary(app, "健身追踪器 PWA") {
    Container(spa, "SPA", "Vue 3, TypeScript", "单页应用")
    Container(pinia, "状态管理", "Pinia", "管理应用状态")
    ContainerDb(indexeddb, "IndexedDB", "Dexie", "本地锻炼存储")
  }

  Rel(user, spa, "使用")
  Rel(spa, pinia, "读写状态")
  Rel(pinia, indexeddb, "持久化", "Dexie ORM")

组件图（层级3）

C4Component
  title 组件图 - 锻炼功能

  Container(views, "视图", "Vue Router页面")

  Container_Boundary(workout, "锻炼功能") {
    Component(useWorkout, "useWorkout", "Composable", "锻炼执行状态")
    Component(useTimer, "useTimer", "Composable", "计时器状态机")
    Component(workoutRepo, "WorkoutRepository", "Dexie", "锻炼持久化")
  }

  Rel(views, useWorkout, "使用")
  Rel(useWorkout, useTimer, "控制")
  Rel(useWorkout, workoutRepo, "保存到")

动态图（请求流）

C4Dynamic
  title 动态图 - 用户登录流程

  ContainerDb(db, "数据库", "PostgreSQL", "用户凭证")
  Container(spa, "单页应用", "React", "银行UI")

  Container_Boundary(api, "API应用") {
    Component(signIn, "登录控制器", "Express", "认证端点")
    Component(security, "安全服务", "JWT", "验证凭证")
  }

  Rel(spa, signIn, "1. 提交凭证", "JSON/HTTPS")
  Rel(signIn, security, "2. 验证")
  Rel(security, db, "3. 查询用户", "SQL")

  UpdateRelStyle(spa, signIn, $textColor="blue", $offsetY="-30")

部署图

C4Deployment
  title 部署图 - 生产环境

  Deployment_Node(browser, "客户浏览器", "Chrome/Firefox") {
    Container(spa, "SPA", "React", "Web应用")
  }

  Deployment_Node(aws, "AWS云", "us-east-1") {
    Deployment_Node(ecs, "ECS集群", "Fargate") {
      Container(api, "API服务", "Node.js", "REST API")
    }
    Deployment_Node(rds, "RDS", "db.r5.large") {
      ContainerDb(db, "数据库", "PostgreSQL", "应用数据")
    }
  }

  Rel(spa, api, "API调用", "HTTPS")
  Rel(api, db, "读写", "JDBC")

元素语法

人员和系统

Person(alias, "标签", "描述")
Person_Ext(alias, "标签", "描述")       # 外部人员
System(alias, "标签", "描述")
System_Ext(alias, "标签", "描述")       # 外部系统
SystemDb(alias, "标签", "描述")         # 数据库系统
SystemQueue(alias, "标签", "描述")      # 队列系统

容器

Container(alias, "标签", "技术", "描述")
Container_Ext(alias, "标签", "技术", "描述")
ContainerDb(alias, "标签", "技术", "描述")
ContainerQueue(alias, "标签", "技术", "描述")

组件

Component(alias, "标签", "技术", "描述")
Component_Ext(alias, "标签", "技术", "描述")
ComponentDb(alias, "标签", "技术", "描述")

边界

Enterprise_Boundary(alias, "标签") { ... }
System_Boundary(alias, "标签") { ... }
Container_Boundary(alias, "标签") { ... }
Boundary(alias, "标签", "类型") { ... }

关系

Rel(from, to, "标签")
Rel(from, to, "标签", "技术")
BiRel(from, to, "标签")                        # 双向
Rel_U(from, to, "标签")                        # 向上
Rel_D(from, to, "标签")                        # 向下
Rel_L(from, to, "标签")                        # 向左
Rel_R(from, to, "标签")                        # 向右

部署节点

Deployment_Node(alias, "标签", "类型", "描述") { ... }
Node(alias, "标签", "类型", "描述") { ... }  # 简写

样式和布局

布局配置

UpdateLayoutConfig($c4ShapeInRow="3", $c4BoundaryInRow="1")

• $c4ShapeInRow - 每行形状数（默认：4）
• $c4BoundaryInRow - 每行边界数（默认：2）

元素样式

UpdateElementStyle(alias, $fontColor="red", $bgColor="grey", $borderColor="red")

关系样式

UpdateRelStyle(from, to, $textColor="blue", $lineColor="blue", $offsetX="5", $offsetY="-10")

使用 $offsetX 和 $offsetY 修复重叠的关系标签。

最佳实践

基本规则

1. 每个元素必须包含：名称、类型、技术（如适用）和描述
2. 仅使用单向箭头 - 双向箭头会造成歧义
3. 用动作动词标记箭头 - “使用...发送邮件”、“从...读取”，而不仅仅是“使用”
4. 包含技术标签 - “JSON/HTTPS”、“JDBC”、“gRPC”
5. 每个图表不超过20个元素 - 将复杂系统拆分为多个图表

清晰度指南

1. 从层级1开始 - 上下文图有助于界定系统范围
2. 每个文件一个图表 - 保持图表专注于单一抽象层级
3. 有意义的别名 - 使用描述性别名（例如 orderService 而不是 s1）
4. 简洁的描述 - 尽可能将描述控制在50个字符以内
5. 始终包含标题 - “[系统名称]的系统上下文图”

应避免的事项

参见 references/common-mistakes.md 了解详细的反模式：

• 混淆容器（可部署）和组件（不可部署）
• 将共享库建模为容器
• 将消息代理显示为单个容器而不是单独的主题
• 添加未定义的抽象层级，如“子组件”
• 移除类型标签以“简化”图表

微服务指南

单团队所有权

将每个微服务建模为一个容器（或容器组）：

C4Container
  title 微服务 - 单团队

  System_Boundary(platform, "电商平台") {
    Container(orderApi, "订单服务", "Spring Boot", "订单处理")
    ContainerDb(orderDb, "订单数据库", "PostgreSQL", "订单数据")
    Container(inventoryApi, "库存服务", "Node.js", "库存管理")
    ContainerDb(inventoryDb, "库存数据库", "MongoDB", "库存数据")
  }

多团队所有权

当微服务由不同团队拥有时，将其提升为软件系统：

C4Context
  title 微服务 - 多团队

  Person(customer, "客户", "下订单")
  System(orderSystem, "订单系统", "Alpha团队")
  System(inventorySystem, "库存系统", "Beta团队")
  System(paymentSystem, "支付系统", "Gamma团队")

  Rel(customer, orderSystem, "下订单")
  Rel(orderSystem, inventorySystem, "检查库存")
  Rel(orderSystem, paymentSystem, "处理支付")

事件驱动架构

将各个主题/队列显示为容器，而不是单个“Kafka”框：

C4Container
  title 事件驱动架构

  Container(orderService, "订单服务", "Java", "创建订单")
  Container(stockService, "库存服务", "Java", "管理库存")
  ContainerQueue(orderTopic, "order.created", "Kafka", "订单事件")
  ContainerQueue(stockTopic, "stock.reserved", "Kafka", "库存事件")

  Rel(orderService, orderTopic, "发布到")
  Rel(stockService, orderTopic, "订阅")
  Rel(stockService, stockTopic, "发布到")
  Rel(orderService, stockTopic, "订阅")

输出位置

将架构文档写入 docs/architecture/，命名约定如下：

• c4-context.md - 系统上下文图
• c4-containers.md - 容器图
• c4-components-{feature}.md - 每个功能的组件图
• c4-deployment.md - 部署图
• c4-dynamic-{flow}.md - 特定流程的动态图

面向受众的细节

受众	推荐图表
高管	仅系统上下文
产品经理	上下文 + 容器
架构师	上下文 + 容器 + 关键组件
开发者	根据需要所有层级
DevOps	容器 + 部署

参考资料

• references/c4-syntax.md - 完整的Mermaid C4语法
• references/common-mistakes.md - 应避免的反模式
• references/advanced-patterns.md - 微服务、事件驱动、部署