diff --git a/README.md b/README.md index 393f41f..3a7412d 100644 --- a/README.md +++ b/README.md @@ -4,28 +4,38 @@ ## 技术栈 -- **NestJS** `^10.0.0` - 渐进式 Node.js 框架 -- **TypeScript** `^5.3.0` - 类型安全 +- **NestJS** `^10.4.20` - 渐进式 Node.js 框架 +- **TypeScript** `^5.9.3` - 类型安全 - **Socket.IO** - WebSocket 实时通信支持 -- **RxJS** `^7.8.1` - 响应式编程库 +- **RxJS** `^7.8.2` - 响应式编程库 +- **Pino** `^10.1.0` - 高性能日志库 +- **Jest** `^29.7.0` - 测试框架 ### 核心依赖 **生产环境:** -- `@nestjs/common` `^10.0.0` - NestJS 核心功能 -- `@nestjs/core` `^10.0.0` - NestJS 核心模块 -- `@nestjs/platform-express` `^10.0.0` - Express 平台适配器 -- `@nestjs/websockets` `^10.0.0` - WebSocket 支持 -- `@nestjs/platform-socket.io` `^10.0.0` - Socket.IO 适配器 -- `reflect-metadata` `^0.1.13` - 装饰器元数据支持 -- `rxjs` `^7.8.1` - 响应式编程 +- `@nestjs/common` `^10.4.20` - NestJS 核心功能 +- `@nestjs/core` `^10.4.20` - NestJS 核心模块 +- `@nestjs/config` `^4.0.2` - 配置管理 +- `@nestjs/platform-express` `^10.4.20` - Express 平台适配器 +- `@nestjs/websockets` `^10.4.20` - WebSocket 支持 +- `@nestjs/platform-socket.io` `^10.4.20` - Socket.IO 适配器 +- `nestjs-pino` `^4.5.0` - Pino 日志集成 +- `pino` `^10.1.0` - 高性能日志库 +- `reflect-metadata` `^0.1.14` - 装饰器元数据支持 +- `rxjs` `^7.8.2` - 响应式编程 **开发环境:** -- `@nestjs/cli` `^10.0.0` - NestJS 命令行工具 -- `@nestjs/schematics` `^10.0.0` - NestJS 代码生成器 -- `@types/node` `^20.0.0` - Node.js 类型定义 -- `ts-node` `^10.9.0` - TypeScript 运行时 -- `typescript` `^5.3.0` - TypeScript 编译器 +- `@nestjs/cli` `^10.4.9` - NestJS 命令行工具 +- `@nestjs/schematics` `^10.2.3` - NestJS 代码生成器 +- `@nestjs/testing` `^10.4.20` - 测试工具 +- `@types/jest` `^29.5.14` - Jest 类型定义 +- `@types/node` `^20.19.26` - Node.js 类型定义 +- `jest` `^29.7.0` - 测试框架 +- `ts-jest` `^29.2.5` - TypeScript Jest 支持 +- `ts-node` `^10.9.2` - TypeScript 运行时 +- `typescript` `^5.9.3` - TypeScript 编译器 +- `pino-pretty` `^13.1.3` - Pino 美化输出 ## 开发规范 @@ -82,11 +92,50 @@ git commit -m "api:添加玩家信息查询接口" 详细规范请查看:[Git 提交规范文档](./docs/git_commit_guide.md) +### 后端开发规范 + +项目要求严格的代码质量和可维护性标准: + +**核心要求:** + +- **完整注释**:每个模块、类、方法都必须有详细注释 +- **全面业务逻辑**:考虑所有可能情况,包括异常和边界条件 +- **关键日志记录**:重要操作必须记录日志,便于问题排查 +- **防御性编程**:对所有输入进行验证,实现健壮的错误处理 + +**注释要求:** + +```typescript +/** + * 玩家服务类 + * + * 职责:处理玩家相关的业务逻辑 + * 主要方法:createPlayer(), updatePlayerInfo(), getPlayerById() + * 使用场景:玩家注册登录流程、个人陈列室数据管理 + */ +@Injectable() +export class PlayerService { + /** + * 创建新玩家 + * @param email 玩家邮箱地址 + * @param nickname 玩家昵称 + * @returns Promise 创建成功的玩家对象 + * @throws BadRequestException 当邮箱格式错误时 + */ + async createPlayer(email: string, nickname: string): Promise { + // 详细的业务逻辑实现... + } +} +``` + +详细规范请查看:[后端开发规范指南](./docs/backend_development_guide.md) + ## 文档 - [NestJS 使用指南](./docs/nestjs_guide.md) - 详细的 NestJS 开发指南,包含实战案例 - [命名规范](./docs/naming_convention.md) - 项目命名规范和最佳实践 - [Git 提交规范](./docs/git_commit_guide.md) - Git 提交信息格式和最佳实践 +- [后端开发规范](./docs/backend_development_guide.md) - 注释标准、业务逻辑设计和日志记录要求 ## 前置要求 @@ -112,23 +161,6 @@ pnpm --version pnpm install ``` -**注意**:首次安装时,pnpm 可能会提示需要批准构建脚本。这是 pnpm 的安全特性,用于防止恶意脚本执行。 - -如果看到以下警告: - -``` -Warning: Ignored build scripts: @nestjs/core. -Run "pnpm approve-builds" to pick which dependencies should be allowed to run scripts. -``` - -请运行以下命令批准 NestJS 的构建脚本: - -```bash -pnpm approve-builds -``` - -然后选择批准 `@nestjs/core` 和其他 NestJS 相关包的构建脚本。 - ## 开发 启动开发服务器(支持热重载): @@ -139,6 +171,26 @@ pnpm dev 服务器将运行在 `http://localhost:3000` +## 测试 + +运行测试: + +```bash +pnpm test +``` + +运行测试并监听文件变化: + +```bash +pnpm test:watch +``` + +运行测试并生成覆盖率报告: + +```bash +pnpm test:cov +``` + ## 构建 ```bash @@ -156,11 +208,11 @@ pnpm start:prod ``` src/ ├── api/ # API 接口层(控制器、网关) -├── config/ # 配置文件 -├── data/ # 数据访问层(数据库、缓存) -├── model/ # 数据模型、实体、DTO -├── service/ # 业务逻辑层 -├── utils/ # 工具函数 +├── business/ # 业务逻辑层 +├── core/ # 核心功能模块 +│ ├── db/ # 数据库相关 +│ └── utils/ # 工具函数 +│ └── logger/ # 日志系统 ├── main.ts # 应用入口 ├── app.module.ts # 根模块 ├── app.controller.ts # 根控制器 @@ -168,8 +220,67 @@ src/ test/ ├── api/ # API 测试 └── service/ # 服务测试 +docs/ # 项目文档 +├── backend_development_guide.md # 后端开发规范 +├── git_commit_guide.md # Git 提交规范 +├── naming_convention.md # 命名规范 +└── nestjs_guide.md # NestJS 使用指南 ``` +## 核心功能 + +### 日志系统 + +项目集成了完整的日志系统,基于 Pino 高性能日志库: + +**特性:** +- 🚀 高性能日志记录 +- 🔒 自动敏感信息过滤 +- 🎯 多级别日志控制 +- 🔍 请求上下文绑定 +- 📊 结构化日志输出 + +**使用示例:** + +```typescript +import { AppLoggerService } from './core/utils/logger/logger.service'; + +@Injectable() +export class UserService { + constructor(private readonly logger: AppLoggerService) {} + + async createUser(userData: CreateUserDto) { + this.logger.info('开始创建用户', { + operation: 'createUser', + email: userData.email, + timestamp: new Date().toISOString() + }); + + try { + const user = await this.userRepository.save(userData); + + this.logger.info('用户创建成功', { + operation: 'createUser', + userId: user.id, + email: userData.email + }); + + return user; + } catch (error) { + this.logger.error('用户创建失败', { + operation: 'createUser', + email: userData.email, + error: error.message + }, error.stack); + + throw error; + } + } +} +``` + +详细使用方法请参考:[后端开发规范指南 - 日志系统使用指南](./docs/backend_development_guide.md#四日志系统使用指南) + ## 下一步 - 在 `src/api/` 目录下创建游戏相关的控制器和网关