# architecture-design

**Repository Path**: zyh-soft/architecture-design

## Basic Information

- **Project Name**: architecture-design
- **Description**: 系统化地设计软件系统架构，为后续的详细设计和实现提供清晰的蓝图。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-06-07
- **Last Updated**: 2026-07-25

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

---
name: architecture-design
description: 在需求分析完成后使用 - 系统化地设计系统架构，包括分层架构、模块划分、技术选型和依赖关系管理。
---

# 架构设计

系统化地设计软件系统架构，为后续的详细设计和实现提供清晰的蓝图。

**核心原则：** 好的架构让系统易于理解、开发、测试和演进。

## 流程

### 1. 分层架构设计

定义系统的逻辑层次结构。

**常见分层模式：**

#### 三层架构

```
┌─────────────────────────────────────┐
│           表示层（Presentation）      │  ← 用户界面、API 网关
├─────────────────────────────────────┤
│           业务层（Business）          │  ← 业务逻辑、领域服务
├─────────────────────────────────────┤
│           数据层（Data）              │  ← 数据访问、外部服务
└─────────────────────────────────────┘
```

#### 整洁架构（Clean Architecture）

```
┌─────────────────────────────────────────────────────────┐
│                    框架与驱动器                           │
│  ┌─────────────────────────────────────────────────┐   │
│  │                  接口适配器                       │   │
│  │  ┌─────────────────────────────────────────┐    │   │
│  │  │              用例层                       │    │   │
│  │  │  ┌─────────────────────────────────┐    │    │   │
│  │  │  │          实体层                  │    │    │   │
│  │  │  │      核心业务规则                 │    │    │   │
│  │  │  └─────────────────────────────────┘    │    │   │
│  │  └─────────────────────────────────────────┘    │   │
│  └─────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────┘

依赖方向：外层 → 内层
```

#### 六边形架构（端口与适配器）

```
                    ┌──────────────┐
                    │   REST API   │ ← 适配器
                    └──────┬───────┘
                           │
┌──────────────┐    ┌──────┴───────┐    ┌──────────────┐
│   Web UI     │ ←→ │    应用核心   │ ←→ │   消息队列    │
└──────────────┘    │   (六边形)    │    └──────────────┘
                    └──────┬───────┘
                           │
                    ┌──────┴───────┐
                    │   数据库      │ ← 适配器
                    └──────────────┘
```

**分层原则：**
- 依赖方向：外层依赖内层，内层不知道外层
- 数据流：请求从外层流入，响应从内层流出
- 变化频率：内层变化少，外层变化多

### 2. 模块划分

将系统分解为高内聚、低耦合的模块。

**模块深度原则（来自《软件设计哲学》）：**

```
深度模块 = 小接口 + 大实现

┌─────────────────────┐
│    小接口           │  ← 少量方法，简单参数
├─────────────────────┤
│                     │
│                     │
│   大实现            │  ← 复杂逻辑隐藏
│                     │
│                     │
└─────────────────────┘

浅层模块 = 大接口 + 小实现（应避免）

┌─────────────────────────────────┐
│        大接口                   │  ← 方法多，参数复杂
├─────────────────────────────────┤
│   小实现                        │  ← 只是透传
└─────────────────────────────────┘
```

**模块划分方法：**

1. **按业务能力划分**
   - 每个模块对应一个业务能力
   - 模块内高内聚，模块间低耦合

2. **按子域划分（DDD）**
   - 核心域：业务核心竞争力
   - 支撑域：支撑核心业务
   - 通用域：通用功能

3. **按变化原因划分（SRP）**
   - 每个模块只有一个变化原因
   - 变化影响范围最小化

**模块接口设计：**
- 接口是调用者必须知道的一切
- 包括：类型签名、不变量、错误模式、性能特征
- 好的接口让简单的事情简单

### 3. 技术选型

系统化地评估和选择技术栈。

**技术选型框架：**

| 评估维度 | 权重 | 评分标准 |
|----------|------|----------|
| 功能适配度 | 30% | 是否满足功能需求？ |
| 性能表现 | 20% | 是否满足性能需求？ |
| 学习成本 | 15% | 团队学习难度如何？ |
| 社区活跃度 | 15% | 社区是否活跃？文档是否完善？ |
| 长期维护性 | 10% | 是否持续维护？版本稳定性？ |
| 成本 | 10% | 许可费用、运维成本？ |

