whale-town-end/docs/ARCHITECTURE.md

🏗️ Whale Town 项目架构设计

基于四层架构（Gateway-Business-Core-Data）的现代化后端设计，支持双模式运行，开发测试零依赖，生产部署高性能。

📋 目录

• 架构概述
• 四层架构设计
• 目录结构
• 双模式架构
• 模块依赖关系
• 数据流向
• 扩展指南

---

架构概述

Whale Town 采用四层架构设计（Gateway-Business-Core-Data），将协议处理、业务逻辑、技术基础设施和数据存储清晰分离。

核心设计理念

• 职责分离 - 每层职责明确，互不干扰
• 双模式支持 - 开发测试零依赖，生产部署高性能
• 依赖单向 - 上层依赖下层，下层不依赖上层
• 模块化设计 - 每个模块独立完整，可单独测试
• 配置驱动 - 通过环境变量控制运行模式

技术栈

后端： NestJS 11 + TypeScript 5 + MySQL + Redis + 原生WebSocket
前端： React 18 + Vite 7 + Ant Design 5
测试： Jest + Supertest（99个测试用例）
部署： Docker + PM2 + Nginx

---

四层架构设计

架构层次图

┌─────────────────────────────────────────────────────────────┐
│                  🌐 Gateway Layer (网关层)                   │
│  HTTP/WebSocket协议处理、数据验证、路由管理、认证守卫       │
└─────────────────────────────────────────────────────────────┘
                            ⬇️
┌─────────────────────────────────────────────────────────────┐
│                  🎯 Business Layer (业务层)                  │
│  业务逻辑实现、服务协调、业务规则验证、事务管理             │
└─────────────────────────────────────────────────────────────┘
                            ⬇️
┌─────────────────────────────────────────────────────────────┐
│                  ⚙️ Core Layer (核心层)                     │
│  技术基础设施、数据访问、外部系统集成、工具服务             │
└─────────────────────────────────────────────────────────────┘
                            ⬇️
┌─────────────────────────────────────────────────────────────┐
│                  🗄️ Data Layer (数据层)                    │
│  数据持久化、缓存管理、文件存储                             │
└─────────────────────────────────────────────────────────────┘

各层职责

🌐 Gateway Layer（网关层）

位置： src/gateway/

职责：

• HTTP/WebSocket协议处理
• 请求参数验证（DTO）
• 路由管理
• 认证守卫（JWT验证）
• 错误转换（业务错误 → HTTP状态码）
• API文档（Swagger）

原则：

• ✅ 只做协议转换，不做业务逻辑
• ✅ 使用DTO进行数据验证
• ✅ 统一的错误处理
• ❌ 不直接访问数据库
• ❌ 不包含业务规则

示例模块：

• gateway/auth/ - 认证网关（登录、注册接口）
• gateway/location_broadcast/ - 位置广播网关（WebSocket）

🎯 Business Layer（业务层）

位置： src/business/

职责：

• 业务逻辑实现
• 业务流程控制
• 服务协调
• 业务规则验证
• 事务管理

原则：

• ✅ 实现所有业务逻辑
• ✅ 协调多个Core层服务
• ✅ 返回统一的业务响应
• ❌ 不处理HTTP协议
• ❌ 不直接访问数据库

示例模块：

• business/auth/ - 用户认证业务
• business/user_mgmt/ - 用户管理业务
• business/admin/ - 管理员业务
• business/zulip/ - Zulip集成业务
• business/location_broadcast/ - 位置广播业务
• business/notice/ - 公告业务

⚙️ Core Layer（核心层）

位置： src/core/

职责：

• 数据访问（数据库、缓存）
• 基础设施（Redis、消息队列）
• 外部系统集成（Zulip API）
• 技术实现细节
• 工具服务（邮件、验证码、日志）

原则：

• ✅ 提供技术基础设施
• ✅ 数据持久化和缓存
• ✅ 外部API集成
• ❌ 不包含业务逻辑
• ❌ 不处理HTTP协议

示例模块：

• core/db/users/ - 用户数据服务
• core/redis/ - Redis缓存服务
• core/login_core/ - 登录核心服务
• core/admin_core/ - 管理员核心服务
• core/zulip_core/ - Zulip核心服务
• core/security_core/ - 安全核心服务
• core/utils/ - 工具服务（邮件、验证码、日志）

<EFBFBD>️ Data Layer（数据层）

