datawhale/whale-town-end
3
4
Fork 2
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
43874892b77fe87af8abd9b43279a07aa58138f8
whale-town-end/docs/ARCHITECTURE.md
moyin bb796a2469 refactor：项目架构重构和命名规范化 
- 统一文件命名为snake_case格式（kebab-case  snake_case）
- 重构zulip模块为zulip_core，明确Core层职责
- 重构user-mgmt模块为user_mgmt，统一命名规范
- 调整模块依赖关系，优化架构分层
- 删除过时的文件和目录结构
- 更新相关文档和配置文件

本次重构涉及大量文件重命名和模块重组，
旨在建立更清晰的项目架构和统一的命名规范。
2026-01-08 00:14:14 +08:00

773 lines
33 KiB
Markdown
Raw Blame History

This file contains invisible Unicode characters
This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 🏗️ Whale Town 项目架构设计
> 基于业务功能模块化的现代化后端架构，支持双模式运行，开发测试零依赖，生产部署高性能。
## 📋 目录
- [🎯 架构概述](#-架构概述)
- [📁 目录结构详解](#-目录结构详解)
- [🏗️ 分层架构设计](#️-分层架构设计)
- [🔄 双模式架构](#-双模式架构)
- [📦 模块依赖关系](#-模块依赖关系)
- [🚀 扩展指南](#-扩展指南)
---
## 🎯 架构概述
Whale Town 采用**业务功能模块化架构**，将代码按业务功能而非技术组件组织，确保高内聚、低耦合的设计原则。
### 🌟 核心设计理念
- **业务驱动** - 按业务功能组织代码，而非技术分层
- **双模式支持** - 开发测试零依赖，生产部署高性能
- **清晰分层** - 业务层 → 核心层 → 数据层，职责明确
- **模块化设计** - 每个模块独立完整，可单独测试和部署
- **配置驱动** - 通过环境变量控制运行模式和行为
### 🛠️ 技术栈
#### 后端技术栈
- **框架**: NestJS 11.x (基于Express)
- **语言**: TypeScript 5.x
- **数据库**: MySQL + TypeORM (生产) / 内存数据库 (开发)
- **缓存**: Redis + IORedis (生产) / 文件存储 (开发)
- **认证**: JWT + bcrypt
- **验证**: class-validator + class-transformer
- **文档**: Swagger/OpenAPI
- **测试**: Jest + Supertest
- **日志**: Pino + nestjs-pino
- **WebSocket**: Socket.IO
- **邮件**: Nodemailer
- **集成**: Zulip API
#### 前端技术栈
- **框架**: React 18.x
- **构建工具**: Vite 7.x
- **UI库**: Ant Design 5.x
- **路由**: React Router DOM 6.x
- **语言**: TypeScript 5.x
### 📊 整体架构图
```
┌─────────────────────────────────────────────────────────────────┐
│ 🌐 API接口层 │
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
│ │ 🔗 REST API │ │ 🔌 WebSocket │ │ 📄 Swagger UI │ │
│ │ (HTTP接口) │ │ (实时通信) │ │ (API文档) │ │
│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
⬇️
┌─────────────────────────────────────────────────────────────────┐
│ 🎯 业务功能模块层 │
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
│ │ 🔐 用户认证 │ │ 👥 用户管理 │ │ 🛡️ 管理员 │ │
│ │ (auth) │ │ (user_mgmt) │ │ (admin) │ │
│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
│ │ 💬 Zulip集成 │ │ 🔗 共享组件 │ │ │ │
│ │ (zulip) │ │ (shared) │ │ │ │
│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
⬇️
┌─────────────────────────────────────────────────────────────────┐
│ ⚙️ 核心技术服务层 │
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
│ │ 🔑 登录核心 │ │ 👑 管理员核心 │ │ 💬 Zulip核心 │ │
│ │ (auth_core) │ │ (admin_core) │ │ (zulip) │ │
│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
│ │ 🛡️ 安全核心 │ │ 🛠️ 工具服务 │ │ 📧 邮件服务 │ │
│ │ (security_core)│ │ (utils) │ │ (email) │ │
│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
⬇️
┌─────────────────────────────────────────────────────────────────┐
│ 🗄️ 数据存储层 │
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
│ │ 🗃️ 数据库 │ │ 🔴 Redis缓存 │ │ 📁 文件存储 │ │
│ │ (MySQL/内存) │ │ (Redis/文件) │ │ (logs/data) │ │
│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
```
---
## 📁 目录结构详解
### 🎯 业务功能模块 (`src/business/`)
> **设计原则**: 按业务功能组织，每个模块包含完整的业务逻辑
```
src/business/
├── 📂 auth/ # 🔐 用户认证模块
│ ├── 📄 auth.module.ts # 模块定义
│ ├── 📂 controllers/ # 控制器
│ │ └── 📄 login.controller.ts # 登录接口控制器
│ ├── 📂 services/ # 业务服务
│ │ ├── 📄 login.service.ts # 登录业务逻辑
│ │ └── 📄 login.service.spec.ts # 登录服务测试
│ ├── 📂 dto/ # 数据传输对象
│ │ ├── 📄 login.dto.ts # 登录请求DTO
│ │ └── 📄 login_response.dto.ts # 登录响应DTO
│ └── 📂 guards/ # 权限守卫（预留）
│
├── 📂 user-mgmt/ # 👥 用户管理模块
│ ├── 📄 user-mgmt.module.ts # 模块定义
│ ├── 📂 controllers/ # 控制器
│ │ └── 📄 user-status.controller.ts # 用户状态管理接口
│ ├── 📂 services/ # 业务服务
│ │ └── 📄 user-management.service.ts # 用户管理逻辑
│ ├── 📂 dto/ # 数据传输对象
│ │ ├── 📄 user-status.dto.ts # 用户状态DTO
│ │ └── 📄 user-status-response.dto.ts # 状态响应DTO
│ ├── 📂 enums/ # 枚举定义
│ │ └── 📄 user-status.enum.ts # 用户状态枚举
│ └── 📂 tests/ # 测试文件（预留）
│
├── 📂 admin/ # 🛡️ 管理员模块
│ ├── 📄 admin.controller.ts # 管理员接口
│ ├── 📄 admin.service.ts # 管理员业务逻辑
│ ├── 📄 admin.module.ts # 模块定义
│ ├── 📄 admin.service.spec.ts # 管理员服务测试
│ ├── 📂 dto/ # 数据传输对象
│ └── 📂 guards/ # 权限守卫
│
├── 📂 zulip/ # 💬 Zulip集成模块
│ ├── 📄 zulip.service.ts # Zulip业务服务
│ ├── 📄 zulip_websocket.gateway.ts # WebSocket网关
│ ├── 📄 zulip.module.ts # 模块定义
│ ├── 📂 interfaces/ # 接口定义
│ └── 📂 services/ # 子服务
│ ├── 📄 message_filter.service.ts # 消息过滤
│ └── 📄 session_cleanup.service.ts # 会话清理
│
└── 📂 shared/ # 🔗 共享业务组件
├── 📂 dto/ # 共享数据传输对象
└── 📄 index.ts # 导出文件
```
### ⚙️ 核心技术服务 (`src/core/`)
> **设计原则**: 提供技术基础设施，支持业务模块运行
```
src/core/
├── 📂 db/ # 🗄️ 数据库层
│ └── 📂 users/ # 用户数据服务
│ ├── 📄 users.service.ts # MySQL数据库实现
│ ├── 📄 users_memory.service.ts # 内存数据库实现
│ ├── 📄 users.dto.ts # 用户数据传输对象
│ ├── 📄 users.entity.ts # 用户实体定义
│ ├── 📄 users.module.ts # 用户数据模块
│ └── 📄 users.service.spec.ts # 用户服务测试
│
├── 📂 redis/ # 🔴 Redis缓存层
│ ├── 📄 redis.module.ts # Redis模块
│ ├── 📄 real_redis.service.ts # Redis真实实现
│ ├── 📄 file_redis.service.ts # 文件存储实现
│ └── 📄 redis.interface.ts # Redis服务接口
│
├── 📂 login_core/ # 🔑 登录核心服务
│ ├── 📄 login_core.service.ts # 登录核心逻辑
│ ├── 📄 login_core.module.ts # 模块定义
│ └── 📄 login_core.service.spec.ts # 登录核心测试
│
├── 📂 admin_core/ # 👑 管理员核心服务
│ ├── 📄 admin_core.service.ts # 管理员核心逻辑
│ ├── 📄 admin_core.module.ts # 模块定义
│ └── 📄 admin_core.service.spec.ts # 管理员核心测试
│
├── 📂 zulip_core/ # 💬 Zulip核心服务
│ ├── 📄 zulip_core.module.ts # Zulip核心模块
│ ├── 📂 config/ # 配置文件
│ ├── 📂 interfaces/ # 接口定义
│ ├── 📂 services/ # 核心服务
│ ├── 📂 types/ # 类型定义
│ └── 📄 index.ts # 导出文件
│
├── 📂 security_core/ # 🛡️ 安全核心模块
│ ├── 📄 security_core.module.ts # 安全模块定义
│ ├── 📂 guards/ # 安全守卫
│ │ └── 📄 throttle.guard.ts # 频率限制守卫
│ ├── 📂 interceptors/ # 拦截器
│ │ └── 📄 timeout.interceptor.ts # 超时拦截器
│ ├── 📂 middleware/ # 中间件
│ │ ├── 📄 maintenance.middleware.ts # 维护模式中间件
│ │ └── 📄 content_type.middleware.ts # 内容类型中间件
│ └── 📂 decorators/ # 装饰器
│ ├── 📄 throttle.decorator.ts # 频率限制装饰器
│ └── 📄 timeout.decorator.ts # 超时装饰器
│
└── 📂 utils/ # 🛠️ 工具服务
├── 📂 email/ # 📧 邮件服务
│ ├── 📄 email.service.ts # 邮件发送服务
│ ├── 📄 email.module.ts # 邮件模块
│ └── 📄 email.service.spec.ts # 邮件服务测试
├── 📂 verification/ # 🔢 验证码服务
│ ├── 📄 verification.service.ts # 验证码生成验证
│ ├── 📄 verification.module.ts # 验证码模块
│ └── 📄 verification.service.spec.ts # 验证码服务测试
└── 📂 logger/ # 📝 日志服务
├── 📄 logger.service.ts # 日志记录服务
├── 📄 logger.module.ts # 日志模块
├── 📄 logger.config.ts # 日志配置
└── 📄 log_management.service.ts # 日志管理服务
```
### 🎨 前端管理界面 (`client/`)
> **设计原则**: 独立的前端项目，提供管理员后台功能，基于React + Vite + Ant Design
```
client/
├── 📂 src/ # 前端源码
│ ├── 📂 app/ # 应用组件
│ │ ├── 📄 App.tsx # 应用主组件
│ │ └── 📄 AdminLayout.tsx # 管理员布局组件
│ ├── 📂 pages/ # 页面组件
│ │ ├── 📄 LoginPage.tsx # 登录页面
│ │ ├── 📄 UsersPage.tsx # 用户管理页面
│ │ └── 📄 LogsPage.tsx # 日志管理页面
│ ├── 📂 lib/ # 工具库
│ │ ├── 📄 api.ts # API客户端
│ │ └── 📄 adminAuth.ts # 管理员认证服务
│ └── 📄 main.tsx # 应用入口
├── 📂 dist/ # 构建产物
├── 📄 package.json # 前端依赖
├── 📄 vite.config.ts # Vite配置
└── 📄 tsconfig.json # TypeScript配置
```
### 📚 文档中心 (`docs/`)
> **设计原则**: 完整的项目文档，支持开发者快速上手
```
docs/
├── 📄 README.md # 📖 文档导航中心
├── 📄 ARCHITECTURE.md # 🏗️ 架构设计文档
├── 📄 CONTRIBUTORS.md # 🤝 贡献者指南
│
├── 📂 api/ # 🔌 API接口文档
│ ├── 📄 README.md # API文档使用指南
│ └── 📄 api-documentation.md # 完整API接口文档
│
├── 📂 development/ # 💻 开发指南
│ ├── 📄 backend_development_guide.md # 后端开发规范
│ ├── 📄 git_commit_guide.md # Git提交规范
│ ├── 📄 AI辅助开发规范指南.md # AI辅助开发指南
│ └── 📄 TESTING.md # 测试指南
│
└── 📂 deployment/ # 🚀 部署文档
└── 📄 DEPLOYMENT.md # 生产环境部署指南
```
### 🧪 测试文件 (`test/`)
> **设计原则**: 完整的测试覆盖，确保代码质量
```
test/
├── 📂 unit/ # 单元测试
├── 📂 integration/ # 集成测试
├── 📂 e2e/ # 端到端测试
└── 📂 fixtures/ # 测试数据
```
### ⚙️ 配置文件
> **设计原则**: 清晰的配置管理，支持多环境部署
```
项目根目录/
├── 📄 .env # 🔧 环境变量配置
├── 📄 .env.example # 🔧 环境变量示例
├── 📄 .env.production.example # 🔧 生产环境示例
├── 📄 package.json # 📋 后端项目依赖配置
├── 📄 pnpm-workspace.yaml # 📦 pnpm工作空间配置
├── 📄 tsconfig.json # 📘 TypeScript配置
├── 📄 jest.config.js # 🧪 Jest测试配置
├── 📄 nest-cli.json # 🏠 NestJS CLI配置
└── 📄 ecosystem.config.js # 🚀 PM2进程管理配置
client/
├── 📄 package.json # 📋 前端项目依赖配置
├── 📄 vite.config.ts # ⚡ Vite构建配置
└── 📄 tsconfig.json # 📘 前端TypeScript配置
```
---
## 🏗️ 分层架构设计
### 📊 架构分层说明
```
┌─────────────────────────────────────────────────────────────┐
│ 🌐 表现层 (Presentation) │
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
│ │ Controllers │ │ WebSocket │ │ Swagger UI │ │
│ │ (HTTP接口) │ │ Gateways │ │ (API文档) │ │
│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │
└─────────────────────────────────────────────────────────────┘
⬇️
┌─────────────────────────────────────────────────────────────┐
│ 🎯 业务层 (Business) │
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
│ │ Auth Module │ │ UserMgmt │ │ Admin Module │ │
│ │ (用户认证) │ │ Module │ │ (管理员) │ │
│ │ │ │ (用户管理) │ │ │ │
│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
│ │ Security Module │ │ Zulip Module │ │ Shared Module │ │
│ │ (安全防护) │ │ (Zulip集成) │ │ (共享组件) │ │
│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │
└─────────────────────────────────────────────────────────────┘
⬇️
┌─────────────────────────────────────────────────────────────┐
│ ⚙️ 服务层 (Service) │
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
│ │ Login Core │ │ Admin Core │ │ Zulip Core │ │
│ │ (登录核心) │ │ (管理员核心) │ │ (Zulip核心) │ │
│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
│ │ Email Service │ │ Verification │ │ Logger Service │ │
│ │ (邮件服务) │ │ Service │ │ (日志服务) │ │
│ │ │ │ (验证码服务) │ │ │ │
│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │
└─────────────────────────────────────────────────────────────┘
⬇️
┌─────────────────────────────────────────────────────────────┐
│ 🗄️ 数据层 (Data) │
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
│ │ Users Service │ │ Redis Service │ │ File Storage │ │
│ │ (用户数据) │ │ (缓存服务) │ │ (文件存储) │ │
│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
│ │ MySQL/Memory │ │ Redis/File │ │ Logs/Data │ │
│ │ (数据库) │ │ (缓存实现) │ │ (日志数据) │ │
│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │
└─────────────────────────────────────────────────────────────┘
```
### 🔄 数据流向
#### 用户登录流程示例
```
1. 📱 用户请求 → LoginController.login()
2. 🔍 参数验证 → class-validator装饰器
3. 🎯 业务逻辑 → LoginService.login()
4. ⚙️ 核心服务 → LoginCoreService.validateUser()
5. 📧 发送验证码 → VerificationService.generate()
6. 💾 存储数据 → UsersService.findByEmail() + RedisService.set()
7. 📝 记录日志 → LoggerService.log()
8. ✅ 返回响应 → 用户收到登录结果
```
#### 管理员操作流程示例
```
1. 🛡️ 管理员请求 → AdminController.resetUserPassword()
2. 🔐 权限验证 → AdminGuard.canActivate()
3. 🎯 业务逻辑 → AdminService.resetPassword()
4. ⚙️ 核心服务 → AdminCoreService.resetUserPassword()
5. 🔑 密码加密 → bcrypt.hash()
6. 💾 更新数据 → UsersService.update()
7. 📧 通知用户 → EmailService.sendPasswordReset()
8. 📝 审计日志 → LoggerService.audit()
9. ✅ 返回响应 → 管理员收到操作结果
```
---
## 🔄 双模式架构
### 🎯 设计目标
- **开发测试**: 零依赖快速启动，无需安装MySQL、Redis等外部服务
- **生产部署**: 高性能、高可用，支持集群和负载均衡
### 📊 模式对比
| 功能模块 | 🧪 开发测试模式 | 🚀 生产部署模式 |
|----------|----------------|----------------|
| **数据库** | 内存存储 (UsersMemoryService) | MySQL (UsersService + TypeORM) |
| **缓存** | 文件存储 (FileRedisService) | Redis (RealRedisService + IORedis) |
| **邮件** | 控制台输出 (测试模式) | SMTP服务器 (生产模式) |
| **日志** | 控制台 + 文件 | 结构化日志 + 日志轮转 |
| **配置** | `.env` 默认配置 | 环境变量 + 配置中心 |
### ⚙️ 模式切换配置
#### 开发测试模式 (.env)
```bash
# 数据存储模式
USE_FILE_REDIS=true # 使用文件存储代替Redis
NODE_ENV=development # 开发环境
# 数据库配置（注释掉，使用内存数据库）
# DB_HOST=localhost
# DB_USERNAME=root
# DB_PASSWORD=password
# 邮件配置（注释掉，使用测试模式）
# EMAIL_HOST=smtp.gmail.com
# EMAIL_USER=your_email@gmail.com
# EMAIL_PASS=your_password
```
#### 生产部署模式 (.env.production)
```bash
# 数据存储模式
USE_FILE_REDIS=false # 使用真实Redis
NODE_ENV=production # 生产环境
# 数据库配置
DB_HOST=your_mysql_host
DB_PORT=3306
DB_USERNAME=your_username
DB_PASSWORD=your_password
DB_DATABASE=whale_town
# Redis配置
REDIS_HOST=your_redis_host
REDIS_PORT=6379
REDIS_PASSWORD=your_redis_password
# 邮件配置
EMAIL_HOST=smtp.gmail.com
EMAIL_PORT=587
EMAIL_USER=your_email@gmail.com
EMAIL_PASS=your_app_password
```
### 🔧 实现机制
#### 依赖注入切换
```typescript
// redis.module.ts
@Module({
providers: [
{
provide: 'IRedisService',
useFactory: (configService: ConfigService) => {
const useFileRedis = configService.get<boolean>('USE_FILE_REDIS');
return useFileRedis
? new FileRedisService()
: new RealRedisService(configService);
},
inject: [ConfigService],
},
],
})
export class RedisModule {}
```
#### 配置驱动服务选择
```typescript
// users.module.ts
@Module({
providers: [
{
provide: 'IUsersService',
useFactory: (configService: ConfigService) => {
const dbHost = configService.get<string>('DB_HOST');
return dbHost
? new UsersService()
: new UsersMemoryService();
},
inject: [ConfigService],
},
],
})
export class UsersModule {}
```
---
## 📦 模块依赖关系
### 🏗️ 模块依赖图
```
AppModule (应用主模块)
├── 📊 ConfigModule (全局配置)
├── 📝 LoggerModule (日志系统)
├── 🔴 RedisModule (缓存服务)
│ ├── RealRedisService (真实Redis)
│ └── FileRedisService (文件存储)
├── 🗄️ UsersModule (用户数据)
│ ├── UsersService (MySQL数据库)
│ └── UsersMemoryService (内存数据库)
├── 📧 EmailModule (邮件服务)
├── 🔢 VerificationModule (验证码服务)
├── 🔑 LoginCoreModule (登录核心)
├── 👑 AdminCoreModule (管理员核心)
├── 💬 ZulipCoreModule (Zulip核心)
├── 🔒 SecurityCoreModule (安全核心)
│
├── 🎯 业务功能模块
│ ├── 🔐 AuthModule (用户认证)
│ │ └── 依赖: LoginCoreModule, EmailModule, VerificationModule, SecurityCoreModule
│ ├── 👥 UserMgmtModule (用户管理)
│ │ └── 依赖: UsersModule, LoggerModule, SecurityCoreModule
│ ├── 🛡️ AdminModule (管理员)
│ │ └── 依赖: AdminCoreModule, UsersModule, SecurityCoreModule
│ ├── 💬 ZulipModule (Zulip集成)
│ │ └── 依赖: ZulipCoreModule, RedisModule
│ └── 🔗 SharedModule (共享组件)
```
### 🔄 模块交互流程
#### 用户认证流程
```
AuthController → LoginService → LoginCoreService
↓
EmailService ← VerificationService ← RedisService
↓
UsersService
```
#### 管理员操作流程
```
AdminController → AdminService → AdminCoreService
↓
LoggerService ← UsersService ← RedisService
```
#### 安全防护流程
```
SecurityGuard → RedisService (频率限制)
→ LoggerService (审计日志)
→ ConfigService (维护模式)
```
---
## 🚀 扩展指南
### 📝 添加新的业务模块
#### 1. 创建业务模块结构
```bash
# 创建模块目录
mkdir -p src/business/game/{dto,enums,guards,interfaces}
# 生成NestJS模块文件
nest g module business/game
nest g controller business/game
nest g service business/game
```
#### 2. 实现业务逻辑
```typescript
// src/business/game/game.module.ts
@Module({
imports: [
GameCoreModule, # 依赖核心服务
UsersModule, # 依赖用户数据
RedisModule, # 依赖缓存服务
],
controllers: [GameController],
providers: [GameService],
exports: [GameService],
})
export class GameModule {}
```
#### 3. 创建对应的核心服务
```bash
# 创建核心服务
mkdir -p src/core/game_core
nest g module core/game_core
nest g service core/game_core
```
#### 4. 更新主模块
```typescript
// src/app.module.ts
@Module({
imports: [
// ... 其他模块
GameModule, # 添加新的业务模块
],
})
export class AppModule {}
```
### 🛠️ 添加新的工具服务
#### 1. 创建工具服务
```bash
mkdir -p src/core/utils/notification
nest g module core/utils/notification
nest g service core/utils/notification
```
#### 2. 定义服务接口
```typescript
// src/core/utils/notification/notification.interface.ts
export interface INotificationService {
sendPush(userId: string, message: string): Promise<void>;
sendSMS(phone: string, message: string): Promise<void>;
}
```
#### 3. 实现服务
```typescript
// src/core/utils/notification/notification.service.ts
@Injectable()
export class NotificationService implements INotificationService {
async sendPush(userId: string, message: string): Promise<void> {
// 实现推送通知逻辑
}
async sendSMS(phone: string, message: string): Promise<void> {
// 实现短信发送逻辑
}
}
```
#### 4. 配置依赖注入
```typescript
// src/core/utils/notification/notification.module.ts
@Module({
providers: [
{
provide: 'INotificationService',
useClass: NotificationService,
},
],
exports: ['INotificationService'],
})
export class NotificationModule {}
```
### 🔌 添加新的API接口
#### 1. 定义DTO
```typescript
// src/business/game/dto/create-game.dto.ts
export class CreateGameDto {
@IsString()
@IsNotEmpty()
name: string;
@IsString()
@IsOptional()
description?: string;
}
```
#### 2. 实现Controller
```typescript
// src/business/game/game.controller.ts
@Controller('game')
@ApiTags('游戏管理')
export class GameController {
constructor(private readonly gameService: GameService) {}
@Post()
@ApiOperation({ summary: '创建游戏' })
async createGame(@Body() createGameDto: CreateGameDto) {
return this.gameService.create(createGameDto);
}
}
```
#### 3. 实现Service
```typescript
// src/business/game/game.service.ts
@Injectable()
export class GameService {
constructor(
@Inject('IGameCoreService')
private readonly gameCoreService: IGameCoreService,
) {}
async create(createGameDto: CreateGameDto) {
return this.gameCoreService.createGame(createGameDto);
}
}
```
#### 4. 添加测试用例
```typescript
// src/business/game/game.service.spec.ts
describe('GameService', () => {
let service: GameService;
let gameCoreService: jest.Mocked<IGameCoreService>;
beforeEach(async () => {
const module: TestingModule = await Test.createTestingModule({
providers: [
GameService,
{
provide: 'IGameCoreService',
useValue: {
createGame: jest.fn(),
},
},
],
}).compile();
service = module.get<GameService>(GameService);
gameCoreService = module.get('IGameCoreService');
});
it('should create game', async () => {
const createGameDto = { name: 'Test Game' };
const expectedResult = { id: 1, ...createGameDto };
gameCoreService.createGame.mockResolvedValue(expectedResult);
const result = await service.create(createGameDto);
expect(result).toEqual(expectedResult);
expect(gameCoreService.createGame).toHaveBeenCalledWith(createGameDto);
});
});
```
### 📊 性能优化建议
#### 1. 缓存策略
- **Redis缓存**: 用户会话、验证码、频繁查询数据
- **内存缓存**: 配置信息、静态数据
- **CDN缓存**: 静态资源文件
#### 2. 数据库优化
- **连接池**: 复用数据库连接，减少连接开销
- **索引优化**: 为查询字段建立合适的索引
- **查询优化**: 避免N+1查询，使用JOIN优化关联查询
#### 3. 日志优化
- **异步日志**: 使用Pino的异步写入功能
- **日志分级**: 生产环境只记录ERROR和WARN级别
- **日志轮转**: 自动清理过期日志文件
### 🔒 安全加固建议
#### 1. 数据验证
- **输入验证**: 使用class-validator进行严格验证
- **类型检查**: TypeScript静态类型检查
- **SQL注入防护**: TypeORM参数化查询
#### 2. 认证授权
- **密码安全**: bcrypt加密，强密码策略
- **会话管理**: JWT + Redis会话存储
- **权限控制**: 基于角色的访问控制(RBAC)
#### 3. 通信安全
- **HTTPS**: 生产环境强制HTTPS
- **CORS**: 严格的跨域请求控制
- **Rate Limiting**: API请求频率限制
---
**🏗️ 通过清晰的架构设计，Whale Town 实现了高内聚、低耦合的模块化架构，支持快速开发和灵活部署！**
Reference in New Issue View Git Blame Copy Permalink