软件架构评审

在系统层面评估软件架构的质量属性、设计原则遵守情况和长期可维护性。

适用场景

• 在实施开始前评估拟议架构
• 评估现有系统的可扩展性、可维护性或安全性
• 审查项目的架构决策记录（ADR）
• 进行技术债务评估
• 评估系统是否准备好进行重大规模扩展或功能扩展
• 与行级代码审查区分（行级代码审查侧重于 PR 级别的变更）

输入

• 必填：系统代码库或架构文档（图表、ADR、README）
• 必填：系统目的、规模和约束的背景信息
• 可选：非功能性需求（延迟、吞吐量、可用性目标）
• 可选：团队规模和技能构成
• 可选：技术约束或偏好
• 可选：已知痛点或关注领域

步骤

第 1 步：了解系统背景

绘制系统边界和接口：

## 系统背景
- **名称**：[系统名称]
- **目的**：[一句话描述]
- **用户**：[谁在使用及如何使用]
- **规模**：[请求数/秒、数据量、用户数]
- **年龄**：[生产年数、主要版本]
- **团队**：[规模、构成]

## 外部依赖
| 依赖项 | 类型 | 关键性 | 备注 |
|--------|------|--------|------|
| PostgreSQL | 数据库 | 关键 | 主数据存储 |
| Redis | 缓存 | 高 | 会话存储 + 缓存 |
| Stripe | 外部 API | 关键 | 支付处理 |
| S3 | 对象存储 | 高 | 文件上传 |

预期结果： 清楚了解系统功能及其依赖关系。

失败处理： 若架构文档缺失，从代码结构、配置和部署文件推断背景。

第 2 步：评估结构质量

耦合度评估

检查模块之间的依赖紧密程度：

• 依赖方向：依赖关系是单向流动（分层）还是循环？
• 接口边界：模块是通过定义的接口/契约连接，还是直接引用实现？
• 共享状态：模块间是否共享可变状态？
• 数据库耦合：多个服务是否直接读写同一张表？
• 时序耦合：操作是否必须按特定顺序发生，却没有显式的编排？

# 检测循环依赖（JavaScript/TypeScript）
npx madge --circular src/

# 检测导入模式（Python）
# 查找深层跨包导入
grep -r "from app\." --include="*.py" | sort | uniq -c | sort -rn | head -20

内聚性评估

评估每个模块是否有单一明确的职责：

• 模块命名：名称是否准确描述了模块的功能？
• 文件大小：文件或类是否过大（>500 行表明有多个职责）？
• 变更频率：不相关的功能是否需要修改同一模块？
• 上帝对象：是否存在所有东西都依赖的类/模块？

耦合级别	描述	示例
低（好）	模块通过接口通信	服务 A 调用服务 B 的 API
中	模块共享数据结构	共享 DTO/模型库
高（关注）	模块引用彼此的内部实现	跨模块直接数据库访问
病理性	模块修改彼此的内部状态	全局可变状态

预期结果： 耦合度和内聚性已评估，并附有来自代码库的具体示例。

失败处理： 若代码库太大无法手动审查，抽样 3-5 个关键模块和变更最频繁的文件。

第 3 步：评估 SOLID 原则

原则	问题	危险信号
单一职责	每个类/模块是否只有一个变更原因？	类中有 >5 个关于不相关问题的公共方法
开放/封闭	是否可以在不修改现有代码的情况下扩展行为？	每次新功能都频繁修改核心类
里氏替换	子类型是否可以替换其基类型而不破坏行为？	消费者代码中散布着类型检查（instanceof）
接口隔离	接口是否聚焦且最小化？	"臃肿"接口，消费者实现了未使用的方法
依赖倒置	高层模块是否依赖于抽象而非细节？	业务逻辑中直接实例化基础设施类

## SOLID 评估
| 原则 | 状态 | 证据 | 影响 |
|------|------|------|------|
| SRP | 关注 | UserService 处理认证、个人资料、通知和计费 | 高——对计费的修改可能影响认证 |
| OCP | 良好 | 支付提供商的插件系统 | 低 |
| LSP | 良好 | 未发现类型检查反模式 | 低 |
| ISP | 关注 | IRepository 有 15 个方法，大多数实现者只使用 3-4 个 | 中 |
| DIP | 关注 | 控制器直接实例化数据库仓库 | 中 |

预期结果： 每个原则均已评估，并附有至少一个具体示例。

失败处理： 并非所有原则都同等适用于每种架构风格。注意某个原则不太相关的情况（如 ISP 在函数式代码库中重要性较低）。

第 4 步：审查 API 设计

对于暴露 API 的系统（REST、GraphQL、gRPC）：