位置： 数据库、Redis、文件系统

职责：

• 数据持久化
• 缓存管理
• 文件存储

实现：

• MySQL / 内存数据库
• Redis / 文件存储
• 日志文件 / 数据文件

---

目录结构

整体结构

whale-town-end/
├── src/
│   ├── gateway/          # 🌐 网关层
│   │   ├── auth/         # 认证网关
│   │   └── location_broadcast/  # 位置广播网关
│   ├── business/         # 🎯 业务层
│   │   ├── auth/         # 用户认证业务
│   │   ├── user_mgmt/    # 用户管理业务
│   │   ├── admin/        # 管理员业务
│   │   ├── zulip/        # Zulip集成业务
│   │   ├── location_broadcast/  # 位置广播业务
│   │   └── notice/       # 公告业务
│   ├── core/             # ⚙️ 核心层
│   │   ├── db/users/     # 用户数据服务
│   │   ├── redis/        # Redis缓存服务
│   │   ├── login_core/   # 登录核心服务
│   │   ├── admin_core/   # 管理员核心服务
│   │   ├── zulip_core/   # Zulip核心服务
│   │   ├── security_core/  # 安全核心服务
│   │   └── utils/        # 工具服务
│   ├── app.module.ts     # 应用主模块
│   └── main.ts           # 应用入口
├── client/               # 🎨 前端管理界面
├── docs/                 # 📚 项目文档
├── test/                 # 🧪 测试文件
└── config/               # ⚙️ 配置文件

网关层结构

src/gateway/
├── auth/                 # 认证网关
│   ├── login.controller.ts
│   ├── register.controller.ts
│   ├── jwt_auth.guard.ts
│   ├── current_user.decorator.ts
│   ├── dto/
│   └── auth.gateway.module.ts
└── location_broadcast/   # 位置广播网关
    ├── location_broadcast.gateway.ts
    └── location_broadcast.gateway.module.ts

业务层结构

src/business/
├── auth/                 # 用户认证业务
│   ├── login.service.ts
│   ├── register.service.ts
│   └── auth.module.ts
├── user_mgmt/            # 用户管理业务
│   ├── user_management.service.ts
│   ├── dto/
│   ├── enums/
│   └── user_mgmt.module.ts
├── admin/                # 管理员业务
│   ├── admin.service.ts
│   └── admin.module.ts
├── zulip/                # Zulip集成业务
│   ├── zulip.service.ts
│   ├── services/
│   └── zulip.module.ts
├── location_broadcast/   # 位置广播业务
│   ├── location_broadcast.service.ts
│   └── location_broadcast.module.ts
└── notice/               # 公告业务
    ├── notice.service.ts
    └── notice.module.ts

核心层结构

src/core/
├── db/users/             # 用户数据服务
│   ├── users.service.ts  # MySQL实现
│   ├── users_memory.service.ts  # 内存实现
│   ├── users.entity.ts
│   └── users.module.ts
├── redis/                # Redis缓存服务
│   ├── real_redis.service.ts
│   ├── file_redis.service.ts
│   └── redis.module.ts
├── login_core/           # 登录核心服务
│   ├── login_core.service.ts
│   └── login_core.module.ts
├── admin_core/           # 管理员核心服务
│   ├── admin_core.service.ts
│   └── admin_core.module.ts
├── zulip_core/           # Zulip核心服务
│   ├── services/
│   ├── config/
│   └── zulip_core.module.ts
├── security_core/        # 安全核心服务
│   ├── guards/
│   ├── interceptors/
│   ├── middleware/
│   └── security_core.module.ts
└── utils/                # 工具服务
    ├── email/
    ├── verification/
    └── logger/

---

双模式架构

模式对比

功能	开发模式	生产模式
数据库	内存存储	MySQL
缓存	文件存储	Redis
邮件	控制台输出	SMTP服务器
日志	控制台+文件	结构化日志

配置示例

开发模式：

USE_FILE_REDIS=true
NODE_ENV=development
# 无需配置数据库和邮件

生产模式：

USE_FILE_REDIS=false
NODE_ENV=production
DB_HOST=your_mysql_host
REDIS_HOST=your_redis_host
EMAIL_HOST=smtp.163.com

实现机制

通过依赖注入和工厂模式实现自动切换：

