architect/architecture-design

# 系统架构设计方法论

## 适用场景

基于技术调研结论，设计完整的系统架构，包括：
- 架构模式选择（单体/前后端分离/微服务）
- 系统分层和模块划分
- 目录结构设计
- 数据模型设计
- API设计

## 架构设计流程

### 1. 架构模式选择

根据项目规模、团队规模、业务复杂度选择合适的架构模式：

| 架构模式 | 适用场景 | 优点 | 缺点 | 团队规模 |
|----------|----------|------|------|----------|
| **单体应用** | 小型项目、快速迭代、MVP | 简单、开发快、易部署 | 扩展性差、耦合高 | 1-3人 |
| **前后端分离** | 中型项目、团队协作、多端支持 | 职责清晰、并行开发、技术独立 | 部署复杂、接口管理 | 3-10人 |
| **微服务** | 大型项目、独立部署、高可用 | 独立扩展、技术异构、故障隔离 | 复杂度高、运维成本高 | 10+人 |
| **Serverless** | 事件驱动、弹性伸缩、按需付费 | 免运维、自动扩展、成本优化 | 冷启动、供应商锁定 | 任意 |

**选择决策树**：

```
项目规模？
├─ 小型（< 10个页面）
│  └─ 单体应用 或 前后端分离（简化版）
├─ 中型（10-50个页面）
│  └─ 前后端分离
└─ 大型（> 50个页面）
   ├─ 业务模块独立？
   │  ├─ 是 → 微服务
   │  └─ 否 → 前后端分离
   └─ 流量波动大？
      └─ 是 → Serverless
```

### 2. 系统分层设计

#### 经典三层架构

```
┌─────────────────────────────────┐
│      表现层 (Presentation)       │  ← 用户界面、API接口
├─────────────────────────────────┤
│       业务层 (Business)          │  ← 业务逻辑、流程控制
├─────────────────────────────────┤
│      数据层 (Data Access)        │  ← 数据库访问、ORM
└─────────────────────────────────┘
```

#### 前后端分离架构

```
┌──────────────┐
│   前端应用    │  ← React/Vue/Angular
└──────┬───────┘
       │ HTTP/WebSocket
┌──────▼───────┐
│   API网关    │  ← 路由、认证、限流
└──────┬───────┘
       │
┌──────▼───────┐
│   后端服务    │  ← 业务逻辑
└──────┬───────┘
       │
┌──────▼───────┐
│   数据库     │  ← PostgreSQL/MongoDB
└──────────────┘
```

#### 微服务架构

```
┌──────────┐
│  前端应用 │
└────┬─────┘
     │
┌────▼─────┐
│ API网关  │
└────┬─────┘
     │
     ├─────┬─────┬─────┐
     │     │     │     │
┌────▼┐ ┌─▼──┐ ┌▼───┐ ┌▼────┐
│用户 │ │订单│ │商品│ │支付 │
│服务│ │服务│ │服务│ │服务 │
└────┘ └────┘ └────┘ └─────┘
  │      │      │       │
  └──────┴──────┴───────┘
         │
    ┌────▼────┐
    │ 数据库  │
    └─────────┘
```

### 3. 系统架构图

使用 Mermaid 绘制系统架构图：

**前后端分离架构示例**：

```mermaid
graph TB
    subgraph 客户端
        Web[Web 应用]
        Mobile[移动端]
    end

    subgraph 接入层
        CDN[CDN]
        LB[负载均衡]
    end

    subgraph 应用层
        subgraph 前端服务
            FE[前端应用]
        end

        subgraph 后端服务
            API[API 网关]
            Auth[认证服务]
            BIZ[业务服务]
        end
    end

    subgraph 数据层
        DB[(主数据库)]
        Cache[(缓存)]
        MQ[消息队列]
    end

    subgraph 基础设施
        Log[日志系统]
        Monitor[监控告警]
    end

    Web --> CDN
    Mobile --> LB
    CDN --> LB
    LB --> FE
    FE --> API
    API --> Auth
    API --> BIZ
    BIZ --> DB
    BIZ --> Cache
    BIZ --> MQ
    BIZ --> Log
```

### 4. 目录结构设计

**重要原则**：
1. **遵循框架惯例**：使用检测到的框架的标准目录结构
2. **关注点分离**：业务逻辑、数据访问、API层清晰分离
3. **测试并置**：测试文件与源码在同层或专用tests目录
4. **配置集中**：环境配置统一管理

#### Next.js App Router 项目结构

