Files

- 重新组织docs目录结构，按功能模块分类
- 新增deployment和development目录
- 更新API文档结构
- 添加客户端README文档
- 移除过时的文档文件

2025-12-24 18:04:14 +08:00

7.6 KiB

Raw Blame History

测试指南

本项目支持无数据库和无邮件服务器的测试模式，让你可以快速验证所有功能！

🚀 快速开始

1. 环境配置

# 复制环境配置文件
cp .env.example .env

默认配置已经设置为测试模式，无需修改即可使用。

2. 启动服务

# 安装依赖
npm install

# 启动开发服务器
npm run dev

3. 运行测试

Windows (PowerShell):

.\test-api.ps1

Linux/macOS:

./test-api.sh

自定义参数:

# Windows
.\test-api.ps1 -BaseUrl "http://localhost:3000" -TestEmail "custom@example.com"

# Linux/macOS
./test-api.sh "http://localhost:3000" "custom@example.com"

🧪 测试功能

API功能测试

测试脚本会验证以下核心功能：

用户认证模块：

✅ 邮箱验证码发送 - 生成6位数验证码，测试模式输出到控制台
✅ 邮箱验证码验证 - 验证码校验和自动清理
✅ 用户注册 - 完整的用户注册流程，包含邮箱验证
✅ 用户登录 - 支持用户名/邮箱/手机号多种方式登录

系统状态测试：

✅ 应用状态检查 - 验证服务器运行状态和系统信息
✅ Redis文件存储 - 验证验证码存储和读取功能
✅ 内存数据库 - 验证用户数据存储功能

单元测试覆盖

核心服务测试（7个测试套件，140个测试用例）：

LoginCoreService - 登录核心服务（15个测试）
- 用户登录成功/失败场景
- 用户注册功能测试
- GitHub OAuth登录测试
- 密码重置和修改功能
- 用户状态验证（active、inactive、locked等）
AdminService - 管理员服务测试
- 管理员登录认证
- 用户列表管理
- 用户密码重置
- 日志管理功能
VerificationService - 验证码服务测试
- 验证码生成和验证
- 频率限制机制
- Redis存储操作
- 错误处理和边界条件
EmailService - 邮件服务测试
- 邮件发送功能（测试模式和生产模式）
- 验证码邮件模板
- 连接验证和错误处理
- SMTP配置测试
UsersService - 用户数据服务测试
- 用户CRUD操作
- 用户查询功能
- 数据验证和约束
AdminCoreService - 管理员核心服务测试
- 管理员认证逻辑
- 权限验证
- 管理员引导创建
LoggerService - 日志服务测试
- 日志记录功能
- 敏感信息过滤
- 日志级别控制

E2E端到端测试

登录功能完整流程测试：

用户注册 → 邮箱验证 → 登录验证
GitHub OAuth登录流程
密码重置完整流程
错误处理和边界条件测试

🔧 测试模式特性

🗄️ Redis 文件存储 - 使用 redis-data/redis.json 存储验证码
📧 邮件测试模式 - 邮件内容输出到控制台，无需真实SMTP
💾 内存用户存储 - 无需数据库，用户数据存储在内存中
🔄 自动切换 - 根据配置自动选择存储模式

📊 单元测试

运行测试命令

# 运行所有单元测试
npm test

# 监听模式（开发时使用）
npm run test:watch

# 生成覆盖率报告
npm run test:cov

# 运行特定测试文件
npm test -- src/core/login_core/login_core.service.spec.ts

测试覆盖情况

测试统计：

测试套件：7个
测试用例：140个
覆盖率：100%通过

测试文件列表：

src/core/login_core/login_core.service.spec.ts          # 登录核心服务
src/business/admin/admin.service.spec.ts                # 管理员服务
src/core/utils/verification/verification.service.spec.ts # 验证码服务
src/core/utils/email/email.service.spec.ts             # 邮件服务
src/core/db/users/users.service.spec.ts                # 用户数据服务
src/core/admin_core/admin_core.service.spec.ts         # 管理员核心服务
src/core/utils/logger/logger.service.spec.ts           # 日志服务
test/business/login.e2e-spec.ts                        # E2E端到端测试

测试场景覆盖

正常流程测试：

用户注册、登录、密码管理
邮箱验证码发送和验证
管理员认证和用户管理
系统状态和日志功能

异常情况测试：

无效输入和参数验证
网络连接失败处理
权限验证和访问控制
频率限制和安全防护

边界条件测试：

密码强度验证
验证码过期处理
用户状态变更
数据库连接异常

🌐 生产环境配置

要切换到生产环境，编辑 .env 文件：

# 启用数据库（取消注释并填入真实数据）
DB_HOST=your_mysql_host
DB_PORT=3306
DB_USERNAME=your_db_username
DB_PASSWORD=your_db_password
DB_NAME=your_db_name

# 启用真实Redis（取消注释并设置）
USE_FILE_REDIS=false
REDIS_HOST=your_redis_host
REDIS_PORT=6379
REDIS_PASSWORD=your_redis_password

# 启用邮件服务（取消注释并填入真实数据）
EMAIL_HOST=smtp.gmail.com
EMAIL_PORT=587
EMAIL_USER=your_email@gmail.com
EMAIL_PASS=your_app_password
EMAIL_FROM="Whale Town Game" <noreply@whaletown.com>

# 生产环境设置
NODE_ENV=production
LOG_LEVEL=info

🔍 故障排除

服务启动失败

端口占用：检查端口3000是否被占用，使用 netstat -ano | findstr :3000 查看
Node.js版本：确认Node.js版本 >= 18.0.0，使用 node --version 检查
依赖问题：运行 npm install 或 pnpm install 重新安装依赖
权限问题：确保有足够的文件读写权限

测试脚本执行失败

服务器状态：确认服务器正在运行，访问 http://localhost:3000 检查
网络连接：检查防火墙设置，确保端口3000可访问
脚本权限：在Linux/macOS上确保脚本有执行权限：chmod +x test-api.sh
PowerShell策略：Windows上可能需要设置执行策略：Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

单元测试失败

依赖冲突：清理node_modules并重新安装：rm -rf node_modules && npm install
TypeScript错误：运行 npm run build 检查编译错误
环境变量：确保测试环境变量配置正确
数据库连接：测试模式下应该使用内存数据库，检查配置

Redis文件存储问题

目录权限：检查 redis-data 目录的读写权限
配置设置：确认 USE_FILE_REDIS=true 设置正确
文件锁定：确保redis.json文件没有被其他进程锁定
磁盘空间：检查磁盘空间是否充足

邮件测试模式问题

配置检查：确认邮件配置为注释状态（测试模式）
控制台输出：检查服务器控制台是否有邮件内容输出
日志级别：确保日志级别设置为info或debug以查看详细输出

常见错误解决

EADDRINUSE错误：

# 查找占用端口的进程
netstat -ano | findstr :3000
# 结束进程（Windows）
taskkill /PID <进程ID> /F

权限错误：

# Linux/macOS设置权限
chmod +x test-api.sh
chmod 755 redis-data/

模块未找到错误：

# 清理并重新安装
rm -rf node_modules package-lock.json
npm install

📝 测试数据

测试完成后，你可以查看：

redis-data/redis.json - 验证码存储数据
服务器控制台 - 邮件内容输出
测试脚本输出 - API响应结果

🎯 下一步

查看 API 文档了解更多接口
阅读开发规范开始开发
使用 AI 辅助指南提高开发效率

7.6 KiB Raw Blame History Unescape Escape