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