forked from datawhale/whale-town-end
305 lines
8.4 KiB
Markdown
305 lines
8.4 KiB
Markdown
# Pixel Game Server
|
||
|
||
一个基于 NestJS 的 2D 像素风游戏后端服务
|
||
|
||
---
|
||
|
||
## 🚨 开发者必读警告
|
||
|
||
**⚠️ 在开始任何开发工作之前，请务必阅读：[AI 辅助开发规范指南](./docs/AI辅助开发规范指南.md)**
|
||
|
||
**📢 重要提醒：**
|
||
- 🚫 **未阅读 AI 辅助指南的代码将无法通过审查**
|
||
- 🤖 **学会使用 AI 助手可以让你的开发效率提升 300%**
|
||
- 📝 **AI 可以帮你自动生成符合规范的代码和注释**
|
||
- 🔍 **AI 可以实时检查你的代码质量**
|
||
|
||
**👉 [立即阅读 AI 辅助开发指南](./docs/AI辅助开发规范指南.md)**
|
||
|
||
---
|
||
|
||
## 技术栈
|
||
|
||
- **NestJS** `^10.4.20` - 渐进式 Node.js 框架
|
||
- **TypeScript** `^5.9.3` - 类型安全
|
||
- **Socket.IO** - WebSocket 实时通信支持
|
||
- **RxJS** `^7.8.2` - 响应式编程库
|
||
- **Pino** `^10.1.0` - 高性能日志库
|
||
- **Jest** `^29.7.0` - 测试框架
|
||
|
||
### 核心依赖
|
||
|
||
**生产环境：**
|
||
- `@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.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 美化输出
|
||
|
||
## 🚨 重要：开发前必读
|
||
|
||
### ⚠️ 所有开发者必须先阅读 AI 辅助开发指南
|
||
|
||
**在开始任何开发工作之前，请务必阅读：[AI 辅助开发规范指南](./docs/AI辅助开发规范指南.md)**
|
||
|
||
这个指南将教你如何：
|
||
- 🤖 使用 AI 助手遵循项目规范
|
||
- 📝 自动生成规范的代码和注释
|
||
- 🔍 实时检查代码质量
|
||
- 🚀 显著提高开发效率和代码质量
|
||
|
||
**不阅读此指南直接开发，代码审查将无法通过！**
|
||
|
||
---
|
||
|
||
## 开发规范
|
||
|
||
### 命名规范
|
||
|
||
项目采用统一的命名规范，确保代码风格一致：
|
||
|
||
- **文件/文件夹**：下划线分隔（如 `order_controller.ts`）
|
||
- **变量/函数**：小驼峰命名（如 `userName`、`async queryUserInfo()`）
|
||
- **类/构造函数**：大驼峰命名（如 `UserModel`、`OrderService`）
|
||
- **常量**：全大写 + 下划线（如 `PORT`、`DB_HOST`）
|
||
- **接口路由**：全小写 + 短横线（如 `/user/get-info`、`/order/create-order`）
|
||
|
||
详细规范请查看：[命名规范文档](./docs/naming_convention.md)
|
||
|
||
### Git 提交规范
|
||
|
||
项目采用约定式提交规范，提交信息格式：`<类型>：<简短描述>`
|
||
|
||
**常用提交类型：**
|
||
|
||
- `feat` - 新增功能
|
||
- `fix` - 修复 Bug
|
||
- `docs` - 文档更新
|
||
- `style` - 代码格式调整
|
||
- `refactor` - 代码重构
|
||
- `perf` - 性能优化
|
||
- `test` - 测试相关
|
||
- `chore` - 构建/工具变动
|
||
|
||
**后端特定类型：**
|
||
|
||
- `api` - API 接口
|
||
- `db` - 数据库
|
||
- `websocket` - WebSocket
|
||
- `auth` - 认证授权
|
||
- `dto` - 数据传输对象
|
||
- `service` - 服务层
|
||
|
||
**核心原则：**
|
||
|
||
- ⭐ 一次提交只做一件事
|
||
- 使用中文冒号 `：`
|
||
- 简短明确（不超过 50 字符）
|
||
- 能拆分就拆分，保持提交历史清晰
|
||
|
||
**示例：**
|
||
|
||
```bash
|
||
git commit -m "feat：实现玩家注册和登录功能"
|
||
git commit -m "fix：修复房间加入时的并发问题"
|
||
git commit -m "api：添加玩家信息查询接口"
|
||
```
|
||
|
||
详细规范请查看：[Git 提交规范文档](./docs/git_commit_guide.md)
|
||
|
||
### 后端开发规范
|
||
|
||
项目要求严格的代码质量和可维护性标准：
|
||
|
||
**核心要求：**
|
||
|
||
- **完整注释**：每个模块、类、方法都必须有详细注释
|
||
- **全面业务逻辑**：考虑所有可能情况，包括异常和边界条件
|
||
- **关键日志记录**：重要操作必须记录日志，便于问题排查
|
||
- **防御性编程**：对所有输入进行验证，实现健壮的错误处理
|
||
|
||
**注释要求：**
|
||
|
||
```typescript
|
||
/**
|
||
* 玩家服务类
|
||
*
|
||
* 职责：处理玩家相关的业务逻辑
|
||
* 主要方法：createPlayer(), updatePlayerInfo(), getPlayerById()
|
||
* 使用场景：玩家注册登录流程、个人陈列室数据管理
|
||
*/
|
||
@Injectable()
|
||
export class PlayerService {
|
||
/**
|
||
* 创建新玩家
|
||
* @param email 玩家邮箱地址
|
||
* @param nickname 玩家昵称
|
||
* @returns Promise<Player> 创建成功的玩家对象
|
||
* @throws BadRequestException 当邮箱格式错误时
|
||
*/
|
||
async createPlayer(email: string, nickname: string): Promise<Player> {
|
||
// 详细的业务逻辑实现...
|
||
}
|
||
}
|
||
```
|
||
|
||
详细规范请查看：[后端开发规范指南](./docs/backend_development_guide.md)
|
||
|
||
## 📚 开发文档
|
||
|
||
### 🔥 必读文档
|
||
- **[AI 辅助开发规范指南](./docs/AI辅助开发规范指南.md)** - 🚨 **所有开发者必读！** 教你如何使用 AI 遵循项目规范
|
||
|
||
### 📋 规范文档
|
||
- [后端开发规范](./docs/backend_development_guide.md) - 注释标准、业务逻辑设计和日志记录要求
|
||
- [Git 提交规范](./docs/git_commit_guide.md) - Git 提交信息格式和最佳实践
|
||
- [命名规范](./docs/naming_convention.md) - 项目命名规范和最佳实践
|
||
- [NestJS 使用指南](./docs/nestjs_guide.md) - 详细的 NestJS 开发指南，包含实战案例
|
||
|
||
### 💡 使用建议
|
||
1. **开发前**：先读 AI 辅助指南，了解如何用 AI 帮助遵循规范
|
||
2. **开发中**：参考具体规范文档，使用 AI 实时检查代码质量
|
||
3. **提交前**：用 AI 检查代码和提交信息是否符合规范
|
||
|
||
## 前置要求
|
||
|
||
- **Node.js** >= 18.0.0 默认：24.7.0
|
||
- **pnpm** >= 8.0.0（推荐）默认：10.25.0
|
||
|
||
如果还没有安装 pnpm，请先安装：
|
||
|
||
```bash
|
||
npm install -g pnpm
|
||
```
|
||
|
||
检查版本：
|
||
|
||
```bash
|
||
node --version
|
||
pnpm --version
|
||
```
|
||
|
||
## 安装依赖
|
||
|
||
```bash
|
||
pnpm install
|
||
```
|
||
|
||
## 开发
|
||
|
||
启动开发服务器（支持热重载）：
|
||
|
||
```bash
|
||
pnpm dev
|
||
```
|
||
|
||
服务器将运行在 `http://localhost:3000`
|
||
|
||
## 测试
|
||
|
||
运行测试：
|
||
|
||
```bash
|
||
pnpm test
|
||
```
|
||
|
||
运行测试并监听文件变化：
|
||
|
||
```bash
|
||
pnpm test:watch
|
||
```
|
||
|
||
运行测试并生成覆盖率报告：
|
||
|
||
```bash
|
||
pnpm test:cov
|
||
```
|
||
|
||
## 构建
|
||
|
||
```bash
|
||
pnpm build
|
||
```
|
||
|
||
## 生产环境运行
|
||
|
||
```bash
|
||
pnpm start:prod
|
||
```
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
src/
|
||
├── api/ # API 接口层（控制器、网关）
|
||
├── business/ # 业务逻辑层
|
||
├── core/ # 核心功能模块
|
||
│ ├── db/ # 数据库相关
|
||
│ └── utils/ # 工具函数
|
||
│ └── logger/ # 日志系统
|
||
├── main.ts # 应用入口
|
||
├── app.module.ts # 根模块
|
||
├── app.controller.ts # 根控制器
|
||
└── app.service.ts # 根服务
|
||
test/
|
||
├── api/ # API 测试
|
||
└── service/ # 服务测试
|
||
docs/ # 项目文档
|
||
├── backend_development_guide.md # 后端开发规范
|
||
├── git_commit_guide.md # Git 提交规范
|
||
├── naming_convention.md # 命名规范
|
||
└── nestjs_guide.md # NestJS 使用指南
|
||
```
|
||
|
||
## 核心功能
|
||
|
||
### 🔐 用户认证系统
|
||
|
||
完整的用户认证解决方案，支持多种登录方式和安全特性：
|
||
|
||
- 用户名/邮箱/手机号登录
|
||
- GitHub OAuth 第三方登录
|
||
- 密码重置和修改功能
|
||
- bcrypt 密码加密
|
||
- 基于角色的权限控制
|
||
|
||
**详细文档**: [用户认证系统文档](./docs/systems/user-auth/README.md)
|
||
|
||
### 📊 日志系统
|
||
|
||
基于 Pino 的高性能日志系统，提供结构化日志记录：
|
||
|
||
- 高性能日志记录
|
||
- 自动敏感信息过滤
|
||
- 多级别日志控制
|
||
- 请求上下文绑定
|
||
|
||
**详细文档**: [日志系统文档](./docs/systems/logger/README.md)
|
||
|
||
**💡 提示：使用 [AI 辅助开发指南](./docs/AI辅助开发规范指南.md) 可以让 AI 帮你自动生成符合规范的代码！**
|
||
|
||
## 下一步
|
||
|
||
- 在 `src/api/` 目录下创建游戏相关的控制器和网关
|
||
- 在 `src/model/` 目录下定义游戏数据模型
|
||
- 在 `src/service/` 目录下实现游戏业务逻辑
|
||
- 使用 NestJS CLI 快速生成模块：`nest g module game`
|
||
- 添加 WebSocket 网关实现实时游戏逻辑
|