7924cfb201
- 重构README结构，按新开发者学习流程组织内容 - 更新项目架构图和技术栈说明，基于实际代码结构 - 创建CONTRIBUTORS.md，记录所有贡献者信息和统计 - 添加TESTING.md测试指南，支持无依赖快速测试 - 创建docs/ARCHITECTURE.md详细架构设计文档 - 优化.env.example配置，支持测试和生产环境切换 - 添加跨平台测试脚本(test-api.ps1/test-api.sh) - 删除冗余测试文件，统一测试入口 - 更新所有链接为正确的Gitea仓库地址 - 添加MIT开源协议文件
7.9 KiB
7.9 KiB
🏗️ 项目架构设计
整体架构
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 - 业务异常: 自定义异常类
- 日志记录: 结构化错误日志
扩展指南
添加新的业务模块
-
创建业务模块
nest g module business/game nest g controller business/game nest g service business/game -
创建核心服务
nest g module core/game_core nest g service core/game_core -
添加数据模型
nest g module core/db/games nest g service core/db/games -
更新主模块 在
app.module.ts中导入新模块
添加新的工具服务
-
创建工具模块
nest g module core/utils/notification nest g service core/utils/notification -
实现服务接口 定义抽象接口和具体实现
-
添加配置支持 在环境变量中添加相关配置
-
编写测试用例 确保功能正确性和代码覆盖率
性能优化
1. 缓存策略
- Redis缓存: 验证码、会话信息
- 内存缓存: 配置信息、静态数据
- CDN缓存: 静态资源文件
2. 数据库优化
- 连接池: 复用数据库连接
- 索引优化: 关键字段建立索引
- 查询优化: 避免N+1查询问题
3. 日志优化
- 异步日志: 使用Pino的异步写入
- 日志分级: 生产环境只记录必要日志
- 日志轮转: 自动清理过期日志文件
安全考虑
1. 数据验证
- 输入验证: class-validator装饰器
- 类型检查: TypeScript静态类型
- SQL注入: TypeORM参数化查询
2. 认证授权
- 密码加密: bcrypt哈希算法
- 会话管理: Redis存储会话信息
- 权限控制: 基于角色的访问控制
3. 通信安全
- HTTPS: 生产环境强制HTTPS
- CORS: 跨域请求控制
- Rate Limiting: API请求频率限制