```
project/
├── app/                    # Next.js App Router
│   ├── (auth)/            # 路由组：认证相关页面
│   │   ├── login/
│   │   └── register/
│   ├── (dashboard)/       # 路由组：仪表板
│   │   ├── layout.tsx
│   │   └── page.tsx
│   ├── api/               # API Routes
│   │   ├── auth/
│   │   └── users/
│   ├── layout.tsx         # 根布局
│   └── page.tsx           # 首页
├── components/            # React组件
│   ├── ui/               # UI组件
│   └── features/         # 功能组件
├── lib/                   # 工具库
│   ├── db.ts             # 数据库连接
│   ├── auth.ts           # 认证逻辑
│   └── utils.ts          # 工具函数
├── prisma/               # Prisma ORM
│   └── schema.prisma
├── public/               # 静态资源
├── tests/                # 测试
└── package.json
```

#### Express + React 前后端分离结构

```
project/
├── client/               # 前端
│   ├── src/
│   │   ├── components/
│   │   ├── pages/
│   │   ├── hooks/
│   │   └── App.tsx
│   ├── public/
│   └── package.json
├── server/               # 后端
│   ├── src/
│   │   ├── routes/      # 路由
│   │   ├── controllers/ # 控制器
│   │   ├── services/    # 业务逻辑
│   │   ├── models/      # 数据模型
│   │   ├── middleware/  # 中间件
│   │   └── app.ts       # 入口
│   ├── tests/
│   └── package.json
├── shared/              # 共享代码
│   └── types/          # TypeScript类型
└── docker-compose.yml
```

#### Python FastAPI 项目结构

```
project/
├── app/
│   ├── api/             # API路由
│   │   ├── v1/
│   │   │   ├── endpoints/
│   │   │   └── router.py
│   │   └── deps.py      # 依赖注入
│   ├── core/            # 核心配置
│   │   ├── config.py
│   │   └── security.py
│   ├── models/          # 数据模型
│   ├── schemas/         # Pydantic schemas
│   ├── services/        # 业务逻辑
│   └── main.py          # 入口
├── tests/
├── alembic/             # 数据库迁移
├── requirements.txt
└── pyproject.toml
```

#### Go 标准项目结构

```
project/
├── cmd/                 # 主程序入口
│   └── api/
│       └── main.go
├── internal/            # 私有代码
│   ├── handler/        # HTTP处理器
│   ├── service/        # 业务逻辑
│   ├── repository/     # 数据访问
│   └── model/          # 数据模型
├── pkg/                 # 公共库
│   └── utils/
├── api/                 # API定义
│   └── openapi.yaml
├── migrations/          # 数据库迁移
├── tests/
├── go.mod
└── go.sum
```

### 5. 技术栈总览

输出完整的技术栈清单：

| 层级 | 技术 | 版本 | 说明 |
|------|------|------|------|
| **前端** | | | |
| 框架 | Next.js | 14.x | App Router模式 |
| UI库 | React | 18.x | |
| 样式 | Tailwind CSS | 3.x | 原子化CSS |
| 状态管理 | Zustand | 4.x | 轻量级状态管理 |
| **后端** | | | |
| 运行时 | Node.js | 20.x | LTS版本 |
| 框架 | Next.js API Routes | 14.x | 与前端一体 |
| ORM | Prisma | 5.x | 类型安全ORM |
| **数据** | | | |
| 主数据库 | PostgreSQL | 16.x | 关系型数据库 |
| 缓存 | Redis | 7.x | 可选 |
| **基础设施** | | | |
| 容器化 | Docker | 24.x | 开发环境 |
| CI/CD | GitHub Actions | - | 自动化部署 |
| 部署 | Vercel | - | 托管平台 |

## 输出要求

完成架构设计后，应输出以下内容（通常作为架构文档的第2-3章）：

```markdown
## 2. 架构概述

### 2.1 架构类型选择

**本项目选择**：[架构模式] - [选择理由]

### 2.2 系统架构图

[Mermaid架构图]

### 2.3 技术栈总览

[技术栈表格]

---

## 3. 目录结构

[目录树]

### 目录说明

- `app/`: [说明]
- `components/`: [说明]
- `lib/`: [说明]
```

## 关键原则

1. **遵循惯例**：使用框架的标准结构，不要自创
2. **职责清晰**：每个目录的职责明确，不要混杂
3. **扩展性**：结构要易于扩展，不要过早优化
4. **一致性**：命名和组织保持一致

## 常见误区

❌ **自创结构**：不遵循框架惯例，自己发明目录结构
❌ **过度设计**：小项目用微服务架构
❌ **职责混乱**：业务逻辑、数据访问、UI混在一起
❌ **忽略测试**：没有规划测试文件的位置