architecture

# 架构设计技能

本技能提供架构设计的完整指南，包括 ADR 记录、设计检查清单、可扩展性评估、架构模式速查等最佳实践。

## 架构决策记录 (ADR)

对于重要的架构决策，创建 ADR 记录：

### ADR 模板 (`docs/decisions/ADR-XXX.md`)

```markdown
# ADR-XXX: [决策标题]

## 状态

Proposed | Accepted | Deprecated | Superseded by ADR-YYY

## 上下文

[描述导致这个决策的背景、问题或需求]

## 决策

[明确说明做出的决策]

## 理由

[解释为什么选择这个方案]

## 备选方案

### 方案 A: [名称]

- 优点: ...
- 缺点: ...

### 方案 B: [名称]

- 优点: ...
- 缺点: ...

## 后果

### 正面

- [好处1]
- [好处2]

### 负面

- [代价1]
- [代价2]

### 风险

- [风险1] → 缓解: [措施]

## 相关决策

- ADR-XXX: [相关决策]

## 日期

YYYY-MM-DD
```

### 何时创建 ADR

| 场景                           | 是否需要 ADR  |
| ------------------------------ | ------------- |
| 选择主要技术栈（框架、数据库） | ✅ 必须       |
| 定义核心架构模式               | ✅ 必须       |
| 引入新的外部依赖               | ⚠️ 视影响范围 |
| API 设计重大变更               | ✅ 必须       |
| 简单的实现细节                 | ❌ 不需要     |

---

## 系统设计检查清单

设计方案前，检查以下维度：

### 功能性需求

- [ ] 用户故事是否清晰完整
- [ ] API 契约是否定义明确
- [ ] 数据模型是否满足需求
- [ ] 边界条件是否考虑

### 非功能性需求

- [ ] **性能**: 响应时间目标？吞吐量要求？
- [ ] **可扩展性**: 预期用户量？数据增长？
- [ ] **可用性**: 可接受的停机时间？
- [ ] **安全性**: 认证授权？数据保护？

### 技术设计

- [ ] 架构图是否清晰
- [ ] 组件职责是否明确
- [ ] 数据流是否完整
- [ ] 错误处理策略是否定义
- [ ] 测试策略是否规划

### 运维考虑

- [ ] 部署策略是否明确
- [ ] 监控告警是否规划
- [ ] 日志策略是否定义
- [ ] 回滚方案是否准备

---

## 可扩展性评估

### 扩展阶段规划

| 阶段   | 用户量   | 架构要求                   |
| ------ | -------- | -------------------------- |
| MVP    | <1K      | 单体应用足够               |
| 成长期 | 1K-10K   | 优化数据库查询，添加缓存   |
| 扩展期 | 10K-100K | 服务拆分，读写分离         |
| 规模化 | >100K    | 微服务，分布式缓存，多区域 |

### 常见瓶颈与解决方案

| 瓶颈         | 解决方案                     |
| ------------ | ---------------------------- |
| 数据库读取慢 | 索引优化 → 读写分离 → 缓存层 |
| API 响应慢   | 异步处理 → 消息队列 → CDN    |
| 内存不足     | 分页加载 → 流式处理 → 扩容   |
| 并发冲突     | 乐观锁 → 分布式锁 → 事件溯源 |

---

## 架构模式速查

### 后端模式

| 模式       | 适用场景         | 复杂度 |
| ---------- | ---------------- | ------ |
| 分层架构   | 大多数 CRUD 应用 | 低     |
| 六边形架构 | 需要高可测试性   | 中     |
| CQRS       | 读写负载差异大   | 高     |
| 事件溯源   | 需要完整审计轨迹 | 高     |
| 微服务     | 团队多、规模大   | 高