@Module({
  providers: [
    {
      provide: 'IRedisService',
      useFactory: (config: ConfigService) => {
        return config.get('USE_FILE_REDIS')
          ? new FileRedisService()
          : new RealRedisService(config);
      },
      inject: [ConfigService],
    },
  ],
})
export class RedisModule {}

---

模块依赖关系

依赖方向

Gateway Layer
    ↓ 依赖
Business Layer
    ↓ 依赖
Core Layer
    ↓ 依赖
Data Layer

模块依赖图

AppModule
├── ConfigModule (全局配置)
├── LoggerModule (日志系统)
├── RedisModule (缓存服务)
├── UsersModule (用户数据)
├── EmailModule (邮件服务)
├── VerificationModule (验证码服务)
├── LoginCoreModule (登录核心)
├── AdminCoreModule (管理员核心)
├── ZulipCoreModule (Zulip核心)
├── SecurityCoreModule (安全核心)
│
├── Gateway Layer
│   ├── AuthGatewayModule
│   └── LocationBroadcastGatewayModule
│
└── Business Layer
    ├── AuthModule
    ├── UserMgmtModule
    ├── AdminModule
    ├── ZulipModule
    ├── LocationBroadcastModule
    └── NoticeModule

---

数据流向

用户登录流程

1. 用户请求 → LoginController (Gateway)
2. 参数验证 → DTO Validation
3. 业务逻辑 → LoginService (Business)
4. 核心服务 → LoginCoreService (Core)
5. 数据访问 → UsersService + RedisService (Core)
6. 数据存储 → MySQL/Memory + Redis/File (Data)
7. 返回响应 → 用户收到结果

WebSocket消息流程

1. WebSocket连接 → LocationBroadcastGateway (Gateway)
2. 消息验证 → JWT验证
3. 业务处理 → LocationBroadcastService (Business)
4. 房间管理 → 地图分组逻辑
5. 消息广播 → 同地图用户
6. Zulip同步 → ZulipService (Business)

管理员操作流程

1. 管理员请求 → AdminController (Gateway)
2. 权限验证 → AdminGuard
3. 业务逻辑 → AdminService (Business)
4. 核心服务 → AdminCoreService (Core)
5. 数据更新 → UsersService (Core)
6. 审计日志 → LoggerService (Core)
7. 返回响应 → 管理员收到结果

---

扩展指南

添加新的业务模块

1. 创建目录结构

mkdir -p src/gateway/game
mkdir -p src/business/game
mkdir -p src/core/game_core

2. 实现网关层

// src/gateway/game/game.controller.ts
@Controller('game')
export class GameController {
  constructor(private readonly gameService: GameService) {}
  
  @Post()
  async createGame(@Body() dto: CreateGameDto) {
    return this.gameService.create(dto);
  }
}

3. 实现业务层

// src/business/game/game.service.ts
@Injectable()
export class GameService {
  constructor(
    @Inject('IGameCoreService')
    private readonly gameCoreService: IGameCoreService,
  ) {}
  
  async create(dto: CreateGameDto) {
    // 业务逻辑
    return this.gameCoreService.createGame(dto);
  }
}

4. 实现核心层

// src/core/game_core/game_core.service.ts
@Injectable()
export class GameCoreService {
  async createGame(dto: CreateGameDto) {
    // 数据访问逻辑
  }
}

5. 注册模块

// src/app.module.ts
@Module({
  imports: [
    // ...
    GameGatewayModule,
    GameModule,
    GameCoreModule,
  ],
})
export class AppModule {}

性能优化建议

1. 缓存策略

   • 用户会话 → Redis
   • 验证码 → Redis（短期）
   • 配置信息 → 内存缓存

2. 数据库优化

   • 添加索引
   • 使用连接池
   • 避免N+1查询

3. 日志优化

   • 异步写入
   • 日志分级
   • 日志轮转

安全加固建议

1. 数据验证

   • 使用class-validator
   • TypeScript类型检查
   • SQL注入防护

2. 认证授权

   • JWT认证
   • 角色权限控制
   • 会话管理

3. 通信安全

   • HTTPS强制
   • CORS配置
   • 频率限制

---

参考文档

• 架构重构文档 - 四层架构迁移指南
• 网关层README - 网关层详细说明
• 开发规范 - 代码规范
• 部署指南 - 生产环境部署

---

🏗️ 通过清晰的四层架构设计，Whale Town 实现了职责分离、高内聚、低耦合的现代化架构！