1. 为什么我们需要架构图记录

在技术团队协作中，架构图就像建筑行业的施工蓝图。我经历过无数次这样的场景：某个核心服务突然出现性能问题，团队成员围在一起讨论解决方案时，有人问"这个模块当初为什么这样设计？"，结果发现当初的设计文档早已过时，参与原始架构设计的人员也已离职。

架构图记录的价值主要体现在三个方面：

1. 知识传承：避免"人走茶凉"的知识断层，新成员能快速理解系统全貌
2. 问题排查：当系统出现故障时，清晰的架构图能帮助快速定位问题边界
3. 演进规划：在系统迭代时，现有架构图是讨论改进方案的基础依据

提示：架构图不是一次性的工作成果，而是需要持续维护的"活文档"。我建议至少每季度做一次架构图review，确保其与线上系统保持一致。

2. 架构图应该包含哪些核心要素

2.1 基础组件与依赖关系

一个完整的架构图至少应该包含以下元素：

• 系统边界（明确哪些在系统内/外）
• 核心服务/模块及其职责
• 数据流向（请求/响应路径）
• 关键依赖（数据库、中间件、第三方服务）
• 部署拓扑（物理/逻辑部署结构）

以电商系统为例，典型的分层架构可能包括：

用户层 → 接入层 → 业务服务层 → 数据服务层 → 存储层 ↘ 中间件层 ↗

2.2 非功能性标注

除了基础结构，建议在架构图中标注：

• SLA要求（如99.9%可用性）
• 流量预估（如QPS峰值）
• 数据规模（如日订单量）
• 安全边界（需要特殊防护的模块）

我在实际工作中发现，很多团队只画"静态"架构图，忽略了这些动态指标，导致后续容量规划时缺乏依据。

3. 架构图的版本管理实践

3.1 版本控制策略

架构图应该像代码一样纳入版本管理。我的团队采用以下实践：

1. 使用Git管理.drawio/.vsdx源文件
2. 每次重大架构变更都打tag
3. 在README中记录变更日志
4. 导出PNG/SVG时包含版本号水印

示例版本命名规则：

v[主版本].[迭代版本].[修订版本]-[环境] 如：v2.3.1-prod

3.2 变更diff机制

对于复杂系统，建议：

• 使用Beyond Compare等工具对比不同版本
• 在架构评审会议前生成变更对比图
• 对不兼容变更用红色高亮显示

我们曾因为忽略了一个Redis集群拓扑的微小变更，导致缓存雪崩。现在严格要求所有中间件变更都必须体现在架构图中。

4. 架构图工具链选型

4.1 绘图工具对比

4.2 我的工具组合方案

经过多次迭代，我现在采用：

1. 设计阶段：用Excalidraw画草图（快速原型）
2. 定稿阶段：用Draw.io制作正式图（平衡功能与成本）
3. 文档化阶段：导出矢量图嵌入Confluence（保留缩放清晰度）
4. 代码映射：使用Go Diagrams生成部分基础设施图（保持与代码一致）

特别提醒：避免使用PPT画架构图。我们曾因此导致图形元素散落各处，后续维护极其困难。

5. 架构图与文档的联动

5.1 文档化标准

好的架构图需要配套文档说明：

• 设计决策记录（ADR）：为什么选择这个架构
• 演进路线图：未来3-6个月的改造计划
• 异常处理矩阵：各模块的故障处理策略

建议采用轻量级模板：

## [模块名] 设计说明 ### 职责范围 - 负责处理XX请求 - 不处理YY场景 ### 关键依赖 1. 服务A（强依赖） 2. 数据库B（弱依赖） ### 性能指标 - 平均延迟：<200ms - 吞吐量：1000QPS

5.2 自动化文档方案

我最近在尝试的进阶实践：

1. 使用Swagger UI展示API架构
2. 通过Terraform生成基础设施图
3. 用ArgoCD可视化部署拓扑
4. 集成Prometheus指标到架构图

这样当系统实际运行指标偏离设计值时，架构图可以自动预警（如用颜色标注热点模块）。

6. 架构图评审的常见陷阱

6.1 典型问题清单

根据我的复盘记录，架构图评审中最常出现：

• 混淆逻辑架构与物理部署（画在一起导致混乱）
• 遗漏故障转移路径（只画了happy path）
• 过度简化（隐藏了关键细节）
• 过度复杂（包含无关实现细节）

6.2 有效的评审方法

我们现在的改进做法：

1. 角色扮演法：让评审者模拟不同用户视角（运维、开发、产品）
2. 故障注入讨论：随机去掉图中某个组件，讨论影响面
3. 流量推演：用便签纸模拟请求流转路径
4. 版本对比：必须展示与上一版本的diff

最近一次评审中，通过模拟支付服务宕机，我们发现原架构图没有体现降级方案，及时补充了备用通道设计。

7. 架构图的知识管理

7.1 分类存储方案

建议按以下维度组织架构图：

/docs /architecture /system-overview # 系统概览 /service-design # 服务设计 /data-flow # 数据流向 /deployment # 部署拓扑 /historical # 历史版本

7.2 权限控制要点

根据经验，需要注意：

• 源文件编辑权限严格控制
• 对外分享只提供PDF版本
• 敏感信息（如内网IP）使用占位符
• 离职员工及时回收权限

我们曾发生过前员工在外网泄露包含真实IP的架构图，导致安全事件。现在所有对外文档都会用自动化工具脱敏。