forked from datawhale/whale-town-end
70c020a97c
- 将src/business/security模块迁移至src/core/security_core - 更新模块导入路径和依赖关系 - 统一安全相关组件的命名规范（content_type.middleware.ts） - 清理过时的配置文件和文档 - 更新架构文档以反映新的模块结构 此次重构符合业务功能模块化架构设计原则，将技术基础设施 服务统一放置在core层，提高代码组织的清晰度和可维护性。
773 lines
33 KiB
Markdown
773 lines
33 KiB
Markdown
# 🏗️ 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/ # 💬 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 实现了高内聚、低耦合的模块化架构，支持快速开发和灵活部署！** |