• 一致性：命名约定、错误格式、分页模式统一
• 版本控制：策略存在并已应用（URL、请求头、内容协商）
• 错误处理：错误响应结构化、一致，且不泄露内部信息
• 认证/授权：在 API 层正确执行
• 速率限制：防止滥用的保护措施
• 文档：OpenAPI/Swagger、GraphQL 架构或 protobuf 定义已维护
• 幂等性：修改操作（POST/PUT）安全地处理重试

## API 设计审查
| 方面 | 状态 | 备注 |
|------|------|------|
| 命名一致性 | 良好 | 全程使用 RESTful 资源命名 |
| 版本控制 | 关注 | 无版本控制策略——破坏性变更影响所有客户端 |
| 错误格式 | 良好 | 一致使用 RFC 7807 问题详情 |
| 认证 | 良好 | 带基于角色的作用域的 JWT |
| 速率限制 | 缺失 | 任何端点都没有速率限制 |
| 文档 | 关注 | OpenAPI 规范存在但已 6 个月未更新 |

预期结果： API 设计已对照通用标准进行审查，并有具体发现。

失败处理： 若未暴露 API，跳过此步骤，专注于内部模块接口。

第 5 步：评估可扩展性和可靠性

• 无状态性：应用程序是否可以水平扩展（无本地状态）？
• 数据库可扩展性：查询是否有索引？模式是否适合数据量？
• 缓存策略：是否在适当层次应用了缓存（数据库、应用程序、CDN）？
• 故障处理：依赖项不可用时会发生什么（熔断器、重试、降级）？
• 可观测性：是否实现了日志、指标和追踪？
• 数据一致性：最终一致性是否可接受，还是需要强一致性？

预期结果： 可扩展性和可靠性已相对于所述的非功能性需求进行评估。

失败处理： 若非功能性需求未记录，建议将其定义为第一步。

第 6 步：评估技术债务

## 技术债务清单
| 项目 | 严重性 | 影响 | 预估工作量 | 建议 |
|------|--------|------|-----------|------|
| 无数据库迁移 | 高 | 架构变更是手动且容易出错的 | 1 个迭代 | 采用 Alembic/Flyway |
| 单体测试套件 | 中 | 测试需要 45 分钟，开发者会跳过 | 2 个迭代 | 拆分为单元/集成/e2e |
| 硬编码配置值 | 中 | 特定环境的值在源代码中 | 1 个迭代 | 提取到环境变量/配置服务 |
| 无 CI/CD 流水线 | 高 | 手动部署容易出错 | 1 个迭代 | 设置 GitHub Actions |

预期结果： 技术债务已编目，附严重性、影响和工作量估计。

失败处理： 若债务清单压倒性地多，优先处理影响/工作量比最高的前 5 项。

第 7 步：审查架构决策记录（ADR）

若 ADR 存在，评估：

• 决策有清晰的背景（解决什么问题）
• 已考虑并记录了替代方案
• 权衡是明确的
• 决策仍然是最新的（未在没有文档的情况下被取代）
• 新的重要决策有 ADR

若 ADR 不存在，建议为关键决策建立 ADR。

第 8 步：撰写架构评审报告

## 架构评审报告

### 执行摘要
[2-3 句：整体健康状况、主要问题、建议行动]

### 优点
1. [具体的架构优势及证据]
2. ...

### 问题（按严重性）

#### 严重
1. **[标题]**：[描述、影响、建议]

#### 重大
1. **[标题]**：[描述、影响、建议]

#### 次要
1. **[标题]**：[描述、建议]

### 技术债务摘要
[前 5 项债务，附优先级建议]

### 建议的后续步骤
1. [范围明确的可操作建议]
2. ...

预期结果： 评审报告具有可操作性，附有优先级建议。

失败处理： 若评审有时间限制，清楚说明已覆盖的内容和尚未评估的内容。

验证清单

• 系统背景已记录（目的、规模、依赖关系、团队）
• 耦合度和内聚性已评估，附具体代码示例
• SOLID 原则已在适用情况下评估
• API 设计已审查（如适用）
• 可扩展性和可靠性已对照需求评估
• 技术债务已编目并排定优先级
• ADR 已审查或其缺失已注明
• 建议具体、有优先级且可操作

常见问题

• 审查代码而非架构：此技能关注系统级设计，而非行级代码质量。PR 级别的反馈请使用 code-reviewer。
• 规定具体技术：架构评审应识别问题，而非强制规定具体工具，除非有明确的技术原因。
• 忽视团队背景："最佳"架构对 3 人团队和 30 人团队不同。考虑组织约束。
• 完美主义：每个系统都有技术债务。关注正在积极造成痛苦或阻碍未来工作的债务。
• 假设规模：不要为服务 100 个用户的应用推荐分布式系统。将架构与实际需求匹配。

相关技能

• security-audit-codebase — 以安全为重点的代码和配置审查
• configure-git-repository — 仓库结构和约定
• design-serialization-schema — 数据模式设计和演进
• review-data-analysis — 分析正确性审查（互补视角）