**技术选型模板：**

```markdown
## 技术选型：[技术领域]

### 需求分析
- 功能需求：[列出]
- 非功能需求：[列出]
- 约束条件：[列出]

### 候选方案

| 方案 | 优势 | 劣势 | 适用场景 |
|------|------|------|----------|
| 方案A | ... | ... | ... |
| 方案B | ... | ... | ... |

### 评估矩阵

| 维度 | 权重 | 方案A | 方案B | 方案C |
|------|------|-------|-------|-------|
| 功能适配度 | 30% | 8 | 7 | 9 |
| 性能表现 | 20% | 7 | 9 | 6 |
| 学习成本 | 15% | 6 | 8 | 5 |
| 社区活跃度 | 15% | 9 | 7 | 8 |
| 长期维护性 | 10% | 8 | 6 | 7 |
| 成本 | 10% | 7 | 8 | 6 |
| **加权总分** | 100% | **7.6** | **7.4** | **7.2** |

### 最终选择
选择方案A，理由：...

### 风险与缓解
- 风险1：... → 缓解措施：...
```

### 4. 依赖关系管理

管理模块间的依赖关系，避免循环依赖和过度耦合。

**依赖分类：**

| 类型 | 描述 | 测试策略 |
|------|------|----------|
| **进程内** | 纯计算、内存状态、无 I/O | 直接测试，无需适配器 |
| **本地可替换** | 有本地测试替身（如 PGLite） | 使用替身测试 |
| **远程但可控** | 自己的服务跨网络边界 | 端口+适配器模式 |
| **真正外部** | 第三方服务（Stripe、Twilio） | Mock 适配器 |

**依赖原则：**

1. **依赖倒置原则（DIP）**
   - 高层模块不依赖低层模块，都依赖抽象
   - 抽象不依赖细节，细节依赖抽象

2. **接口隔离原则（ISP）**
   - 不应强迫客户依赖它们不使用的方法
   - 接口应该小而专注

3. **缝（Seam）原则**
   - 缝是可以在不修改代码的情况下改变行为的地方
   - 一个适配器 = 假设的缝
   - 两个适配器 = 真正的缝

**依赖关系可视化：**

```
┌──────────────┐      ┌──────────────┐
│   订单模块    │ ───→ │   支付模块    │
└──────────────┘      └──────────────┘
       │                     │
       │                     │
       ↓                     ↓
┌──────────────┐      ┌──────────────┐
│   库存模块    │      │   通知模块    │
└──────────────┘      └──────────────┘

依赖方向：订单 → 支付、库存
```

**循环依赖检测：**
- 使用依赖分析工具
- 定期审查依赖关系
- 通过事件驱动或中介者模式解耦

## 架构决策记录（ADR）

记录重要的架构决策及其背景。

**ADR 模板：**

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

## 状态
[提议/已接受/已废弃/已替代]

## 背景
[描述导致此决策的情况]

## 决策
[描述决策内容]

## 后果
[描述决策的影响，包括正面和负面]

## 替代方案
[考虑过的其他方案及拒绝理由]
```

## 输出产物

1. **架构设计文档** (`docs/architecture/architecture.md`)
   - 分层架构图
   - 模块划分说明
   - 技术栈选择

2. **模块接口定义** (`docs/architecture/modules/`)
   - 每个模块的职责
   - 模块间的接口
   - 依赖关系图

3. **技术选型报告** (`docs/architecture/tech-selection.md`)
   - 技术选型评估
   - 风险分析

4. **架构决策记录** (`docs/adr/`)
   - 重要决策的 ADR 文档

## 检查清单

- [ ] 分层架构已定义
- [ ] 模块边界已划分
- [ ] 模块深度已评估
- [ ] 技术栈已选型
- [ ] 依赖关系已梳理
- [ ] 循环依赖已消除
- [ ] 架构决策已记录
- [ ] 利益相关者已评审

## 与其他 Skill 的集成

**前置条件：**
- 使用 `requirements-analysis` 完成需求分析

**下一步：**
- 使用 `interface-design` 定义接口契约
- 使用 `detailed-design` 进行详细设计