review-software-architecture

审查软件架构

从系统层面评估软件架构的质量属性、对设计原则的遵循情况以及长期可维护性。

适用场景

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

输入

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

流程

步骤 1：了解系统背景

梳理系统边界和接口：

## System Context
- **Name**: [System name]
- **Purpose**: [One-line description]
- **Users**: [Who uses it and how]
- **Scale**: [Requests/sec, data volume, user count]
- **Age**: [Years in production, major versions]
- **Team**: [Size, composition]

## External Dependencies
| Dependency | Type | Criticality | Notes |
|-----------|------|-------------|-------|
| PostgreSQL | Database | Critical | Primary data store |
| Redis | Cache | High | Session store + caching |
| Stripe | External API | Critical | Payment processing |
| S3 | Object storage | High | File uploads |

预期结果： 清晰了解系统的功能及其依赖项。 失败时： 如果缺少架构文档，则根据代码结构、配置和部署文件推导系统背景。

步骤 2：评估结构质量

耦合度评估

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

• 依赖方向：依赖是单向流动（分层）还是存在循环依赖？
• 接口边界：模块是通过定义好的接口／契约连接，还是直接引用具体实现？
• 共享状态：模块之间是否共享可变状态？
• 数据库耦合：多个服务是否直接读写同一张表？
• 时序耦合：操作是否必须按特定顺序进行，却没有明确的编排机制？

# 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 原则

原则	问题	警示信号
Single Responsibility（单一职责）	每个类／模块是否只有一个变更原因？	类中包含超过 5 个与无关事项相关的公共方法
Open/Closed（开闭原则）	是否可以在不修改现有代码的情况下扩展行为？	每增加一项功能，都要频繁修改核心类
Liskov Substitution（里氏替换）	子类型能否替换其基类型而不破坏行为？	消费者代码中散布着类型检查（instanceof）
Interface Segregation（接口隔离）	接口是否专注且精简？	“臃肿”的接口要求消费者实现未使用的方法
Dependency Inversion（依赖倒置）	高层模块是否依赖抽象，而非具体细节？	业务逻辑中直接实例化基础设施类

## SOLID Assessment
| Principle | Status | Evidence | Impact |
|-----------|--------|----------|--------|
| SRP | Concern | UserService handles auth, profile, notifications, and billing | High — changes to billing risk breaking auth |
| OCP | Good | Plugin system for payment providers | Low |
| LSP | Good | No type-checking anti-patterns found | Low |
| ISP | Concern | IRepository has 15 methods, most implementors use 3-4 | Medium |
| DIP | Concern | Controllers directly instantiate database repositories | Medium |

预期： 每项原则都至少结合一个具体示例进行评估。 未通过时： 并非所有原则都同等适用于每种架构风格。请指出相关性较低的原则（例如，ISP 在函数式代码库中的重要性较低）。

第 4 步：审查 API 设计

对于提供 API 的系统（REST、GraphQL、gRPC）：

• 一致性： 命名约定、错误格式和分页模式是否统一
• 版本控制： 是否制定并实施了策略（URL、标头、内容协商）
• 错误处理： 错误响应是否结构清晰、保持一致且不会泄露内部信息
• 身份验证／授权： 是否在 API 层正确执行
• 速率限制： 是否采取措施防止滥用
• 文档： 是否维护 OpenAPI/Swagger、GraphQL 架构或 protobuf 定义
• 幂等性： 可变更操作（POST/PUT）是否能安全处理重试

## API Design Review
| Aspect | Status | Notes |
|--------|--------|-------|
| Naming consistency | Good | RESTful resource naming throughout |
| Versioning | Concern | No versioning strategy — breaking changes affect all clients |
| Error format | Good | RFC 7807 Problem Details used consistently |
| Auth | Good | JWT with role-based scopes |
| Rate limiting | Missing | No rate limiting on any endpoint |
| Documentation | Concern | OpenAPI spec exists but 6 months out of date |

预期： 根据通用标准审查 API 设计，并提供具体发现。 未通过时： 如果未提供 API，请跳过此步骤，重点关注内部模块接口。

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

• 无状态性： 应用是否可以水平扩展（无本地状态）？
• 数据库可扩展性： 查询是否已建立索引？架构是否适合数据量？
• 缓存策略： 是否在适当层级应用缓存（数据库、应用、CDN）？
• 故障处理： 依赖不可用时会发生什么（熔断器、重试、回退）？
• 可观测性： 是否实现了日志、指标和追踪？
• 数据一致性： 最终一致性是否可接受，还是必须保证强一致性？

预期： 根据声明的非功能性需求评估可扩展性和可靠性。 未通过时： 如果未记录非功能性需求，建议将其定义为第一步。

第 6 步：评估技术债务

## Technical Debt Inventory
| Item | Severity | Impact | Estimated Effort | Recommendation |
|------|----------|--------|-----------------|----------------|
| No database migrations | High | Schema changes are manual and error-prone | 1 sprint | Adopt Alembic/Flyway |
| Monolithic test suite | Medium | Tests take 45 min, developers skip them | 2 sprints | Split into unit/integration/e2e |
| Hardcoded config values | Medium | Environment-specific values in source code | 1 sprint | Extract to env vars/config service |
| No CI/CD pipeline | High | Manual deployment prone to errors | 1 sprint | Set up GitHub Actions |

预期： 按严重程度、影响和工作量估算对技术债务进行分类。 未通过时： 如果债务清单过于庞大，请按影响／工作量比优先处理前 5 项。

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

如果存在 ADR，请评估：

• 决策是否明确说明了背景（要解决什么问题）
• 是否考虑并记录了备选方案
• 权衡是否明确
• 决策是否仍然有效（是否存在未记录的替代情况）
• 新的重大决策是否有 ADR

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

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

## Architecture Review Report

### Executive Summary
[2-3 sentences: overall health, key concerns, recommended actions]

### Strengths
1. [Specific architectural strength with evidence]
2. ...

### Concerns (by severity)

#### Critical
1. **[Title]**: [Description, impact, recommendation]

#### Major
1. **[Title]**: [Description, impact, recommendation]

#### Minor
1. **[Title]**: [Description, recommendation]

### Technical Debt Summary
[Top 5 debt items with prioritized recommendations]

### Recommended Next Steps
1. [Actionable recommendation with clear scope]
2. ...

预期： 审查报告应具有可操作性，并按优先级排列建议。 未通过时： 如果审查有时间限制，请明确说明已审查的内容以及尚未评估的部分。

验证

• 已记录系统上下文（用途、规模、依赖项、团队）
• 已通过具体代码示例评估耦合度和内聚性
• 已在适用时评估 SOLID 原则
• 已审查 API 设计（如适用）
• 已根据需求评估可扩展性和可靠性
• 已整理技术债务并确定优先级
• 已审查 ADR，或注明缺少 ADR
• 建议具体、优先级明确且可执行

常见陷阱

• 审查代码而非架构：此技能关注系统级设计，而非逐行代码质量。PR 级反馈请使用 code-reviewer。
• 指定特定技术：架构审查应指出问题，而非强制指定特定工具，除非有明确的技术理由。
• 忽视团队背景：适合 3 人团队的“最佳”架构，与适合 30 人团队的架构不同。请考虑组织约束。
• 追求完美：每个系统都有技术债务。重点关注正在造成困扰或阻碍未来工作的债务。
• 臆测规模：不要建议为服务 100 名用户的应用采用分布式系统。架构应与实际需求相符。

相关技能

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