Merge pull request 'docs/update-readme-and-contributors-20260114' (#47) from docs/update-readme-and-contributors-20260114 into main
Reviewed-on: #47
This commit was merged in pull request #47.
This commit is contained in:
488
README.md
488
README.md
@@ -1,35 +1,30 @@
|
|||||||
# 🐋 Whale Town - 像素游戏后端服务
|
# 🐋 Whale Town - 像素游戏后端服务
|
||||||
|
|
||||||
> 一个基于 NestJS 的现代化 2D 像素风游戏后端服务，采用业务功能模块化架构，支持用户认证、管理员后台、安全防护等完整功能。
|
> 基于 NestJS 的现代化 2D 像素游戏后端，采用四层架构（Gateway-Business-Core-Data），支持用户认证、实时通信、Zulip集成、管理员后台。
|
||||||
|
|
||||||
[](https://nodejs.org/)
|
[](https://nodejs.org/)
|
||||||
[](https://nestjs.com/)
|
[](https://nestjs.com/)
|
||||||
[](https://www.typescriptlang.org/)
|
[](https://www.typescriptlang.org/)
|
||||||
[](./LICENSE)
|
[](https://reactjs.org/)
|
||||||
|
[](#)
|
||||||
|
|
||||||
## 🎯 项目简介
|
## 🎯 核心特性
|
||||||
|
|
||||||
Whale Town 是一个功能完整的像素游戏后端服务，采用业务功能模块化架构设计：
|
- 🔐 用户认证：多方式登录、验证码登录、GitHub OAuth
|
||||||
|
- 🌐 实时通信：原生WebSocket、位置广播、地图房间管理
|
||||||
- 🔐 **用户认证模块** - 完整的登录、注册、密码管理、邮箱验证系统
|
- 💬 Zulip集成：游戏内聊天与Zulip社群双向同步
|
||||||
- 👥 **用户管理模块** - 用户状态管理、批量操作、状态统计功能
|
- 👑 管理员后台：React界面、用户管理、日志监控
|
||||||
- 🛡️ **管理员模块** - 管理员认证、用户管理、密码重置、日志查看
|
- 🛡️ 安全防护：频率限制、维护模式、JWT认证
|
||||||
- 🔒 **安全模块** - 频率限制、维护模式、超时控制、内容类型检查
|
- 🗄️ 灵活存储：MySQL/内存双模式、Redis/文件双模式
|
||||||
- 📧 **智能邮件服务** - 支持测试模式和生产模式自动切换
|
- 📚 完整文档：Swagger UI、WebSocket测试工具
|
||||||
- 🗄️ **灵活存储方案** - Redis文件存储 + 内存数据库，支持无依赖测试
|
|
||||||
- 📚 **完整API文档** - Swagger UI + OpenAPI规范，17个接口完整覆盖
|
|
||||||
- 🧪 **全面测试覆盖** - 140个单元测试用例全部通过
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 🚀 快速开始
|
## 🚀 快速开始
|
||||||
|
|
||||||
### 📋 环境要求
|
### 环境要求
|
||||||
|
- Node.js >= 18.0.0
|
||||||
|
- pnpm >= 8.0.0
|
||||||
|
|
||||||
- **Node.js** >= 18.0.0 (推荐 24.7.0)
|
### 安装运行
|
||||||
- **pnpm** >= 8.0.0 (推荐 10.25.0)
|
|
||||||
|
|
||||||
### 🛠️ 安装与运行
|
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# 1. 克隆项目
|
# 1. 克隆项目
|
||||||
@@ -39,429 +34,188 @@ cd whale-town-end
|
|||||||
# 2. 安装依赖
|
# 2. 安装依赖
|
||||||
pnpm install
|
pnpm install
|
||||||
|
|
||||||
# 3. 配置环境（测试模式，无需数据库和邮件服务器）
|
# 3. 配置环境（测试模式，无需数据库）
|
||||||
cp .env.example .env
|
cp .env.example .env
|
||||||
|
|
||||||
# 4. 启动开发服务器
|
# 4. 启动服务
|
||||||
pnpm run dev
|
pnpm run dev
|
||||||
```
|
```
|
||||||
|
|
||||||
🎉 **服务启动成功！** 访问 http://localhost:3000
|
访问：http://localhost:3000
|
||||||
|
|
||||||
### 🧑💻 前端管理界面
|
### 前端管理界面
|
||||||
|
|
||||||
项目包含一个功能完整的前端管理界面，位于 `client/` 目录：
|
|
||||||
|
|
||||||
**🎛️ 核心功能：**
|
|
||||||
- 管理员身份认证（独立Token系统）
|
|
||||||
- 用户列表管理与搜索
|
|
||||||
- 用户密码重置功能
|
|
||||||
- 运行时日志查看与下载
|
|
||||||
- 响应式界面设计
|
|
||||||
|
|
||||||
**🚀 快速启动：**
|
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# 1. 启动后端服务
|
# 启动管理后台
|
||||||
pnpm run dev
|
|
||||||
|
|
||||||
# 2. 启动前端管理界面
|
|
||||||
cd client
|
cd client
|
||||||
pnpm install
|
pnpm install
|
||||||
pnpm run dev
|
pnpm run dev
|
||||||
|
|
||||||
# 3. 访问管理后台
|
|
||||||
# 地址: http://localhost:5173
|
|
||||||
# 默认账号: admin / Admin123456
|
|
||||||
```
|
```
|
||||||
|
|
||||||
### 🧪 快速测试
|
访问：http://localhost:5173
|
||||||
|
默认账号：admin / Admin123456
|
||||||
|
|
||||||
```bash
|
### 在线体验
|
||||||
# 运行综合测试（推荐）
|
|
||||||
.\test-comprehensive.ps1
|
|
||||||
|
|
||||||
# 跳过限流测试（更快）
|
- API文档：https://whaletownend.xinghangee.icu/api-docs
|
||||||
.\test-comprehensive.ps1 -SkipThrottleTest
|
- WebSocket测试：https://whaletownend.xinghangee.icu/websocket-test
|
||||||
|
|
||||||
# 测试远程服务器
|
## 🏗️ 项目架构
|
||||||
.\test-comprehensive.ps1 -BaseUrl "https://your-server.com"
|
|
||||||
```
|
|
||||||
|
|
||||||
**测试内容：**
|
### 四层架构设计
|
||||||
- ✅ 应用状态检查
|
|
||||||
- ✅ 邮箱验证码发送与验证
|
|
||||||
- ✅ 用户注册与登录
|
|
||||||
- ✅ 验证码登录功能
|
|
||||||
- ✅ 密码重置流程
|
|
||||||
- ✅ 邮箱冲突检测
|
|
||||||
- ✅ 验证码冷却时间清除
|
|
||||||
- ✅ 限流保护机制
|
|
||||||
- ✅ Redis文件存储功能
|
|
||||||
- ✅ 邮件测试模式
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 🎓 新开发者指南
|
|
||||||
|
|
||||||
### 第一步：了解项目规范 📚
|
|
||||||
|
|
||||||
**⚠️ 重要：在开始开发前，请务必阅读以下文档**
|
|
||||||
|
|
||||||
1. **[AI辅助开发规范指南](./docs/AI辅助开发规范指南.md)** 🤖
|
|
||||||
- 学会使用AI助手提升开发效率300%
|
|
||||||
- 自动生成符合规范的代码和注释
|
|
||||||
- 实时检查代码质量
|
|
||||||
|
|
||||||
2. **[后端开发规范](./docs/backend_development_guide.md)** 📝
|
|
||||||
- 代码注释标准
|
|
||||||
- 业务逻辑设计原则
|
|
||||||
- 日志记录要求
|
|
||||||
|
|
||||||
3. **[Git提交规范](./docs/git_commit_guide.md)** 🔄
|
|
||||||
- 提交信息格式
|
|
||||||
- 分支管理策略
|
|
||||||
|
|
||||||
### 第二步：熟悉项目架构 🏗️
|
|
||||||
|
|
||||||
**📁 项目文件结构总览**
|
|
||||||
|
|
||||||
```
|
```
|
||||||
whale-town-end/ # 🐋 项目根目录
|
Gateway Layer (网关层)
|
||||||
├── 📂 src/ # 源代码目录
|
↓ HTTP/WebSocket协议处理、数据验证
|
||||||
│ ├── 📂 business/ # 🎯 业务功能模块（按功能组织）
|
Business Layer (业务层)
|
||||||
│ │ ├── 📂 auth/ # 🔐 用户认证模块
|
↓ 业务逻辑实现、服务协调
|
||||||
│ │ ├── 📂 user-mgmt/ # 👥 用户管理模块
|
Core Layer (核心层)
|
||||||
│ │ ├── 📂 admin/ # 🛡️ 管理员模块
|
↓ 技术基础设施、数据访问
|
||||||
│ │ ├── 📂 security/ # 🔒 安全防护模块
|
Data Layer (数据层)
|
||||||
│ │ ├── 📂 zulip/ # 💬 Zulip集成模块
|
↓ 数据持久化、缓存管理
|
||||||
│ │ └── 📂 shared/ # 🔗 共享业务组件
|
|
||||||
│ ├── 📂 core/ # ⚙️ 核心技术服务
|
|
||||||
│ │ ├── 📂 db/ # 🗄️ 数据库层（MySQL/内存双模式）
|
|
||||||
│ │ ├── 📂 redis/ # 🔴 Redis缓存（真实Redis/文件存储）
|
|
||||||
│ │ ├── 📂 login_core/ # 🔑 登录核心服务
|
|
||||||
│ │ ├── 📂 admin_core/ # 👑 管理员核心服务
|
|
||||||
│ │ ├── 📂 zulip/ # 💬 Zulip核心服务
|
|
||||||
│ │ └── 📂 utils/ # 🛠️ 工具服务（邮件、验证码、日志）
|
|
||||||
│ ├── 📄 app.module.ts # 🏠 应用主模块
|
|
||||||
│ └── 📄 main.ts # 🚀 应用入口点
|
|
||||||
├── 📂 client/ # 🎨 前端管理界面
|
|
||||||
│ ├── 📂 src/ # 前端源码
|
|
||||||
│ ├── 📂 dist/ # 前端构建产物
|
|
||||||
│ ├── 📄 package.json # 前端依赖配置
|
|
||||||
│ └── 📄 vite.config.ts # Vite构建配置
|
|
||||||
├── 📂 docs/ # 📚 项目文档中心
|
|
||||||
│ ├── 📂 api/ # 🔌 API接口文档
|
|
||||||
│ ├── 📂 development/ # 💻 开发指南
|
|
||||||
│ ├── 📂 deployment/ # 🚀 部署文档
|
|
||||||
│ ├── 📄 ARCHITECTURE.md # 🏗️ 架构设计文档
|
|
||||||
│ └── 📄 README.md # 📖 文档导航中心
|
|
||||||
├── 📂 test/ # 🧪 测试文件目录
|
|
||||||
├── 📂 config/ # ⚙️ 配置文件目录
|
|
||||||
├── 📂 logs/ # 📝 日志文件存储
|
|
||||||
├── 📂 redis-data/ # 💾 Redis文件存储数据
|
|
||||||
├── 📂 dist/ # 📦 后端构建产物
|
|
||||||
├── 📄 .env # 🔧 环境变量配置
|
|
||||||
├── 📄 package.json # 📋 项目依赖配置
|
|
||||||
├── 📄 docker-compose.yml # 🐳 Docker编排配置
|
|
||||||
├── 📄 Dockerfile # 🐳 Docker镜像配置
|
|
||||||
└── 📄 README.md # 📖 项目主文档（当前文件）
|
|
||||||
```
|
```
|
||||||
|
|
||||||
**架构特点：**
|
### 目录结构
|
||||||
- 🏗️ **业务功能模块化** - 按业务功能而非技术组件组织代码
|
|
||||||
- 🔄 **双模式支持** - 开发测试模式 + 生产部署模式
|
|
||||||
- 📦 **清晰分层** - 业务层 → 核心层 → 数据层
|
|
||||||
- 🧪 **测试友好** - 完整的单元测试和集成测试覆盖
|
|
||||||
|
|
||||||
### 第三步：体验核心功能 🎮
|
```
|
||||||
|
whale-town-end/
|
||||||
|
├── src/
|
||||||
|
│ ├── gateway/ # 网关层：auth, location_broadcast
|
||||||
|
│ ├── business/ # 业务层：auth, user_mgmt, admin, zulip, notice
|
||||||
|
│ ├── core/ # 核心层：db, redis, login_core, admin_core, utils
|
||||||
|
│ ├── app.module.ts
|
||||||
|
│ └── main.ts
|
||||||
|
├── client/ # React管理界面
|
||||||
|
├── docs/ # 项目文档
|
||||||
|
├── test/ # 测试文件
|
||||||
|
└── config/ # 配置文件
|
||||||
|
```
|
||||||
|
|
||||||
1. **API文档系统** 📖
|
详细架构：[docs/ARCHITECTURE.md](./docs/ARCHITECTURE.md)
|
||||||
```bash
|
|
||||||
# 启动服务后访问
|
|
||||||
http://localhost:3000/api-docs
|
|
||||||
```
|
|
||||||
|
|
||||||
2. **用户认证系统** 🔐
|
|
||||||
- 邮箱验证码注册
|
|
||||||
- 多方式登录（用户名/邮箱/手机号）
|
|
||||||
- 密码重置功能
|
|
||||||
|
|
||||||
3. **实时通信** 🌐
|
|
||||||
- WebSocket支持
|
|
||||||
- Socket.IO集成
|
|
||||||
|
|
||||||
### 第四步：开始贡献 🤝
|
|
||||||
|
|
||||||
1. **Fork项目** 到你的Gitea账户
|
|
||||||
2. **创建功能分支**：`git checkout -b feature/your-feature`
|
|
||||||
3. **遵循规范开发**（使用AI助手帮助）
|
|
||||||
4. **提交代码**：`git commit -m "feat：添加新功能"`
|
|
||||||
5. **创建Pull Request**
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 🛠️ 技术栈
|
## 🛠️ 技术栈
|
||||||
|
|
||||||
### 🚀 核心框架
|
**后端：** NestJS 11 + TypeScript 5 + MySQL + Redis + WebSocket
|
||||||
- **NestJS** `^11.1.9` - 企业级Node.js框架，提供依赖注入、模块化等特性
|
**前端：** React 18 + Vite 7 + Ant Design 5
|
||||||
- **TypeScript** `^5.9.3` - 类型安全的JavaScript超集
|
**测试：** Jest + Supertest（99个测试用例）
|
||||||
- **Express** `^10.4.20` - 基于Express的HTTP服务器
|
**部署：** Docker + PM2 + Nginx
|
||||||
- **RxJS** `^7.8.2` - 响应式编程库，处理异步数据流
|
|
||||||
|
|
||||||
### 🌐 实时通信
|
## 📊 开发命令
|
||||||
- **Socket.IO** `^10.4.20` - WebSocket实时双向通信
|
|
||||||
- **@nestjs/websockets** - NestJS WebSocket网关支持
|
|
||||||
- **@nestjs/platform-socket.io** - Socket.IO平台适配器
|
|
||||||
|
|
||||||
### 🗄️ 数据存储
|
|
||||||
- **TypeORM** `^0.3.28` - 强大的ORM框架，支持多种数据库
|
|
||||||
- **MySQL2** `^3.16.0` - 高性能MySQL驱动
|
|
||||||
- **IORedis** `^5.8.2` - Redis客户端，支持集群和哨兵模式
|
|
||||||
- **文件存储** - 自研Redis文件存储适配器，支持无Redis开发
|
|
||||||
|
|
||||||
### 🔐 安全认证
|
|
||||||
- **bcrypt** `^6.0.0` - 密码加密哈希算法
|
|
||||||
- **class-validator** `^0.14.3` - 数据验证装饰器
|
|
||||||
- **class-transformer** `^0.5.1` - 对象转换和序列化
|
|
||||||
|
|
||||||
### 📧 通信服务
|
|
||||||
- **Nodemailer** `^6.10.1` - 邮件发送服务
|
|
||||||
- **Axios** `^1.13.2` - HTTP客户端，支持第三方API调用
|
|
||||||
|
|
||||||
### 📚 API文档
|
|
||||||
- **Swagger UI** `^5.0.1` - 交互式API文档界面
|
|
||||||
- **@nestjs/swagger** `^11.2.3` - NestJS Swagger集成
|
|
||||||
|
|
||||||
### 🧑💻 管理员后台（前端）
|
|
||||||
- **Vite** - 前端构建工具（本项目 admin dashboard 使用）
|
|
||||||
- **React** - 前端 UI 框架
|
|
||||||
- **React Router** - 前端路由
|
|
||||||
- **Ant Design** - 企业级 UI 组件库
|
|
||||||
|
|
||||||
### 📊 日志监控
|
|
||||||
- **Pino** `^10.1.0` - 高性能结构化日志库
|
|
||||||
- **nestjs-pino** `^4.5.0` - NestJS Pino集成
|
|
||||||
- **pino-pretty** `^13.1.3` - Pino日志美化输出
|
|
||||||
|
|
||||||
### 🧪 测试框架
|
|
||||||
- **Jest** `^29.7.0` - JavaScript测试框架
|
|
||||||
- **Supertest** `^7.1.4` - HTTP断言测试
|
|
||||||
- **@nestjs/testing** `^10.4.20` - NestJS测试工具
|
|
||||||
|
|
||||||
### ⚙️ 开发工具
|
|
||||||
- **@nestjs/cli** `^10.4.9` - NestJS命令行工具
|
|
||||||
- **ts-jest** `^29.2.5` - TypeScript Jest支持
|
|
||||||
- **ts-node** `^10.9.2` - TypeScript运行时
|
|
||||||
- **pnpm** - 快速、节省磁盘空间的包管理器
|
|
||||||
|
|
||||||
### 🔄 任务调度
|
|
||||||
- **@nestjs/schedule** `^4.1.2` - 定时任务和计划任务支持
|
|
||||||
|
|
||||||
### 📦 构建部署
|
|
||||||
- **Docker** - 容器化部署
|
|
||||||
- **PM2** - 生产环境进程管理
|
|
||||||
- **Nginx** - 反向代理和负载均衡
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 🏗️ 核心功能
|
|
||||||
|
|
||||||
### 🔐 用户认证模块 (business/auth/)
|
|
||||||
- **多方式登录** - 用户名/邮箱/手机号
|
|
||||||
- **邮箱验证** - 完整的验证码流程
|
|
||||||
- **密码安全** - bcrypt加密 + 强度验证
|
|
||||||
- **第三方登录** - GitHub OAuth支持
|
|
||||||
- **密码管理** - 忘记密码、重置密码、修改密码
|
|
||||||
|
|
||||||
### 👥 用户管理模块 (business/user-mgmt/)
|
|
||||||
- **用户状态管理** - 6种状态控制（active、inactive、locked、banned、deleted、pending）
|
|
||||||
- **批量操作** - 批量修改用户状态
|
|
||||||
- **状态统计** - 各状态用户数量统计
|
|
||||||
- **状态变更日志** - 完整的审计日志
|
|
||||||
|
|
||||||
### 🛡️ 管理员模块 (business/admin/)
|
|
||||||
- **独立认证** - 专用Token系统，与用户系统隔离
|
|
||||||
- **用户管理** - 用户列表、搜索、密码重置
|
|
||||||
- **日志监控** - 实时日志查看、历史日志下载
|
|
||||||
- **权限控制** - 管理员角色验证（role=9）
|
|
||||||
|
|
||||||
### 🔒 安全模块 (business/security/)
|
|
||||||
- **频率限制** - 基于IP的请求频率控制
|
|
||||||
- **维护模式** - 系统维护期间的访问控制
|
|
||||||
- **内容类型验证** - HTTP请求内容类型检查
|
|
||||||
- **超时控制** - 可配置的请求超时机制
|
|
||||||
|
|
||||||
### 📧 智能邮件服务
|
|
||||||
- **测试模式** - 控制台输出，无需SMTP服务器
|
|
||||||
- **生产模式** - 支持主流邮件服务商
|
|
||||||
- **模板系统** - 验证码、欢迎邮件等模板
|
|
||||||
- **自动切换** - 根据配置自动选择模式
|
|
||||||
|
|
||||||
### 🗄️ 灵活存储方案
|
|
||||||
- **Redis文件存储** - 开发测试无需Redis服务器
|
|
||||||
- **内存数据库** - 无需MySQL即可运行
|
|
||||||
- **生产就绪** - 支持MySQL + Redis部署
|
|
||||||
- **自动切换** - 根据配置自动选择存储方式
|
|
||||||
|
|
||||||
### 📚 完整API文档
|
|
||||||
- **Swagger UI** - 交互式API文档
|
|
||||||
- **OpenAPI规范** - 标准化接口描述
|
|
||||||
- **Postman集合** - 可导入的测试集合
|
|
||||||
- **实时更新** - 代码变更自动同步文档
|
|
||||||
|
|
||||||
### 🧪 全面测试覆盖
|
|
||||||
- **单元测试** - 140个测试用例全部通过
|
|
||||||
- **API测试** - 跨平台测试脚本
|
|
||||||
- **集成测试** - 完整业务流程验证
|
|
||||||
- **测试模式** - 无依赖快速测试
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 📊 开发与测试
|
|
||||||
|
|
||||||
### 🔧 开发命令
|
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# 开发服务器（热重载）
|
# 开发
|
||||||
pnpm run dev
|
pnpm run dev # 启动开发服务器
|
||||||
|
pnpm run build # 构建项目
|
||||||
|
pnpm run start:prod # 生产环境运行
|
||||||
|
|
||||||
# 构建项目
|
# 测试
|
||||||
pnpm run build
|
pnpm test # 运行单元测试
|
||||||
|
pnpm run test:cov # 测试覆盖率
|
||||||
# 生产环境运行
|
.\test-comprehensive.ps1 # API功能测试
|
||||||
pnpm run start:prod
|
|
||||||
|
|
||||||
# 代码检查
|
|
||||||
pnpm run lint
|
|
||||||
|
|
||||||
# 格式化代码
|
|
||||||
pnpm run format
|
|
||||||
```
|
```
|
||||||
|
|
||||||
### 🧪 测试命令
|
## 🌍 环境配置
|
||||||
|
|
||||||
|
### 开发环境（默认）
|
||||||
```bash
|
```bash
|
||||||
# 运行所有单元测试
|
USE_FILE_REDIS=true # 使用文件存储（无需Redis）
|
||||||
pnpm test
|
|
||||||
|
|
||||||
# 监听模式运行测试
|
|
||||||
pnpm run test:watch
|
|
||||||
|
|
||||||
# 生成测试覆盖率报告
|
|
||||||
pnpm run test:cov
|
|
||||||
|
|
||||||
# API功能测试（综合测试脚本）
|
|
||||||
.\test-comprehensive.ps1
|
|
||||||
```
|
|
||||||
|
|
||||||
### 📈 测试覆盖率
|
|
||||||
|
|
||||||
- **单元测试**: 140个测试用例 ✅
|
|
||||||
- **功能测试**: 用户认证、用户管理、管理员后台、安全防护 ✅
|
|
||||||
- **集成测试**: 完整业务流程 ✅
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 🌍 部署配置
|
|
||||||
|
|
||||||
### 测试环境（默认）
|
|
||||||
```bash
|
|
||||||
# 无需数据库和邮件服务器
|
|
||||||
USE_FILE_REDIS=true
|
|
||||||
NODE_ENV=development
|
NODE_ENV=development
|
||||||
# 数据库和邮件配置保持注释状态
|
# 无需配置数据库和邮件
|
||||||
```
|
```
|
||||||
|
|
||||||
### 生产环境
|
### 生产环境
|
||||||
```bash
|
```bash
|
||||||
# 启用真实服务
|
|
||||||
USE_FILE_REDIS=false
|
USE_FILE_REDIS=false
|
||||||
NODE_ENV=production
|
NODE_ENV=production
|
||||||
|
|
||||||
# 配置数据库
|
# 数据库
|
||||||
DB_HOST=your_mysql_host
|
DB_HOST=your_mysql_host
|
||||||
DB_USERNAME=your_username
|
DB_USERNAME=your_username
|
||||||
DB_PASSWORD=your_password
|
DB_PASSWORD=your_password
|
||||||
|
|
||||||
# 配置Redis
|
# Redis
|
||||||
REDIS_HOST=your_redis_host
|
REDIS_HOST=your_redis_host
|
||||||
REDIS_PASSWORD=your_password
|
REDIS_PASSWORD=your_password
|
||||||
|
|
||||||
# 配置邮件服务
|
# 邮件
|
||||||
EMAIL_HOST=smtp.gmail.com
|
EMAIL_HOST=smtp.163.com
|
||||||
EMAIL_USER=your_email@gmail.com
|
EMAIL_USER=your_email@163.com
|
||||||
EMAIL_PASS=your_app_password
|
EMAIL_PASS=your_password
|
||||||
|
|
||||||
|
# Zulip
|
||||||
|
ZULIP_SERVER_URL=https://your-zulip.com/
|
||||||
|
ZULIP_BOT_API_KEY=your_api_key
|
||||||
```
|
```
|
||||||
|
|
||||||
详细部署指南：[DEPLOYMENT.md](./DEPLOYMENT.md)
|
详细配置：[docs/deployment/DEPLOYMENT.md](./docs/deployment/DEPLOYMENT.md)
|
||||||
|
|
||||||
---
|
## 📚 文档
|
||||||
|
|
||||||
## 📚 文档中心
|
- [架构设计](./docs/ARCHITECTURE.md) - 四层架构详解
|
||||||
|
- [开发规范](./docs/development/backend_development_guide.md) - 代码规范
|
||||||
|
- [Git规范](./docs/development/git_commit_guide.md) - 提交规范
|
||||||
|
- [API文档](http://localhost:3000/api-docs) - Swagger UI
|
||||||
|
- [测试指南](./docs/development/TESTING.md) - 测试说明
|
||||||
|
|
||||||
### 🎯 新手必读
|
### 🤖 AI代码检查指南
|
||||||
1. **[AI辅助开发指南](./docs/AI辅助开发规范指南.md)** - 提升开发效率300%
|
|
||||||
2. **[后端开发规范](./docs/backend_development_guide.md)** - 代码质量标准
|
|
||||||
3. **[Git提交规范](./docs/git_commit_guide.md)** - 版本控制最佳实践
|
|
||||||
|
|
||||||
### 📖 API文档
|
项目提供了完整的AI辅助代码检查流程，帮助确保代码质量和规范性。
|
||||||
- **[Swagger UI](http://localhost:3000/api-docs)** - 交互式API文档
|
|
||||||
- **[API文档总览](./docs/api/README.md)** - 使用指南
|
|
||||||
- **[OpenAPI规范](./docs/api/openapi.yaml)** - 标准化描述
|
|
||||||
- **[Postman集合](./docs/api/postman-collection.json)** - 测试集合
|
|
||||||
|
|
||||||
### 🏗️ 系统设计
|
**快速开始：**
|
||||||
- **[架构文档](./docs/ARCHITECTURE.md)** - 系统架构设计
|
|
||||||
- **[部署指南](./docs/deployment/DEPLOYMENT.md)** - 生产环境部署
|
|
||||||
|
|
||||||
### 🧪 测试指南
|
向AI发送以下prompt开始代码检查：
|
||||||
- **[测试指南](./docs/development/TESTING.md)** - 完整测试说明
|
|
||||||
- **[单元测试](./src/**/*.spec.ts)** - 测试用例参考
|
|
||||||
|
|
||||||
---
|
```
|
||||||
|
请使用 docs/ai-reading 中readme的规范对 [模块路径] 进行完整的代码检查。
|
||||||
|
```
|
||||||
|
|
||||||
## 🤝 贡献者
|
**如何使用：**
|
||||||
|
- AI会按照7个步骤逐步执行检查（命名规范、注释标准、代码质量、架构层级、测试覆盖、文档生成、代码提交）
|
||||||
|
- 每个步骤完成后会提供检查报告，等待确认后继续下一步
|
||||||
|
- 如有问题会自动修复并重新验证
|
||||||
|
- 这里建议每个步骤结束后，人工确认是否执行了修复，如果进行了修复，请告诉他：请重新执行一遍该步骤，看看是否有遗漏。
|
||||||
|
|
||||||
感谢所有为项目做出贡献的开发者！
|
详细说明：[docs/ai-reading/README.md](./docs/ai-reading/README.md) | 开发者规范：[docs/开发者代码检查规范.md](./docs/开发者代码检查规范.md)
|
||||||
|
|
||||||
### 🏆 核心团队
|
## 🤝 参与贡献
|
||||||
- **[moyin](https://gitea.xinghangee.icu/moyin)** - 核心开发者
|
|
||||||
- **[jianuo](https://gitea.xinghangee.icu/jianuo)** - 核心开发者
|
|
||||||
- **[angjustinl](https://gitea.xinghangee.icu/ANGJustinl)** - 核心开发者
|
|
||||||
|
|
||||||
查看完整贡献者名单：[docs/CONTRIBUTORS.md](./docs/CONTRIBUTORS.md)
|
### 贡献流程
|
||||||
|
1. Fork项目
|
||||||
|
2. 创建分支：`git checkout -b feature/your-feature`
|
||||||
|
3. 开发功能（遵循开发规范）
|
||||||
|
4. 运行测试：`pnpm test`
|
||||||
|
5. 提交代码：`git commit -m "feat: 添加新功能"`
|
||||||
|
6. 创建Pull Request
|
||||||
|
|
||||||
### 🌟 如何贡献
|
### 核心团队
|
||||||
|
- [moyin](https://gitea.xinghangee.icu/moyin)
|
||||||
|
- [jianuo](https://gitea.xinghangee.icu/jianuo)
|
||||||
|
- [angjustinl](https://gitea.xinghangee.icu/ANGJustinl)
|
||||||
|
|
||||||
我们欢迎所有形式的贡献：
|
完整贡献者：[docs/CONTRIBUTORS.md](./docs/CONTRIBUTORS.md)
|
||||||
|
|
||||||
1. **<EFBFBD> Bug修复** - 发现并修复问题
|
## 📝 版本历史
|
||||||
2. **✨ 新功能** - 添加有价值的功能
|
|
||||||
3. **<EFBFBD> 文档改馈进** - 完善项目文档
|
|
||||||
4. **🧪 测试用例** - 提高代码覆盖率
|
|
||||||
5. **💡 建议反馈** - 提出改进建议
|
|
||||||
|
|
||||||
**贡献流程：**
|
- **v2.1.0** (2026-01) - WebSocket架构升级、地图房间管理
|
||||||
1. Fork项目 → 2. 创建分支 → 3. 开发功能 → 4. 提交PR
|
- **v2.0.0** (2025-12) - 四层架构重构、Zulip集成、管理员后台
|
||||||
|
- **v1.2.0** (2025-11) - 用户管理、安全防护、邮件服务
|
||||||
|
- **v1.0.0** (2025-10) - 项目初始化、用户认证、双模式存储
|
||||||
|
|
||||||
---
|
## 📞 联系方式
|
||||||
|
|
||||||
## 📞 联系我们
|
- 项目地址：[Gitea Repository](https://gitea.xinghangee.icu/datawhale/whale-town-end)
|
||||||
|
- 问题反馈：[Issues](https://gitea.xinghangee.icu/datawhale/whale-town-end/issues)
|
||||||
- **项目地址**: [Gitea Repository](https://gitea.xinghangee.icu/datawhale/whale-town-end)
|
- 功能建议：[Discussions](https://gitea.xinghangee.icu/datawhale/whale-town-end/discussions)
|
||||||
- **问题反馈**: [Issues](https://gitea.xinghangee.icu/datawhale/whale-town-end/issues)
|
|
||||||
- **功能建议**: [Discussions](https://gitea.xinghangee.icu/datawhale/whale-town-end/discussions)
|
|
||||||
|
|
||||||
## 📄 许可证
|
## 📄 许可证
|
||||||
|
|
||||||
本项目采用 [MIT License](./LICENSE) 开源协议。
|
[MIT License](./LICENSE)
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
<div align="center">
|
<div align="center">
|
||||||
|
|
||||||
**🐋 Whale Town - 让像素世界更精彩！**
|
**🐋 Whale Town - 让像素世界更精彩 ！**
|
||||||
|
|
||||||
Made with ❤️ by the Whale Town Team
|
Made with ❤️ by the Whale Town Team
|
||||||
|
|
||||||
|
|||||||
1063
docs/ARCHITECTURE.md
1063
docs/ARCHITECTURE.md
File diff suppressed because it is too large
Load Diff
@@ -4,116 +4,149 @@
|
|||||||
|
|
||||||
## 核心贡献者
|
## 核心贡献者
|
||||||
|
|
||||||
|
### <20> 项目维护者
|
||||||
|
|
||||||
|
**moyin** - 项目维护者
|
||||||
|
- Gitea: [@moyin](https://gitea.xinghangee.icu/moyin)
|
||||||
|
- Email: xinghang_a@proton.me
|
||||||
|
- 提交数: **166 commits** (不含合并提交)
|
||||||
|
- 主要贡献：
|
||||||
|
- 🚀 **项目架构设计** - 四层架构（Gateway-Business-Core-Data）设计与实现
|
||||||
|
- <20> **用户认证系统** - 完整的登录、注册、JWT认证、验证码登录
|
||||||
|
- 📧 **邮箱验证系统** - 邮件服务、验证码服务、冷却时间机制
|
||||||
|
- <20>️ **双模式架构** - Redis缓存（文件/真实）、用户服务（内存/数据库）
|
||||||
|
- <20> **API文档系统** - Swagger UI、OpenAPI规范、WebSocket文档
|
||||||
|
- 🧪 **测试框架** - Jest配置、507+测试用例、集成测试、E2E测试
|
||||||
|
- <20> **日志系统** - Pino高性能日志、结构化日志、日志管理
|
||||||
|
- 🏗️ **架构重构** - Zulip模块重构、认证模块分层、安全模块迁移
|
||||||
|
- 📚 **文档体系** - 架构文档、开发规范、AI代码检查指南、部署文档
|
||||||
|
- 🎮 **游戏功能** - 位置广播系统、通知系统、地图房间管理
|
||||||
|
- 🔧 **项目配置** - TypeScript配置、构建配置、环境配置、Docker部署
|
||||||
|
- 🐛 **问题修复** - 验证码TTL重置、依赖注入、HTTP状态码、数据库管理
|
||||||
|
|
||||||
### 🌟 核心开发者
|
### 🌟 核心开发者
|
||||||
|
|
||||||
|
**jianuo** - 核心开发者
|
||||||
|
- Gitea: [@jianuo](https://gitea.xinghangee.icu/jianuo)
|
||||||
|
- Email: 32106500027@e.gzhu.edu.cn
|
||||||
|
- 提交数: **10 commits** (不含合并提交)
|
||||||
|
- 主要贡献：
|
||||||
|
- 🎛️ **管理员后台系统** - React前端界面、Ant Design组件、完整CRUD功能
|
||||||
|
- 📊 **日志管理功能** - 运行时日志查看、日志下载、日志分析
|
||||||
|
- <20> **管理员认证** - 独立Token认证、权限控制、会话管理
|
||||||
|
- 🧪 **单元测试** - 管理员功能测试用例、测试覆盖率提升
|
||||||
|
- ⚙️ **TypeScript配置** - Node16模块解析、编译配置优化
|
||||||
|
- 🐳 **Docker部署** - 容器化部署问题修复、部署脚本优化
|
||||||
|
- 📖 **文档维护** - 技术栈文档、部署文档、错误修复文档
|
||||||
|
|
||||||
**angjustinl** - 核心开发者
|
**angjustinl** - 核心开发者
|
||||||
- Gitea: [@ANGJustinl](https://gitea.xinghangee.icu/ANGJustinl)
|
- Gitea: [@ANGJustinl](https://gitea.xinghangee.icu/ANGJustinl)
|
||||||
- GitHub: [@ANGJustinl](https://github.com/ANGJustinl)
|
- GitHub: [@ANGJustinl](https://github.com/ANGJustinl)
|
||||||
- Email: 96008766+ANGJustinl@users.noreply.github.com
|
- Email: 96008766+ANGJustinl@users.noreply.github.com
|
||||||
- 提交数: **7 commits**
|
- 提交数: **9 commits** (不含合并提交)
|
||||||
- 主要贡献：
|
- 主要贡献：
|
||||||
- 🔄 邮箱验证流程重构与优化
|
- <EFBFBD> **Zulip集成系统** - 完整的Zulip实时通信系统、WebSocket连接、消息同步
|
||||||
- 💾 基于内存的用户服务实现
|
- 🔑 **JWT认证重构** - JWT验证机制、API密钥管理、Token刷新
|
||||||
- 🛠️ API响应处理改进
|
- <EFBFBD> **邮箱验证重构** - 验证流程优化、内存用户服务、API响应改进
|
||||||
- 🧪 测试用例完善与错误修复
|
- <EFBFBD> **验证码登录** - 验证码登录功能实现、测试用例编写
|
||||||
- 📚 系统架构优化
|
- 🧪 **测试优化** - E2E测试修复、测试断言更新、测试覆盖完善
|
||||||
- 💬 **Zulip集成系统** - 完整的Zulip实时通信系统开发
|
- 🏗️ **Zulip账户管理** - Zulip账户创建、绑定、同步机制
|
||||||
- 🔧 **E2E测试修复** - Zulip集成的端到端测试优化
|
|
||||||
- 🎯 **验证码登录测试** - 验证码登录功能测试用例编写
|
|
||||||
|
|
||||||
**jianuo** - 核心开发者
|
|
||||||
- Gitea: [@jianuo](https://gitea.xinghangee.icu/jianuo)
|
|
||||||
- Email: 32106500027@e.gzhu.edu.cn
|
|
||||||
- 提交数: **11 commits**
|
|
||||||
- 主要贡献：
|
|
||||||
- 🎛️ **管理员后台系统** - 完整的前后端管理界面开发
|
|
||||||
- 📊 **日志管理功能** - 运行时日志查看与下载系统
|
|
||||||
- 🔐 **管理员认证系统** - 独立Token认证与权限控制
|
|
||||||
- 🧪 **单元测试完善** - 管理员功能测试用例编写
|
|
||||||
- ⚙️ **TypeScript配置优化** - Node16模块解析配置
|
|
||||||
- 🐳 **Docker部署优化** - 容器化部署问题修复
|
|
||||||
- 📖 **技术栈文档更新** - 项目技术栈说明完善
|
|
||||||
- 🔧 **项目配置优化** - 构建和开发环境配置改进
|
|
||||||
|
|
||||||
### 🏆 主要维护者
|
|
||||||
|
|
||||||
**moyin** - 主要维护者
|
|
||||||
- Gitea: [@moyin](https://gitea.xinghangee.icu/moyin)
|
|
||||||
- Email: xinghang_a@proton.me
|
|
||||||
- 提交数: **112 commits**
|
|
||||||
- 主要贡献：
|
|
||||||
- 🚀 项目架构设计与初始化
|
|
||||||
- 🔐 完整用户认证系统实现
|
|
||||||
- 📧 邮箱验证系统设计与开发
|
|
||||||
- 🗄️ Redis缓存服务（文件存储+真实Redis双模式）
|
|
||||||
- 📝 完整的API文档系统（Swagger UI + OpenAPI）
|
|
||||||
- 🧪 测试框架搭建与507个测试用例编写
|
|
||||||
- 📊 高性能日志系统集成（Pino）
|
|
||||||
- 🔧 项目配置优化与部署方案
|
|
||||||
- 🐛 验证码TTL重置关键问题修复
|
|
||||||
- 📚 完整的项目文档体系建设
|
|
||||||
- 🏗️ **Zulip模块架构重构** - 业务功能模块化架构设计与实现
|
|
||||||
- 📖 **架构文档重写** - 详细的架构设计文档和开发者指南
|
|
||||||
- 🔄 **验证码冷却时间优化** - 自动清除机制设计与实现
|
|
||||||
- 📋 **文档清理优化** - 项目文档结构化整理和维护体系建立
|
|
||||||
|
|
||||||
## 贡献统计
|
## 贡献统计
|
||||||
|
|
||||||
| 贡献者 | 提交数 | 主要领域 | 贡献占比 |
|
| 贡献者 | 提交数 | 主要领域 | 贡献占比 |
|
||||||
|--------|--------|----------|----------|
|
|--------|--------|----------|----------|
|
||||||
| angjustinl | 7 | Zulip集成、功能优化、测试、重构 | 5% |
|
| moyin | 166 | 架构设计、核心功能、文档、测试、重构 | 89.7% |
|
||||||
| jianuo | 11 | 管理员后台、日志系统、部署优化、配置管理 | 8% |
|
| jianuo | 10 | 管理员后台、日志系统、部署优化 | 5.4% |
|
||||||
| moyin | 112 | 架构设计、核心功能、文档、测试、Zulip重构 | 86% |
|
| angjustinl | 9 | Zulip集成、JWT认证、验证码登录 | 4.9% |
|
||||||
|
|
||||||
## 🌟 最新重要贡献
|
## 🌟 最新重要贡献
|
||||||
|
|
||||||
### 🏗️ Zulip模块架构重构 (2025年12月31日)
|
### 🏗️ 四层架构重构与规范化 (2026年1月)
|
||||||
**主要贡献者**: moyin, angjustinl
|
|
||||||
|
|
||||||
这是项目历史上最重要的架构重构之一：
|
|
||||||
|
|
||||||
- **架构重构**: 实现业务功能模块化架构，将Zulip模块按照业务层和核心层进行清晰分离
|
|
||||||
- **代码迁移**: 36个文件的重构和迁移，涉及2773行代码的新增和125行的删除
|
|
||||||
- **依赖注入**: 通过接口抽象实现业务层与核心层的完全解耦
|
|
||||||
- **测试完善**: 所有507个测试用例通过，确保重构的安全性
|
|
||||||
|
|
||||||
### 📚 项目文档体系优化 (2025年12月31日)
|
|
||||||
**主要贡献者**: moyin
|
**主要贡献者**: moyin
|
||||||
|
|
||||||
- **架构文档重写**: `docs/ARCHITECTURE.md` 从简单架构图扩展为800+行的完整架构设计文档
|
项目完成了重大的架构升级和代码规范化工作：
|
||||||
- **README优化**: 采用总分结构设计，详细的文件结构总览
|
|
||||||
- **文档清理**: 新增 `docs/DOCUMENT_CLEANUP.md` 记录文档维护过程
|
|
||||||
- **开发者体验**: 建立完整的文档导航体系，提升开发者上手体验
|
|
||||||
|
|
||||||
### 💬 Zulip集成系统 (2025年12月25日)
|
- **认证模块重构** (1月14日): 将Gateway层组件从Business层分离，实现清晰的四层架构
|
||||||
**主要贡献者**: angjustinl
|
- **依赖注入优化** (1月14日): 修复AuthGatewayModule依赖注入问题，完善NestJS模块系统
|
||||||
|
- **AI代码检查体系** (1月14日): 建立完整的AI辅助代码检查流程和规范文档
|
||||||
|
- **架构文档完善** (1月14日): 新增架构重构文档、Gateway层规范、NestJS命名规范
|
||||||
|
- **代码规范优化** (1月12日): 完善多个核心模块的代码规范和测试覆盖
|
||||||
|
|
||||||
- **完整集成**: 实现与Zulip的完整集成，支持实时通信功能
|
### 📚 代码质量与测试提升 (2026年1月)
|
||||||
- **WebSocket支持**: 建立稳定的WebSocket连接和消息处理机制
|
**主要贡献者**: moyin
|
||||||
- **测试覆盖**: 完善的E2E测试确保集成功能的稳定性
|
|
||||||
|
- **测试覆盖完善** (1月12日): 完善users、zulip、verification等模块测试覆盖
|
||||||
|
- **文档体系建设** (1月12日): 添加开发者代码检查规范、AI代码检查执行指南
|
||||||
|
- **性能优化** (1月12日): 集成高性能缓存系统和结构化日志
|
||||||
|
- **模块功能扩展** (1月12日): 添加Zulip动态配置控制器和账户业务服务
|
||||||
|
|
||||||
|
### 🎮 游戏功能扩展 (2026年1月)
|
||||||
|
**主要贡献者**: moyin
|
||||||
|
|
||||||
|
- **通知系统** (1月10日): 实现完整的通知系统核心功能和数据库支持
|
||||||
|
- **WebSocket优化** (1月9日): 统一WebSocket网关配置、增强测试页面用户体验
|
||||||
|
- **原生WebSocket** (1月9日): 移除Socket.IO依赖，实现原生WebSocket支持
|
||||||
|
- **位置广播系统** (1月8日): 实现位置广播系统和端到端测试
|
||||||
|
- **管理员系统** (1月8日): 完善管理员系统核心功能和用户管理模块
|
||||||
|
|
||||||
|
### 🏗️ Zulip模块架构重构 (2025年12月)
|
||||||
|
**主要贡献者**: moyin, angjustinl
|
||||||
|
|
||||||
|
- **架构重构** (12月31日): 实现业务功能模块化架构，清晰分离业务层和核心层
|
||||||
|
- **Zulip集成** (12月25日): angjustinl开发完整的Zulip实时通信系统
|
||||||
|
- **JWT认证** (1月6日): angjustinl引入JWT验证并重构API密钥管理
|
||||||
|
- **账户管理** (1月5日): angjustinl添加Zulip账户管理和认证系统集成
|
||||||
|
|
||||||
## 项目里程碑
|
## 项目里程碑
|
||||||
|
|
||||||
|
### 2026年1月
|
||||||
|
- **1月14日**: 🏗️ 认证模块四层架构重构，Gateway层与Business层清晰分离
|
||||||
|
- **1月14日**: 🔧 修复AuthGatewayModule依赖注入问题，完善模块系统
|
||||||
|
- **1月14日**: 📚 建立AI代码检查体系，添加完整的规范文档
|
||||||
|
- **1月14日**: 📖 新增架构重构文档和NestJS框架规范说明
|
||||||
|
- **1月12日**: ✨ 完善多个核心模块的代码规范和测试覆盖
|
||||||
|
- **1月12日**: 🧪 添加Zulip业务模块完整测试覆盖
|
||||||
|
- **1月12日**: 📝 添加开发者代码检查规范和AI检查执行指南
|
||||||
|
- **1月12日**: ⚡ 集成高性能缓存系统和结构化日志
|
||||||
|
- **1月10日**: 🔔 实现通知系统核心功能和数据库支持
|
||||||
|
- **1月10日**: 🐛 修复数据库管理服务的关键问题
|
||||||
|
- **1月9日**: 🌐 统一WebSocket网关配置，增强测试页面
|
||||||
|
- **1月9日**: 🔄 移除Socket.IO依赖，实现原生WebSocket支持
|
||||||
|
- **1月8日**: 📍 实现位置广播系统和端到端测试
|
||||||
|
- **1月8日**: 👑 完善管理员系统核心功能
|
||||||
|
- **1月8日**: 🏗️ 项目架构重构和命名规范化
|
||||||
|
- **1月7日**: 📦 升级到v2.0.0版本
|
||||||
|
- **1月6日**: 🔑 angjustinl引入JWT验证并重构API密钥管理
|
||||||
|
- **1月5日**: 👤 angjustinl添加Zulip账户管理和认证系统集成
|
||||||
|
- **1月4日**: 🛡️ 重构安全模块架构，迁移至core层
|
||||||
|
|
||||||
### 2025年12月
|
### 2025年12月
|
||||||
- **12月17日**: 项目初始化，完成基础架构搭建
|
- **12月31日**: 🏗️ Zulip模块业务功能模块化架构重构
|
||||||
- **12月17日**: 实现完整的用户认证系统
|
- **12月31日**: 📚 项目文档结构化整理和架构文档重写
|
||||||
- **12月17日**: 完成API文档系统集成
|
- **12月25日**: 💬 angjustinl开发完整的Zulip集成系统
|
||||||
- **12月17日**: 实现邮箱验证系统
|
- **12月25日**: 🔄 实现验证码冷却时间自动清除机制
|
||||||
- **12月17日**: 修复验证码TTL重置关键问题
|
- **12月25日**: 📧 完成邮箱冲突检测优化v1.1.1
|
||||||
- **12月18日**: angjustinl重构邮箱验证流程，引入内存用户服务
|
- **12月25日**: 🎯 angjustinl实现验证码登录功能
|
||||||
- **12月18日**: jianuo修复Docker部署问题
|
- **12月25日**: 📈 升级项目版本到v1.1.0
|
||||||
- **12月18日**: 完成测试用例修复和优化
|
- **12月24日**: 🐛 修复注册逻辑和HTTP状态码问题
|
||||||
- **12月19日**: jianuo开发管理员后台系统
|
- **12月24日**: 🔧 修复API状态码和限流配置问题
|
||||||
- **12月20日**: jianuo完善日志管理功能
|
- **12月24日**: 🏗️ 重构项目结构和业务模块架构
|
||||||
- **12月21日**: jianuo添加管理员后台单元测试
|
- **12月23日**: 📖 全面更新API接口文档
|
||||||
- **12月22日**: 管理员后台功能合并到主分支
|
- **12月22日**: 🎛️ jianuo的管理员后台功能合并到主分支
|
||||||
- **12月25日**: angjustinl开发完整的Zulip集成系统
|
- **12月19日**: 👑 jianuo开发管理员后台系统
|
||||||
- **12月25日**: 实现验证码冷却时间自动清除机制
|
- **12月19日**: 📊 jianuo完善日志管理功能
|
||||||
- **12月25日**: 完成邮箱冲突检测优化v1.1.1
|
- **12月19日**: 🧪 jianuo添加管理员后台单元测试
|
||||||
- **12月25日**: 升级项目版本到v1.1.0
|
- **12月19日**: ⚙️ jianuo优化TypeScript配置
|
||||||
- **12月31日**: **重大架构重构** - 完成Zulip模块业务功能模块化架构重构
|
- **12月18日**: 🔄 angjustinl重构邮箱验证流程，引入内存用户服务
|
||||||
- **12月31日**: **文档体系优化** - 项目文档结构化整理和架构文档重写
|
- **12月18日**: 🐳 jianuo修复Docker部署问题
|
||||||
- **12月31日**: **测试覆盖完善** - 所有507个测试用例通过，测试覆盖率达到新高
|
- **12月18日**: 🧪 完成测试用例修复和优化
|
||||||
|
- **12月17日**: 🐛 修复验证码TTL重置关键问题
|
||||||
|
- **12月17日**: 📧 实现完整的邮箱验证系统
|
||||||
|
- **12月17日**: 🗄️ 实现Redis缓存服务（双模式）
|
||||||
|
- **12月17日**: 📝 完成API文档系统集成
|
||||||
|
- **12月17日**: 🔐 实现完整的用户认证系统
|
||||||
|
- **12月17日**: 🚀 项目初始化，完成基础架构搭建
|
||||||
|
|
||||||
## 如何成为贡献者
|
## 如何成为贡献者
|
||||||
|
|
||||||
@@ -137,9 +170,10 @@
|
|||||||
### 贡献规范
|
### 贡献规范
|
||||||
|
|
||||||
请在贡献前阅读：
|
请在贡献前阅读：
|
||||||
- [AI辅助开发规范指南](./docs/AI辅助开发规范指南.md)
|
- [开发者代码检查规范](./开发者代码检查规范.md)
|
||||||
- [后端开发规范](./docs/backend_development_guide.md)
|
- [后端开发规范](./development/backend_development_guide.md)
|
||||||
- [Git提交规范](./docs/git_commit_guide.md)
|
- [Git提交规范](./development/git_commit_guide.md)
|
||||||
|
- [AI代码检查指南](./ai-reading/README.md)
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
|
|||||||
@@ -1,45 +1,220 @@
|
|||||||
# 后端开发规范指南
|
# 后端开发规范指南
|
||||||
|
|
||||||
本文档定义了后端开发的核心规范，包括注释规范、日志规范、业务逻辑规范等，确保代码质量和团队协作效率。
|
本文档定义了基于四层架构的后端开发规范，包括架构规范、注释规范、日志规范、代码质量规范等。
|
||||||
|
|
||||||
## 📋 目录
|
## 📋 目录
|
||||||
|
|
||||||
|
- [架构规范](#架构规范)
|
||||||
- [注释规范](#注释规范)
|
- [注释规范](#注释规范)
|
||||||
- [日志规范](#日志规范)
|
- [日志规范](#日志规范)
|
||||||
- [业务逻辑规范](#业务逻辑规范)
|
|
||||||
- [异常处理规范](#异常处理规范)
|
- [异常处理规范](#异常处理规范)
|
||||||
- [代码质量规范](#代码质量规范)
|
- [代码质量规范](#代码质量规范)
|
||||||
- [最佳实践](#最佳实践)
|
- [最佳实践](#最佳实践)
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 📝 注释规范
|
## 🏗️ 架构规范
|
||||||
|
|
||||||
|
### 四层架构原则
|
||||||
|
|
||||||
|
项目采用 **Gateway-Business-Core-Data** 四层架构，每层职责明确：
|
||||||
|
|
||||||
|
```
|
||||||
|
Gateway Layer (网关层)
|
||||||
|
↓ 依赖
|
||||||
|
Business Layer (业务层)
|
||||||
|
↓ 依赖
|
||||||
|
Core Layer (核心层)
|
||||||
|
↓ 依赖
|
||||||
|
Data Layer (数据层)
|
||||||
|
```
|
||||||
|
|
||||||
|
### 各层职责
|
||||||
|
|
||||||
|
#### 🌐 Gateway Layer（网关层）
|
||||||
|
|
||||||
|
**位置：** `src/gateway/`
|
||||||
|
|
||||||
|
**职责：**
|
||||||
|
- HTTP/WebSocket协议处理
|
||||||
|
- 请求参数验证（DTO）
|
||||||
|
- 路由管理
|
||||||
|
- 认证守卫
|
||||||
|
- 错误转换
|
||||||
|
|
||||||
|
**规范：**
|
||||||
|
```typescript
|
||||||
|
// ✅ 正确：只做协议转换
|
||||||
|
@Controller('auth')
|
||||||
|
export class LoginController {
|
||||||
|
constructor(private readonly loginService: LoginService) {}
|
||||||
|
|
||||||
|
@Post('login')
|
||||||
|
async login(@Body() dto: LoginDto, @Res() res: Response) {
|
||||||
|
const result = await this.loginService.login(dto);
|
||||||
|
this.handleResponse(result, res);
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
// ❌ 错误：包含业务逻辑
|
||||||
|
@Controller('auth')
|
||||||
|
export class LoginController {
|
||||||
|
@Post('login')
|
||||||
|
async login(@Body() dto: LoginDto) {
|
||||||
|
const user = await this.usersService.findByEmail(dto.email);
|
||||||
|
const isValid = await bcrypt.compare(dto.password, user.password);
|
||||||
|
// ... 更多业务逻辑
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
#### 🎯 Business Layer（业务层）
|
||||||
|
|
||||||
|
**位置：** `src/business/`
|
||||||
|
|
||||||
|
**职责：**
|
||||||
|
- 业务逻辑实现
|
||||||
|
- 服务协调
|
||||||
|
- 业务规则验证
|
||||||
|
- 事务管理
|
||||||
|
|
||||||
|
**规范：**
|
||||||
|
```typescript
|
||||||
|
// ✅ 正确：实现业务逻辑
|
||||||
|
@Injectable()
|
||||||
|
export class LoginService {
|
||||||
|
constructor(
|
||||||
|
private readonly loginCoreService: LoginCoreService,
|
||||||
|
private readonly emailService: EmailService,
|
||||||
|
) {}
|
||||||
|
|
||||||
|
async login(dto: LoginDto): Promise<ApiResponse<LoginResponse>> {
|
||||||
|
try {
|
||||||
|
// 1. 调用核心服务验证
|
||||||
|
const user = await this.loginCoreService.validateUser(dto);
|
||||||
|
|
||||||
|
// 2. 业务逻辑：生成Token
|
||||||
|
const tokens = await this.loginCoreService.generateTokens(user);
|
||||||
|
|
||||||
|
// 3. 业务逻辑：发送登录通知
|
||||||
|
await this.emailService.sendLoginNotification(user.email);
|
||||||
|
|
||||||
|
return { success: true, data: tokens };
|
||||||
|
} catch (error) {
|
||||||
|
return { success: false, message: error.message };
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
// ❌ 错误：直接访问数据库
|
||||||
|
@Injectable()
|
||||||
|
export class LoginService {
|
||||||
|
async login(dto: LoginDto) {
|
||||||
|
const user = await this.userRepository.findOne({ email: dto.email });
|
||||||
|
// ...
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
#### ⚙️ Core Layer（核心层）
|
||||||
|
|
||||||
|
**位置：** `src/core/`
|
||||||
|
|
||||||
|
**职责：**
|
||||||
|
- 数据访问
|
||||||
|
- 基础设施
|
||||||
|
- 外部系统集成
|
||||||
|
- 工具服务
|
||||||
|
|
||||||
|
**规范：**
|
||||||
|
```typescript
|
||||||
|
// ✅ 正确：提供技术基础设施
|
||||||
|
@Injectable()
|
||||||
|
export class LoginCoreService {
|
||||||
|
constructor(
|
||||||
|
@Inject('IUsersService')
|
||||||
|
private readonly usersService: IUsersService,
|
||||||
|
@Inject('IRedisService')
|
||||||
|
private readonly redisService: IRedisService,
|
||||||
|
) {}
|
||||||
|
|
||||||
|
async validateUser(dto: LoginDto): Promise<User> {
|
||||||
|
const user = await this.usersService.findByEmail(dto.email);
|
||||||
|
if (!user) {
|
||||||
|
throw new UnauthorizedException('用户不存在');
|
||||||
|
}
|
||||||
|
|
||||||
|
const isValid = await bcrypt.compare(dto.password, user.password);
|
||||||
|
if (!isValid) {
|
||||||
|
throw new UnauthorizedException('密码错误');
|
||||||
|
}
|
||||||
|
|
||||||
|
return user;
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
// ❌ 错误：包含业务逻辑
|
||||||
|
@Injectable()
|
||||||
|
export class LoginCoreService {
|
||||||
|
async validateUser(dto: LoginDto) {
|
||||||
|
// 发送邮件通知 - 这是业务逻辑，应该在Business层
|
||||||
|
await this.emailService.sendLoginNotification(user.email);
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### 模块组织规范
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
// 模块命名：功能名.module.ts
|
||||||
|
// 服务命名：功能名.service.ts
|
||||||
|
// 控制器命名：功能名.controller.ts
|
||||||
|
// 网关命名：功能名.gateway.ts
|
||||||
|
|
||||||
|
// ✅ 正确的模块结构
|
||||||
|
src/
|
||||||
|
├── gateway/
|
||||||
|
│ └── auth/
|
||||||
|
│ ├── login.controller.ts
|
||||||
|
│ ├── register.controller.ts
|
||||||
|
│ ├── jwt_auth.guard.ts
|
||||||
|
│ ├── dto/
|
||||||
|
│ └── auth.gateway.module.ts
|
||||||
|
├── business/
|
||||||
|
│ └── auth/
|
||||||
|
│ ├── login.service.ts
|
||||||
|
│ ├── register.service.ts
|
||||||
|
│ └── auth.module.ts
|
||||||
|
└── core/
|
||||||
|
└── login_core/
|
||||||
|
├── login_core.service.ts
|
||||||
|
└── login_core.module.ts
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## <20> 注释规规范
|
||||||
|
|
||||||
### 文件头注释
|
### 文件头注释
|
||||||
|
|
||||||
每个 TypeScript 文件都必须包含完整的文件头注释：
|
|
||||||
|
|
||||||
```typescript
|
```typescript
|
||||||
/**
|
/**
|
||||||
* 文件功能描述
|
* 用户登录服务
|
||||||
*
|
*
|
||||||
* 功能描述：
|
* 功能描述：
|
||||||
* - 主要功能点1
|
* - 处理用户登录业务逻辑
|
||||||
* - 主要功能点2
|
* - 协调登录核心服务和邮件服务
|
||||||
* - 主要功能点3
|
* - 生成JWT令牌
|
||||||
*
|
*
|
||||||
* 职责分离：
|
* 架构层级：Business Layer
|
||||||
* - 职责描述1
|
|
||||||
* - 职责描述2
|
|
||||||
*
|
*
|
||||||
* 最近修改：
|
* 依赖服务：
|
||||||
* - YYYY-MM-DD: 修改类型 - 具体修改内容描述
|
* - LoginCoreService: 登录核心逻辑
|
||||||
* - YYYY-MM-DD: 修改类型 - 具体修改内容描述
|
* - EmailService: 邮件发送服务
|
||||||
*
|
*
|
||||||
* @author 作者名
|
* @author 作者名
|
||||||
* @version x.x.x
|
* @version 1.0.0
|
||||||
* @since 创建日期
|
* @since 2025-01-01
|
||||||
* @lastModified 最后修改日期
|
|
||||||
*/
|
*/
|
||||||
```
|
```
|
||||||
|
|
||||||
@@ -47,149 +222,75 @@
|
|||||||
|
|
||||||
```typescript
|
```typescript
|
||||||
/**
|
/**
|
||||||
* 类功能描述
|
* 登录业务服务
|
||||||
*
|
*
|
||||||
* 职责：
|
* 职责：
|
||||||
* - 主要职责1
|
* - 实现用户登录业务逻辑
|
||||||
* - 主要职责2
|
* - 协调核心服务完成登录流程
|
||||||
|
* - 处理登录相关的业务规则
|
||||||
*
|
*
|
||||||
* 主要方法：
|
* 主要方法：
|
||||||
* - method1() - 方法1功能
|
* - login() - 用户登录
|
||||||
* - method2() - 方法2功能
|
* - verificationCodeLogin() - 验证码登录
|
||||||
*
|
* - refreshToken() - 刷新令牌
|
||||||
* 使用场景：
|
|
||||||
* - 场景描述
|
|
||||||
*/
|
*/
|
||||||
@Injectable()
|
@Injectable()
|
||||||
export class ExampleService {
|
export class LoginService {
|
||||||
// 类实现
|
// 实现
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
### 方法注释（三级注释标准）
|
### 方法注释（三级标准）
|
||||||
|
|
||||||
**必须包含以下三个级别的注释：**
|
|
||||||
|
|
||||||
#### 1. 功能描述级别
|
|
||||||
```typescript
|
```typescript
|
||||||
/**
|
/**
|
||||||
* 用户登录验证
|
* 用户登录
|
||||||
*/
|
|
||||||
```
|
|
||||||
|
|
||||||
#### 2. 业务逻辑级别
|
|
||||||
```typescript
|
|
||||||
/**
|
|
||||||
* 用户登录验证
|
|
||||||
*
|
*
|
||||||
* 业务逻辑：
|
* 业务逻辑：
|
||||||
* 1. 验证用户名或邮箱格式
|
* 1. 调用核心服务验证用户凭证
|
||||||
* 2. 查找用户记录
|
* 2. 生成访问令牌和刷新令牌
|
||||||
* 3. 验证密码哈希值
|
* 3. 发送登录成功通知邮件
|
||||||
* 4. 检查用户状态是否允许登录
|
* 4. 记录登录日志
|
||||||
* 5. 记录登录日志
|
* 5. 返回登录结果
|
||||||
* 6. 返回认证结果
|
|
||||||
*/
|
|
||||||
```
|
|
||||||
|
|
||||||
#### 3. 技术实现级别
|
|
||||||
```typescript
|
|
||||||
/**
|
|
||||||
* 用户登录验证
|
|
||||||
*
|
*
|
||||||
* 业务逻辑：
|
* @param dto 登录请求数据
|
||||||
* 1. 验证用户名或邮箱格式
|
* @returns 登录结果，包含用户信息和令牌
|
||||||
* 2. 查找用户记录
|
* @throws UnauthorizedException 用户名或密码错误
|
||||||
* 3. 验证密码哈希值
|
* @throws ForbiddenException 用户状态不允许登录
|
||||||
* 4. 检查用户状态是否允许登录
|
|
||||||
* 5. 记录登录日志
|
|
||||||
* 6. 返回认证结果
|
|
||||||
*
|
|
||||||
* @param loginRequest 登录请求数据
|
|
||||||
* @returns 认证结果，包含用户信息和认证状态
|
|
||||||
* @throws UnauthorizedException 用户名或密码错误时
|
|
||||||
* @throws ForbiddenException 用户状态不允许登录时
|
|
||||||
*
|
*
|
||||||
* @example
|
* @example
|
||||||
* ```typescript
|
* ```typescript
|
||||||
* const result = await loginService.validateUser({
|
* const result = await loginService.login({
|
||||||
* identifier: 'user@example.com',
|
* identifier: 'user@example.com',
|
||||||
* password: 'password123'
|
* password: 'password123'
|
||||||
* });
|
* });
|
||||||
* ```
|
* ```
|
||||||
*/
|
*/
|
||||||
async validateUser(loginRequest: LoginRequest): Promise<AuthResult> {
|
async login(dto: LoginDto): Promise<ApiResponse<LoginResponse>> {
|
||||||
// 实现代码
|
// 实现
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
### 修改记录规范
|
### 修改记录规范
|
||||||
|
|
||||||
#### 修改类型定义
|
|
||||||
|
|
||||||
- **代码规范优化** - 命名规范、注释规范、代码清理等
|
|
||||||
- **功能新增** - 添加新的功能或方法
|
|
||||||
- **功能修改** - 修改现有功能的实现
|
|
||||||
- **Bug修复** - 修复代码缺陷
|
|
||||||
- **性能优化** - 提升代码性能
|
|
||||||
- **重构** - 代码结构调整但功能不变
|
|
||||||
|
|
||||||
#### 修改记录格式
|
|
||||||
|
|
||||||
```typescript
|
```typescript
|
||||||
/**
|
/**
|
||||||
* 最近修改：
|
* 最近修改：
|
||||||
* - 2025-01-07: 代码规范优化 - 清理未使用的导入(EmailSendResult, crypto)
|
* - 2025-01-15: 架构重构 - 迁移到四层架构，分离网关层和业务层
|
||||||
* - 2025-01-07: 代码规范优化 - 修复常量命名(saltRounds -> SALT_ROUNDS)
|
* - 2025-01-10: 功能新增 - 添加验证码登录功能
|
||||||
* - 2025-01-07: 功能新增 - 添加用户验证码登录功能
|
* - 2025-01-08: Bug修复 - 修复Token刷新逻辑错误
|
||||||
* - 2025-01-06: Bug修复 - 修复邮箱验证逻辑错误
|
* - 2025-01-05: 代码规范优化 - 统一异常处理格式
|
||||||
|
* - 2025-01-03: 性能优化 - 优化数据库查询性能
|
||||||
*
|
*
|
||||||
* @version 1.0.1 (修改后需要递增版本号)
|
* @version 2.0.0
|
||||||
* @lastModified 2025-01-07
|
* @lastModified 2025-01-15
|
||||||
*/
|
*/
|
||||||
```
|
```
|
||||||
|
|
||||||
#### 修改记录长度限制
|
**修改记录原则：**
|
||||||
|
- 只保留最近5次修改
|
||||||
**重要：为保持文件头注释简洁，修改记录只保留最近的5次修改。**
|
- 包含日期、类型、描述
|
||||||
|
- 重大版本更新标注版本号
|
||||||
- ✅ **保留最新5条记录** - 便于快速了解最近变更
|
|
||||||
- ✅ **超出时删除最旧记录** - 保持注释简洁
|
|
||||||
- ✅ **重要修改可标注** - 重大版本更新可特别标注
|
|
||||||
|
|
||||||
```typescript
|
|
||||||
// ✅ 正确示例：保持最新5条记录
|
|
||||||
/**
|
|
||||||
* 最近修改：
|
|
||||||
* - 2025-01-07: 功能新增 - 添加用户头像上传功能
|
|
||||||
* - 2025-01-06: Bug修复 - 修复邮箱验证逻辑错误
|
|
||||||
* - 2025-01-05: 代码规范优化 - 统一异常处理格式
|
|
||||||
* - 2025-01-04: 功能修改 - 优化用户状态管理逻辑
|
|
||||||
* - 2025-01-03: 性能优化 - 优化数据库查询性能
|
|
||||||
*
|
|
||||||
* @version 1.3.0
|
|
||||||
*/
|
|
||||||
|
|
||||||
// ❌ 错误示例：记录过多，注释冗长
|
|
||||||
/**
|
|
||||||
* 最近修改：
|
|
||||||
* - 2025-01-07: 功能新增 - 添加用户头像上传功能
|
|
||||||
* - 2025-01-06: Bug修复 - 修复邮箱验证逻辑错误
|
|
||||||
* - 2025-01-05: 代码规范优化 - 统一异常处理格式
|
|
||||||
* - 2025-01-04: 功能修改 - 优化用户状态管理逻辑
|
|
||||||
* - 2025-01-03: 性能优化 - 优化数据库查询性能
|
|
||||||
* - 2025-01-02: 重构 - 重构用户认证逻辑
|
|
||||||
* - 2025-01-01: 功能新增 - 添加用户权限管理
|
|
||||||
* - 2024-12-31: Bug修复 - 修复登录超时问题
|
|
||||||
* // ... 更多记录导致注释过长
|
|
||||||
*/
|
|
||||||
```
|
|
||||||
|
|
||||||
#### 版本号递增规则
|
|
||||||
|
|
||||||
- **代码规范优化、Bug修复** → 修订版本 +1 (1.0.0 → 1.0.1)
|
|
||||||
- **功能新增、功能修改** → 次版本 +1 (1.0.1 → 1.1.0)
|
|
||||||
- **重构、架构变更** → 主版本 +1 (1.1.0 → 2.0.0)
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
@@ -199,22 +300,37 @@ async validateUser(loginRequest: LoginRequest): Promise<AuthResult> {
|
|||||||
|
|
||||||
```typescript
|
```typescript
|
||||||
// ERROR - 系统错误，需要立即处理
|
// ERROR - 系统错误，需要立即处理
|
||||||
this.logger.error('用户登录失败', { userId, error: error.message });
|
this.logger.error('用户登录失败', {
|
||||||
|
userId,
|
||||||
|
error: error.message,
|
||||||
|
stack: error.stack
|
||||||
|
});
|
||||||
|
|
||||||
// WARN - 警告信息，需要关注但不影响系统运行
|
// WARN - 警告信息，需要关注
|
||||||
this.logger.warn('用户多次登录失败', { userId, attemptCount });
|
this.logger.warn('用户多次登录失败', {
|
||||||
|
userId,
|
||||||
|
attemptCount,
|
||||||
|
ip: request.ip
|
||||||
|
});
|
||||||
|
|
||||||
// INFO - 重要的业务操作记录
|
// INFO - 重要的业务操作
|
||||||
this.logger.info('用户登录成功', { userId, loginTime: new Date() });
|
this.logger.info('用户登录成功', {
|
||||||
|
userId,
|
||||||
|
loginTime: new Date(),
|
||||||
|
ip: request.ip
|
||||||
|
});
|
||||||
|
|
||||||
// DEBUG - 调试信息，仅在开发环境使用
|
// DEBUG - 调试信息（仅开发环境）
|
||||||
this.logger.debug('验证用户密码', { userId, hashedPassword: '***' });
|
this.logger.debug('验证用户密码', {
|
||||||
|
userId,
|
||||||
|
passwordHash: '***'
|
||||||
|
});
|
||||||
```
|
```
|
||||||
|
|
||||||
### 日志格式规范
|
### 日志格式规范
|
||||||
|
|
||||||
```typescript
|
```typescript
|
||||||
// ✅ 正确格式
|
// ✅ 正确：结构化日志
|
||||||
this.logger.info('操作描述', {
|
this.logger.info('操作描述', {
|
||||||
userId: 'user123',
|
userId: 'user123',
|
||||||
action: 'login',
|
action: 'login',
|
||||||
@@ -222,68 +338,26 @@ this.logger.info('操作描述', {
|
|||||||
metadata: { ip: '192.168.1.1' }
|
metadata: { ip: '192.168.1.1' }
|
||||||
});
|
});
|
||||||
|
|
||||||
// ❌ 错误格式
|
// ❌ 错误：字符串拼接
|
||||||
this.logger.info('用户登录');
|
|
||||||
this.logger.info(`用户${userId}登录成功`);
|
this.logger.info(`用户${userId}登录成功`);
|
||||||
```
|
```
|
||||||
|
|
||||||
---
|
### 敏感信息处理
|
||||||
|
|
||||||
## 🏗️ 业务逻辑规范
|
|
||||||
|
|
||||||
### 防御性编程
|
|
||||||
|
|
||||||
```typescript
|
```typescript
|
||||||
async getUserById(userId: string): Promise<User> {
|
// ✅ 正确：隐藏敏感信息
|
||||||
// 1. 参数验证
|
this.logger.info('用户注册', {
|
||||||
if (!userId) {
|
email: user.email,
|
||||||
throw new BadRequestException('用户ID不能为空');
|
password: '***', // 密码不记录
|
||||||
}
|
apiKey: '***' // API密钥不记录
|
||||||
|
});
|
||||||
|
|
||||||
// 2. 业务逻辑验证
|
// ❌ 错误：暴露敏感信息
|
||||||
const user = await this.usersService.findOne(userId);
|
this.logger.info('用户注册', {
|
||||||
if (!user) {
|
email: user.email,
|
||||||
throw new NotFoundException('用户不存在');
|
password: user.password, // 危险！
|
||||||
}
|
apiKey: user.apiKey // 危险！
|
||||||
|
});
|
||||||
// 3. 状态检查
|
|
||||||
if (user.status === UserStatus.DELETED) {
|
|
||||||
throw new ForbiddenException('用户已被删除');
|
|
||||||
}
|
|
||||||
|
|
||||||
// 4. 返回结果
|
|
||||||
return user;
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### 业务逻辑分层
|
|
||||||
|
|
||||||
```typescript
|
|
||||||
// Controller 层 - 只处理HTTP请求和响应
|
|
||||||
@Controller('users')
|
|
||||||
export class UsersController {
|
|
||||||
@Get(':id')
|
|
||||||
async getUser(@Param('id') id: string) {
|
|
||||||
return this.usersService.getUserById(id);
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
// Service 层 - 处理业务逻辑
|
|
||||||
@Injectable()
|
|
||||||
export class UsersService {
|
|
||||||
async getUserById(id: string): Promise<User> {
|
|
||||||
// 业务逻辑实现
|
|
||||||
return this.usersCoreService.findUserById(id);
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
// Core 层 - 核心业务实现
|
|
||||||
@Injectable()
|
|
||||||
export class UsersCoreService {
|
|
||||||
async findUserById(id: string): Promise<User> {
|
|
||||||
// 核心逻辑实现
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
```
|
||||||
|
|
||||||
---
|
---
|
||||||
@@ -312,38 +386,66 @@ throw new ConflictException('用户名已存在');
|
|||||||
throw new InternalServerErrorException('系统内部错误');
|
throw new InternalServerErrorException('系统内部错误');
|
||||||
```
|
```
|
||||||
|
|
||||||
### 异常处理模式
|
### 分层异常处理
|
||||||
|
|
||||||
```typescript
|
```typescript
|
||||||
async createUser(userData: CreateUserDto): Promise<User> {
|
// Gateway Layer - 转换为HTTP响应
|
||||||
try {
|
@Controller('auth')
|
||||||
// 1. 参数验证
|
export class LoginController {
|
||||||
this.validateUserData(userData);
|
@Post('login')
|
||||||
|
async login(@Body() dto: LoginDto, @Res() res: Response) {
|
||||||
|
const result = await this.loginService.login(dto);
|
||||||
|
|
||||||
// 2. 业务逻辑检查
|
if (result.success) {
|
||||||
await this.checkUserExists(userData.email);
|
res.status(HttpStatus.OK).json(result);
|
||||||
|
} else {
|
||||||
|
const statusCode = this.getErrorStatusCode(result);
|
||||||
|
res.status(statusCode).json(result);
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
// 3. 执行创建操作
|
// Business Layer - 返回业务响应
|
||||||
const user = await this.usersRepository.create(userData);
|
@Injectable()
|
||||||
|
export class LoginService {
|
||||||
|
async login(dto: LoginDto): Promise<ApiResponse<LoginResponse>> {
|
||||||
|
try {
|
||||||
|
const user = await this.loginCoreService.validateUser(dto);
|
||||||
|
const tokens = await this.loginCoreService.generateTokens(user);
|
||||||
|
|
||||||
// 4. 记录成功日志
|
return {
|
||||||
this.logger.info('用户创建成功', { userId: user.id });
|
success: true,
|
||||||
|
data: tokens,
|
||||||
|
message: '登录成功'
|
||||||
|
};
|
||||||
|
} catch (error) {
|
||||||
|
this.logger.error('登录失败', { dto, error: error.message });
|
||||||
|
|
||||||
return user;
|
return {
|
||||||
} catch (error) {
|
success: false,
|
||||||
// 5. 记录错误日志
|
message: error.message,
|
||||||
this.logger.error('用户创建失败', {
|
error_code: 'LOGIN_FAILED'
|
||||||
userData: { ...userData, password: '***' },
|
};
|
||||||
error: error.message
|
}
|
||||||
});
|
}
|
||||||
|
}
|
||||||
|
|
||||||
// 6. 重新抛出业务异常
|
// Core Layer - 抛出技术异常
|
||||||
if (error instanceof BadRequestException) {
|
@Injectable()
|
||||||
throw error;
|
export class LoginCoreService {
|
||||||
|
async validateUser(dto: LoginDto): Promise<User> {
|
||||||
|
const user = await this.usersService.findByEmail(dto.email);
|
||||||
|
|
||||||
|
if (!user) {
|
||||||
|
throw new UnauthorizedException('用户不存在');
|
||||||
}
|
}
|
||||||
|
|
||||||
// 7. 转换为系统异常
|
const isValid = await bcrypt.compare(dto.password, user.password);
|
||||||
throw new InternalServerErrorException('用户创建失败');
|
if (!isValid) {
|
||||||
|
throw new UnauthorizedException('密码错误');
|
||||||
|
}
|
||||||
|
|
||||||
|
return user;
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
@@ -354,152 +456,233 @@ async createUser(userData: CreateUserDto): Promise<User> {
|
|||||||
|
|
||||||
### 代码检查清单
|
### 代码检查清单
|
||||||
|
|
||||||
在提交代码前，请确保：
|
提交代码前确保：
|
||||||
|
|
||||||
|
- [ ] **架构规范**
|
||||||
|
- [ ] 代码放在正确的架构层
|
||||||
|
- [ ] 没有跨层直接调用（如Gateway直接调用Core）
|
||||||
|
- [ ] 依赖方向正确（上层依赖下层）
|
||||||
|
- [ ] 模块职责单一明确
|
||||||
|
|
||||||
- [ ] **注释完整性**
|
- [ ] **注释完整性**
|
||||||
- [ ] 文件头注释包含功能描述、修改记录、作者信息
|
- [ ] 文件头注释包含架构层级说明
|
||||||
- [ ] 类注释包含职责、主要方法、使用场景
|
- [ ] 类注释说明职责和主要方法
|
||||||
- [ ] 方法注释包含三级注释（功能、业务逻辑、技术实现）
|
- [ ] 方法注释包含业务逻辑和技术实现
|
||||||
- [ ] 修改现有文件时添加了修改记录和更新版本号
|
- [ ] 修改记录保持最近5次
|
||||||
- [ ] 修改记录只保留最近5次，保持注释简洁
|
|
||||||
|
|
||||||
- [ ] **业务逻辑完整性**
|
|
||||||
- [ ] 所有参数都进行了验证
|
|
||||||
- [ ] 所有异常情况都进行了处理
|
|
||||||
- [ ] 关键操作都记录了日志
|
|
||||||
- [ ] 业务逻辑考虑了所有边界情况
|
|
||||||
|
|
||||||
- [ ] **代码质量**
|
- [ ] **代码质量**
|
||||||
- [ ] 没有未使用的导入和变量
|
- [ ] 没有未使用的导入和变量
|
||||||
- [ ] 常量使用了正确的命名规范
|
- [ ] 常量使用正确命名（UPPER_SNAKE_CASE）
|
||||||
- [ ] 方法长度合理（建议不超过50行）
|
- [ ] 方法长度合理（不超过50行）
|
||||||
- [ ] 单一职责原则，每个方法只做一件事
|
- [ ] 单一职责原则
|
||||||
|
|
||||||
- [ ] **安全性**
|
- [ ] **日志规范**
|
||||||
- [ ] 敏感信息不在日志中暴露
|
- [ ] 关键操作记录日志
|
||||||
- [ ] 用户输入都进行了验证和清理
|
- [ ] 使用结构化日志格式
|
||||||
- [ ] 权限检查在适当的位置进行
|
- [ ] 敏感信息已隐藏
|
||||||
|
- [ ] 日志级别使用正确
|
||||||
|
|
||||||
|
- [ ] **异常处理**
|
||||||
|
- [ ] 所有异常情况都处理
|
||||||
|
- [ ] 异常类型使用正确
|
||||||
|
- [ ] 错误信息清晰明确
|
||||||
|
- [ ] 记录了错误日志
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 💡 最佳实践
|
## 💡 最佳实践
|
||||||
|
|
||||||
### 1. 注释驱动开发
|
### 1. 遵循四层架构
|
||||||
|
|
||||||
```typescript
|
```typescript
|
||||||
/**
|
// ✅ 正确：清晰的层次调用
|
||||||
* 用户注册功能
|
// Gateway → Business → Core → Data
|
||||||
*
|
|
||||||
* 业务逻辑：
|
// Gateway Layer
|
||||||
* 1. 验证邮箱格式和唯一性
|
@Controller('users')
|
||||||
* 2. 验证密码强度
|
export class UsersController {
|
||||||
* 3. 生成邮箱验证码
|
constructor(private readonly usersService: UsersService) {}
|
||||||
* 4. 创建用户记录
|
|
||||||
* 5. 发送验证邮件
|
@Get(':id')
|
||||||
* 6. 返回注册结果
|
async getUser(@Param('id') id: string) {
|
||||||
*
|
return this.usersService.getUserById(id);
|
||||||
* @param registerData 注册数据
|
}
|
||||||
* @returns 注册结果
|
}
|
||||||
*/
|
|
||||||
async registerUser(registerData: RegisterDto): Promise<RegisterResult> {
|
// Business Layer
|
||||||
// 先写注释，再写实现
|
@Injectable()
|
||||||
// 这样确保逻辑清晰，不遗漏步骤
|
export class UsersService {
|
||||||
|
constructor(private readonly usersCoreService: UsersCoreService) {}
|
||||||
|
|
||||||
|
async getUserById(id: string): Promise<ApiResponse<User>> {
|
||||||
|
try {
|
||||||
|
const user = await this.usersCoreService.findUserById(id);
|
||||||
|
return { success: true, data: user };
|
||||||
|
} catch (error) {
|
||||||
|
return { success: false, message: error.message };
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
// Core Layer
|
||||||
|
@Injectable()
|
||||||
|
export class UsersCoreService {
|
||||||
|
constructor(
|
||||||
|
@Inject('IUsersService')
|
||||||
|
private readonly usersDataService: IUsersService
|
||||||
|
) {}
|
||||||
|
|
||||||
|
async findUserById(id: string): Promise<User> {
|
||||||
|
const user = await this.usersDataService.findOne(id);
|
||||||
|
if (!user) {
|
||||||
|
throw new NotFoundException('用户不存在');
|
||||||
|
}
|
||||||
|
return user;
|
||||||
|
}
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
### 2. 错误优先处理
|
### 2. 使用依赖注入接口
|
||||||
|
|
||||||
```typescript
|
```typescript
|
||||||
async processPayment(paymentData: PaymentDto): Promise<PaymentResult> {
|
// ✅ 正确：使用接口依赖注入
|
||||||
// 1. 先处理所有可能的错误情况
|
@Injectable()
|
||||||
if (!paymentData.amount || paymentData.amount <= 0) {
|
export class LoginCoreService {
|
||||||
throw new BadRequestException('支付金额必须大于0');
|
constructor(
|
||||||
}
|
@Inject('IUsersService')
|
||||||
|
private readonly usersService: IUsersService,
|
||||||
|
@Inject('IRedisService')
|
||||||
|
private readonly redisService: IRedisService,
|
||||||
|
) {}
|
||||||
|
}
|
||||||
|
|
||||||
if (!paymentData.userId) {
|
// ❌ 错误：直接依赖具体实现
|
||||||
throw new BadRequestException('用户ID不能为空');
|
@Injectable()
|
||||||
}
|
export class LoginCoreService {
|
||||||
|
constructor(
|
||||||
const user = await this.usersService.findOne(paymentData.userId);
|
private readonly usersService: UsersService,
|
||||||
if (!user) {
|
private readonly redisService: RealRedisService,
|
||||||
throw new NotFoundException('用户不存在');
|
) {}
|
||||||
}
|
|
||||||
|
|
||||||
// 2. 再处理正常的业务逻辑
|
|
||||||
return this.executePayment(paymentData);
|
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
### 3. 日志驱动调试
|
### 3. 统一响应格式
|
||||||
|
|
||||||
```typescript
|
```typescript
|
||||||
async complexBusinessLogic(data: ComplexData): Promise<Result> {
|
// 定义统一的响应接口
|
||||||
this.logger.debug('开始执行复杂业务逻辑', { data });
|
export interface ApiResponse<T = any> {
|
||||||
|
success: boolean;
|
||||||
|
data?: T;
|
||||||
|
message: string;
|
||||||
|
error_code?: string;
|
||||||
|
}
|
||||||
|
|
||||||
|
// Business Layer 返回统一格式
|
||||||
|
async login(dto: LoginDto): Promise<ApiResponse<LoginResponse>> {
|
||||||
try {
|
try {
|
||||||
// 步骤1
|
const result = await this.loginCoreService.validateUser(dto);
|
||||||
const step1Result = await this.step1(data);
|
return {
|
||||||
this.logger.debug('步骤1完成', { step1Result });
|
success: true,
|
||||||
|
data: result,
|
||||||
// 步骤2
|
message: '登录成功'
|
||||||
const step2Result = await this.step2(step1Result);
|
};
|
||||||
this.logger.debug('步骤2完成', { step2Result });
|
|
||||||
|
|
||||||
// 步骤3
|
|
||||||
const finalResult = await this.step3(step2Result);
|
|
||||||
this.logger.info('复杂业务逻辑执行成功', { finalResult });
|
|
||||||
|
|
||||||
return finalResult;
|
|
||||||
} catch (error) {
|
} catch (error) {
|
||||||
this.logger.error('复杂业务逻辑执行失败', { data, error: error.message });
|
return {
|
||||||
throw error;
|
success: false,
|
||||||
|
message: error.message,
|
||||||
|
error_code: 'LOGIN_FAILED'
|
||||||
|
};
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
### 4. 版本管理最佳实践
|
### 4. 防御性编程
|
||||||
|
|
||||||
```typescript
|
```typescript
|
||||||
/**
|
async processPayment(dto: PaymentDto): Promise<ApiResponse<PaymentResult>> {
|
||||||
* 用户服务
|
// 1. 参数验证
|
||||||
*
|
if (!dto.amount || dto.amount <= 0) {
|
||||||
* 最近修改：
|
return {
|
||||||
* - 2025-01-07: 功能新增 - 添加用户头像上传功能 (v1.2.0)
|
success: false,
|
||||||
* - 2025-01-06: Bug修复 - 修复邮箱验证逻辑错误 (v1.1.1)
|
message: '支付金额必须大于0',
|
||||||
* - 2025-01-05: 代码规范优化 - 统一异常处理格式 (v1.1.0)
|
error_code: 'INVALID_AMOUNT'
|
||||||
* - 2025-01-04: 功能新增 - 添加用户状态管理 (v1.1.0)
|
};
|
||||||
* - 2025-01-03: 重构 - 重构用户认证逻辑 (v2.0.0)
|
}
|
||||||
*
|
|
||||||
* @version 1.2.0
|
// 2. 业务规则验证
|
||||||
* @lastModified 2025-01-07
|
const user = await this.usersService.findOne(dto.userId);
|
||||||
*/
|
if (!user) {
|
||||||
|
return {
|
||||||
|
success: false,
|
||||||
|
message: '用户不存在',
|
||||||
|
error_code: 'USER_NOT_FOUND'
|
||||||
|
};
|
||||||
|
}
|
||||||
|
|
||||||
|
// 3. 状态检查
|
||||||
|
if (user.status !== UserStatus.ACTIVE) {
|
||||||
|
return {
|
||||||
|
success: false,
|
||||||
|
message: '用户状态不允许支付',
|
||||||
|
error_code: 'USER_INACTIVE'
|
||||||
|
};
|
||||||
|
}
|
||||||
|
|
||||||
|
// 4. 执行业务逻辑
|
||||||
|
return this.executePayment(dto);
|
||||||
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
**修改记录管理原则：**
|
### 5. 测试驱动开发
|
||||||
- ✅ **保持简洁** - 只保留最近5次修改
|
|
||||||
- ✅ **定期清理** - 超出5条时删除最旧记录
|
```typescript
|
||||||
- ✅ **重要标注** - 重大版本更新可特别标注版本号
|
// 先写测试
|
||||||
- ✅ **描述清晰** - 每条记录都要说明具体改动内容
|
describe('LoginService', () => {
|
||||||
|
it('should login successfully with valid credentials', async () => {
|
||||||
|
const dto = { identifier: 'test@example.com', password: 'password123' };
|
||||||
|
const result = await loginService.login(dto);
|
||||||
|
|
||||||
|
expect(result.success).toBe(true);
|
||||||
|
expect(result.data).toHaveProperty('accessToken');
|
||||||
|
});
|
||||||
|
|
||||||
|
it('should return error with invalid credentials', async () => {
|
||||||
|
const dto = { identifier: 'test@example.com', password: 'wrong' };
|
||||||
|
const result = await loginService.login(dto);
|
||||||
|
|
||||||
|
expect(result.success).toBe(false);
|
||||||
|
expect(result.error_code).toBe('LOGIN_FAILED');
|
||||||
|
});
|
||||||
|
});
|
||||||
|
|
||||||
|
// 再写实现
|
||||||
|
@Injectable()
|
||||||
|
export class LoginService {
|
||||||
|
async login(dto: LoginDto): Promise<ApiResponse<LoginResponse>> {
|
||||||
|
// 实现逻辑
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 🎯 总结
|
## 🎯 总结
|
||||||
|
|
||||||
遵循后端开发规范能够：
|
遵循开发规范能够：
|
||||||
|
|
||||||
1. **提高代码质量** - 通过完整的注释和规范的实现
|
1. **清晰的架构** - 四层架构确保职责分离
|
||||||
2. **提升团队效率** - 统一的规范减少沟通成本
|
2. **高质量代码** - 完整的注释和规范的实现
|
||||||
3. **降低维护成本** - 清晰的文档和日志便于问题定位
|
3. **易于维护** - 清晰的文档和日志便于问题定位
|
||||||
4. **增强系统稳定性** - 完善的异常处理和防御性编程
|
4. **团队协作** - 统一的规范减少沟通成本
|
||||||
5. **促进知识传承** - 详细的修改记录和版本管理
|
5. **系统稳定** - 完善的异常处理和防御性编程
|
||||||
|
|
||||||
**记住：好的代码不仅要能运行，更要能被理解、维护和扩展。**
|
**记住：好的代码不仅要能运行，更要符合架构设计、易于理解、便于维护和扩展。**
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 📚 相关文档
|
## 📚 相关文档
|
||||||
|
|
||||||
- [命名规范](./naming_convention.md) - 代码命名规范
|
- [架构设计文档](../ARCHITECTURE.md) - 四层架构详解
|
||||||
- [NestJS 使用指南](./nestjs_guide.md) - 框架最佳实践
|
- [架构重构文档](../ARCHITECTURE_REFACTORING.md) - 架构迁移指南
|
||||||
- [Git 提交规范](./git_commit_guide.md) - 版本控制规范
|
- [Git提交规范](./git_commit_guide.md) - 版本控制规范
|
||||||
- [AI 辅助开发规范](./AI辅助开发规范指南.md) - AI 辅助开发指南
|
- [测试指南](./TESTING.md) - 测试规范和最佳实践
|
||||||
|
|||||||
Reference in New Issue
Block a user