forked from datawhale/whale-town-end
docs：重构README和贡献者文档，完善项目架构说明和测试指南
- 重构README结构，按新开发者学习流程组织内容 - 更新项目架构图和技术栈说明，基于实际代码结构 - 创建CONTRIBUTORS.md，记录所有贡献者信息和统计 - 添加TESTING.md测试指南，支持无依赖快速测试 - 创建docs/ARCHITECTURE.md详细架构设计文档 - 优化.env.example配置，支持测试和生产环境切换 - 添加跨平台测试脚本(test-api.ps1/test-api.sh) - 删除冗余测试文件，统一测试入口 - 更新所有链接为正确的Gitea仓库地址 - 添加MIT开源协议文件
This commit is contained in:
moyin
187
docs/ARCHITECTURE.md
Normal file
187
docs/ARCHITECTURE.md
Normal file
@@ -0,0 +1,187 @@
|
||||
# 🏗️ 项目架构设计
|
||||
|
||||
## 整体架构
|
||||
|
||||
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请求频率限制
|
||||
Reference in New Issue
Block a user