# Review Software Architecture

> 审查软件架构的耦合度、内聚性、SOLID 原则、API 设计、可扩展性和技术债务。 涵盖系统级评估、架构决策记录审查和改进建议。适用于在实施前评估拟议架构、 评估现有系统的可扩展性或安全性、审查 ADR、进行技术债务评估，或评估系统是否 准备好进行重大规模扩展。

- Skill: `pjt222/review-software-architecture-4` (Agent Skill)
- Install (CLI): `npx skillmds@latest add pjt222/review-software-architecture-4`
- Raw SKILL.md: https://api.skillmd.com/api/skills/pjt222/review-software-architecture-4/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- License: MIT
- Author: pjt222 (https://skillmd.com/u/pjt222)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/pjt222/review-software-architecture-4

---


# 软件架构评审

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

## 适用场景

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

## 输入

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

## 步骤

### 第 1 步：了解系统背景

绘制系统边界和接口：

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

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

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

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

### 第 2 步：评估结构质量

#### 耦合度评估
检查模块之间的依赖紧密程度：

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

```bash
# Detect circular dependencies (JavaScript/TypeScript)
npx madge --circular src/

# Detect import patterns (Python)
# Look for deep cross-package imports
grep -r "from app\." --include="*.py" | sort | uniq -c | sort -rn | head -20
```

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

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

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

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

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

### 第 3 步：评估 SOLID 原则

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

```markdown
## 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）安全地处理重试

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

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

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

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

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

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

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

### 第 6 步：评估技术债务

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

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

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

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

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

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

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

```markdown
## 架构评审报告

### 执行摘要
[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` — 分析正确性审查（互补视角）