1. 为什么我们需要架构图记录
在技术团队协作中，架构图就像建筑行业的施工蓝图。我经历过无数次这样的场景：某个核心服务突然出现性能问题，团队成员围在一起讨论解决方案时，有人问"这个模块当初为什么这样设计？"，结果发现当初的设计文档早已过时，参与原始架构设计的人员也已离职。
架构图记录的价值主要体现在三个方面：
- 知识传承：避免"人走茶凉"的知识断层，新成员能快速理解系统全貌
- 问题排查：当系统出现故障时，清晰的架构图能帮助快速定位问题边界
- 演进规划：在系统迭代时，现有架构图是讨论改进方案的基础依据
提示：架构图不是一次性的工作成果，而是需要持续维护的"活文档"。我建议至少每季度做一次架构图review，确保其与线上系统保持一致。
2. 架构图应该包含哪些核心要素
2.1 基础组件与依赖关系
一个完整的架构图至少应该包含以下元素：
- 系统边界（明确哪些在系统内/外）
- 核心服务/模块及其职责
- 数据流向（请求/响应路径）
- 关键依赖（数据库、中间件、第三方服务）
- 部署拓扑（物理/逻辑部署结构）
以电商系统为例，典型的分层架构可能包括：
用户层 → 接入层 → 业务服务层 → 数据服务层 → 存储层 ↘ 中间件层 ↗2.2 非功能性标注
除了基础结构，建议在架构图中标注：
- SLA要求（如99.9%可用性）
- 流量预估（如QPS峰值）
- 数据规模（如日订单量）
- 安全边界（需要特殊防护的模块）
我在实际工作中发现，很多团队只画"静态"架构图，忽略了这些动态指标，导致后续容量规划时缺乏依据。
3. 架构图的版本管理实践
3.1 版本控制策略
架构图应该像代码一样纳入版本管理。我的团队采用以下实践：
- 使用Git管理.drawio/.vsdx源文件
- 每次重大架构变更都打tag
- 在README中记录变更日志
- 导出PNG/SVG时包含版本号水印
示例版本命名规则：
v[主版本].[迭代版本].[修订版本]-[环境] 如：v2.3.1-prod3.2 变更diff机制
对于复杂系统，建议：
- 使用Beyond Compare等工具对比不同版本
- 在架构评审会议前生成变更对比图
- 对不兼容变更用红色高亮显示
我们曾因为忽略了一个Redis集群拓扑的微小变更，导致缓存雪崩。现在严格要求所有中间件变更都必须体现在架构图中。
4. 架构图工具链选型
4.1 绘图工具对比
| 工具 | 优点 | 缺点 | 适用场景 |
|---|---|---|---|
| Draw.io | 免费、协作方便 | 复杂图形支持有限 | 中小型项目 |
| Visio | 专业、模板丰富 | 收费、Mac支持差 | 企业级文档 |
| PlantUML | 代码化、版本友好 | 学习曲线陡峭 | DevOps流程 |
| Miro | 实时协作体验好 | 导出格式受限 | 远程团队头脑风暴 |
4.2 我的工具组合方案
经过多次迭代，我现在采用：
- 设计阶段：用Excalidraw画草图（快速原型）
- 定稿阶段：用Draw.io制作正式图（平衡功能与成本）
- 文档化阶段：导出矢量图嵌入Confluence（保留缩放清晰度）
- 代码映射：使用Go Diagrams生成部分基础设施图（保持与代码一致）
特别提醒：避免使用PPT画架构图。我们曾因此导致图形元素散落各处，后续维护极其困难。
5. 架构图与文档的联动
5.1 文档化标准
好的架构图需要配套文档说明：
- 设计决策记录（ADR）：为什么选择这个架构
- 演进路线图：未来3-6个月的改造计划
- 异常处理矩阵：各模块的故障处理策略
建议采用轻量级模板：
## [模块名] 设计说明 ### 职责范围 - 负责处理XX请求 - 不处理YY场景 ### 关键依赖 1. 服务A（强依赖） 2. 数据库B（弱依赖） ### 性能指标 - 平均延迟：<200ms - 吞吐量：1000QPS5.2 自动化文档方案
我最近在尝试的进阶实践：
- 使用Swagger UI展示API架构
- 通过Terraform生成基础设施图
- 用ArgoCD可视化部署拓扑
- 集成Prometheus指标到架构图
这样当系统实际运行指标偏离设计值时，架构图可以自动预警（如用颜色标注热点模块）。
6. 架构图评审的常见陷阱
6.1 典型问题清单
根据我的复盘记录，架构图评审中最常出现：
- 混淆逻辑架构与物理部署（画在一起导致混乱）
- 遗漏故障转移路径（只画了happy path）
- 过度简化（隐藏了关键细节）
- 过度复杂（包含无关实现细节）
6.2 有效的评审方法
我们现在的改进做法：
- 角色扮演法：让评审者模拟不同用户视角（运维、开发、产品）
- 故障注入讨论：随机去掉图中某个组件，讨论影响面
- 流量推演：用便签纸模拟请求流转路径
- 版本对比：必须展示与上一版本的diff
最近一次评审中，通过模拟支付服务宕机，我们发现原架构图没有体现降级方案，及时补充了备用通道设计。
7. 架构图的知识管理
7.1 分类存储方案
建议按以下维度组织架构图：
/docs /architecture /system-overview # 系统概览 /service-design # 服务设计 /data-flow # 数据流向 /deployment # 部署拓扑 /historical # 历史版本7.2 权限控制要点
根据经验，需要注意：
- 源文件编辑权限严格控制
- 对外分享只提供PDF版本
- 敏感信息（如内网IP）使用占位符
- 离职员工及时回收权限
我们曾发生过前员工在外网泄露包含真实IP的架构图，导致安全事件。现在所有对外文档都会用自动化工具脱敏。
