7924cfb201
- 重构README结构，按新开发者学习流程组织内容 - 更新项目架构图和技术栈说明，基于实际代码结构 - 创建CONTRIBUTORS.md，记录所有贡献者信息和统计 - 添加TESTING.md测试指南，支持无依赖快速测试 - 创建docs/ARCHITECTURE.md详细架构设计文档 - 优化.env.example配置，支持测试和生产环境切换 - 添加跨平台测试脚本(test-api.ps1/test-api.sh) - 删除冗余测试文件，统一测试入口 - 更新所有链接为正确的Gitea仓库地址 - 添加MIT开源协议文件
187 lines
7.9 KiB
Markdown
187 lines
7.9 KiB
Markdown
# 🏗️ 项目架构设计
|
||
|
||
## 整体架构
|
||
|
||
Whale Town 采用分层架构设计，确保代码的可维护性和可扩展性。
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────┐
|
||
│ API 层 │
|
||
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
|
||
│ │ HTTP API │ │ WebSocket │ │ GraphQL │ │
|
||
│ │ (REST) │ │ (Socket.IO) │ │ (预留) │ │
|
||
│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │
|
||
└─────────────────────────────────────────────────────────────┘
|
||
│
|
||
┌─────────────────────────────────────────────────────────────┐
|
||
│ 业务逻辑层 │
|
||
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
|
||
│ │ 用户认证 │ │ 游戏逻辑 │ │ 社交功能 │ │
|
||
│ │ (Login) │ │ (Game) │ │ (Social) │ │
|
||
│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │
|
||
└─────────────────────────────────────────────────────────────┘
|
||
│
|
||
┌─────────────────────────────────────────────────────────────┐
|
||
│ 核心服务层 │
|
||
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
|
||
│ │ 邮件服务 │ │ 验证码服务 │ │ 日志服务 │ │
|
||
│ │ (Email) │ │ (Verification)│ │ (Logger) │ │
|
||
│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │
|
||
└─────────────────────────────────────────────────────────────┘
|
||
│
|
||
┌─────────────────────────────────────────────────────────────┐
|
||
│ 数据访问层 │
|
||
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
|
||
│ │ 用户数据 │ │ Redis缓存 │ │ 文件存储 │ │
|
||
│ │ (Users) │ │ (Cache) │ │ (Files) │ │
|
||
│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │
|
||
└─────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
## 模块依赖关系
|
||
|
||
```
|
||
AppModule
|
||
├── ConfigModule (全局配置)
|
||
├── LoggerModule (日志系统)
|
||
├── RedisModule (缓存服务)
|
||
├── UsersModule (用户管理)
|
||
│ ├── UsersService (数据库模式)
|
||
│ └── UsersMemoryService (内存模式)
|
||
├── EmailModule (邮件服务)
|
||
├── VerificationModule (验证码服务)
|
||
├── LoginCoreModule (登录核心)
|
||
└── LoginModule (登录业务)
|
||
```
|
||
|
||
## 数据流向
|
||
|
||
### 用户注册流程
|
||
```
|
||
1. 用户请求 → LoginController
|
||
2. 参数验证 → LoginService
|
||
3. 发送验证码 → LoginCoreService
|
||
4. 生成验证码 → VerificationService
|
||
5. 发送邮件 → EmailService
|
||
6. 存储验证码 → RedisService
|
||
7. 返回响应 → 用户
|
||
```
|
||
|
||
### 双模式架构
|
||
|
||
项目支持开发测试模式和生产部署模式的无缝切换：
|
||
|
||
#### 开发测试模式
|
||
- **数据库**: 内存存储 (UsersMemoryService)
|
||
- **缓存**: 文件存储 (FileRedisService)
|
||
- **邮件**: 控制台输出 (测试模式)
|
||
- **优势**: 无需外部依赖，快速启动测试
|
||
|
||
#### 生产部署模式
|
||
- **数据库**: MySQL (UsersService + TypeORM)
|
||
- **缓存**: Redis (RealRedisService + IORedis)
|
||
- **邮件**: SMTP服务器 (生产模式)
|
||
- **优势**: 高性能，高可用，数据持久化
|
||
|
||
## 设计原则
|
||
|
||
### 1. 单一职责原则
|
||
每个模块只负责一个特定的功能领域：
|
||
- `LoginModule`: 只处理登录相关业务
|
||
- `EmailModule`: 只处理邮件发送
|
||
- `VerificationModule`: 只处理验证码逻辑
|
||
|
||
### 2. 依赖注入
|
||
使用NestJS的依赖注入系统：
|
||
- 接口抽象: `IRedisService`, `IUsersService`
|
||
- 实现切换: 根据配置自动选择实现类
|
||
- 测试友好: 易于Mock和单元测试
|
||
|
||
### 3. 配置驱动
|
||
通过环境变量控制行为：
|
||
- `USE_FILE_REDIS`: 选择Redis实现
|
||
- `DB_HOST`: 数据库连接配置
|
||
- `EMAIL_HOST`: 邮件服务配置
|
||
|
||
### 4. 错误处理
|
||
统一的错误处理机制：
|
||
- HTTP异常: `BadRequestException`, `UnauthorizedException`
|
||
- 业务异常: 自定义异常类
|
||
- 日志记录: 结构化错误日志
|
||
|
||
## 扩展指南
|
||
|
||
### 添加新的业务模块
|
||
|
||
1. **创建业务模块**
|
||
```bash
|
||
nest g module business/game
|
||
nest g controller business/game
|
||
nest g service business/game
|
||
```
|
||
|
||
2. **创建核心服务**
|
||
```bash
|
||
nest g module core/game_core
|
||
nest g service core/game_core
|
||
```
|
||
|
||
3. **添加数据模型**
|
||
```bash
|
||
nest g module core/db/games
|
||
nest g service core/db/games
|
||
```
|
||
|
||
4. **更新主模块**
|
||
在 `app.module.ts` 中导入新模块
|
||
|
||
### 添加新的工具服务
|
||
|
||
1. **创建工具模块**
|
||
```bash
|
||
nest g module core/utils/notification
|
||
nest g service core/utils/notification
|
||
```
|
||
|
||
2. **实现服务接口**
|
||
定义抽象接口和具体实现
|
||
|
||
3. **添加配置支持**
|
||
在环境变量中添加相关配置
|
||
|
||
4. **编写测试用例**
|
||
确保功能正确性和代码覆盖率
|
||
|
||
## 性能优化
|
||
|
||
### 1. 缓存策略
|
||
- **Redis缓存**: 验证码、会话信息
|
||
- **内存缓存**: 配置信息、静态数据
|
||
- **CDN缓存**: 静态资源文件
|
||
|
||
### 2. 数据库优化
|
||
- **连接池**: 复用数据库连接
|
||
- **索引优化**: 关键字段建立索引
|
||
- **查询优化**: 避免N+1查询问题
|
||
|
||
### 3. 日志优化
|
||
- **异步日志**: 使用Pino的异步写入
|
||
- **日志分级**: 生产环境只记录必要日志
|
||
- **日志轮转**: 自动清理过期日志文件
|
||
|
||
## 安全考虑
|
||
|
||
### 1. 数据验证
|
||
- **输入验证**: class-validator装饰器
|
||
- **类型检查**: TypeScript静态类型
|
||
- **SQL注入**: TypeORM参数化查询
|
||
|
||
### 2. 认证授权
|
||
- **密码加密**: bcrypt哈希算法
|
||
- **会话管理**: Redis存储会话信息
|
||
- **权限控制**: 基于角色的访问控制
|
||
|
||
### 3. 通信安全
|
||
- **HTTPS**: 生产环境强制HTTPS
|
||
- **CORS**: 跨域请求控制
|
||
- **Rate Limiting**: API请求频率限制 |