shiyue/DFJ
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
DFJ/02_详细设计文档/后端技术架构详设.md

887 lines
27 KiB
Markdown
Raw Permalink Blame History

# 后端技术架构详设文档
> **文档版本**: v1.0
> **撰写人**: 后端架构师
> **创建日期**: 2024年9月11日
## 1. 后端架构总览
### 1.1 技术栈详细说明
```typescript
// 后端技术栈配置
{
"runtime": "Node.js 18+", // 运行环境
"framework": "Fastify 4.x", // Web框架
"language": "TypeScript 5.0+", // 开发语言
"database": "MongoDB 6.0", // 主数据库
"cache": "Redis 7.0", // 缓存数据库
"websocket": "ws + socket.io", // WebSocket库
"orm": "Mongoose 7.x", // ODM工具
"validation": "Joi", // 数据验证
"auth": "JWT + 微信登录", // 认证方案
"logging": "Winston + Morgan", // 日志系统
"testing": "Jest + Supertest", // 测试框架
"process": "PM2", // 进程管理
"containerization": "Docker" // 容器化
}
```
### 1.2 服务架构设计
```
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ Load Balancer │ │ Gateway │ │ Static CDN │
│ (Nginx) │ │ (API Route) │ │ (Assets) │
└─────────────────┘ └─────────────────┘ └─────────────────┘
│ │ │
└───────────────────────┼───────────────────────┘
│
┌───────────────────────┴───────────────────────┐
│ Application │
│ Layer (Fastify) │
└───────────────────────┬───────────────────────┘
│
┌────────────────────────────┼────────────────────────────┐
│ │ │
┌───▼────┐ ┌─────────▼─────────┐ ┌─────────▼─────────┐
│ Auth │ │ Game Service │ │ WebSocket │
│Service │ │ (Core Logic) │ │ Service │
└────────┘ └───────────────────┘ └───────────────────┘
│ │ │
└───────────────────┼────────────────────────┘
│
┌───────────────────┼───────────────────┐
│ │ │
┌───▼─────┐ ┌───────▼──────┐ ┌──────▼─────┐
│MongoDB │ │ Redis │ │ External │
│(主数据) │ │ (缓存) │ │ APIs │
└─────────┘ └──────────────┘ └────────────┘
```
### 1.3 项目目录结构
```
src/
├── app.ts # 应用入口
├── server.ts # 服务器启动
├── config/ # 配置文件
│ ├── database.ts # 数据库配置
│ ├── redis.ts # Redis配置
│ ├── jwt.ts # JWT配置
│ └── environment.ts # 环境变量
├── controllers/ # 控制器层
│ ├── auth.controller.ts # 认证控制器
│ ├── room.controller.ts # 房间控制器
│ ├── game.controller.ts # 游戏控制器
│ └── user.controller.ts # 用户控制器
├── services/ # 业务逻辑层
│ ├── auth.service.ts # 认证服务
│ ├── room.service.ts # 房间服务
│ ├── game.service.ts # 游戏服务
│ ├── user.service.ts # 用户服务
│ └── websocket.service.ts # WebSocket服务
├── models/ # 数据模型
│ ├── User.ts # 用户模型
│ ├── Room.ts # 房间模型
│ ├── Game.ts # 游戏模型
│ └── GameSession.ts # 游戏会话模型
├── middleware/ # 中间件
│ ├── auth.middleware.ts # 认证中间件
│ ├── validation.middleware.ts # 验证中间件
│ ├── error.middleware.ts # 错误处理中间件
│ └── logging.middleware.ts # 日志中间件
├── routes/ # 路由定义
│ ├── auth.routes.ts # 认证路由
│ ├── room.routes.ts # 房间路由
│ ├── game.routes.ts # 游戏路由
│ └── user.routes.ts # 用户路由
├── utils/ # 工具函数
│ ├── gameLogic.ts # 游戏逻辑工具
│ ├── encryption.ts # 加密工具
│ ├── validators.ts # 验证工具
│ └── helpers.ts # 通用工具
├── websocket/ # WebSocket处理
│ ├── handlers/ # 消息处理器
│ ├── events.ts # 事件定义
│ └── connection.ts # 连接管理
└── tests/ # 测试文件
├── unit/ # 单元测试
├── integration/ # 集成测试
└── e2e/ # 端到端测试
```
## 2. 核心服务设计
### 2.1 Fastify应用配置
```typescript
// app.ts - 应用主配置
import Fastify, { FastifyInstance } from 'fastify'
import fastifyJwt from '@fastify/jwt'
import fastifyWebsocket from '@fastify/websocket'
import fastifyCors from '@fastify/cors'
import fastifyRateLimit from '@fastify/rate-limit'
export const createApp = async (): Promise<FastifyInstance> => {
const app = Fastify({
logger: {
level: process.env.LOG_LEVEL || 'info',
transport: process.env.NODE_ENV === 'development' ? {
target: 'pino-pretty',
options: {
colorize: true,
translateTime: 'HH:MM:ss',
ignore: 'pid,hostname'
}
} : undefined
}
})
// 注册插件
await app.register(fastifyJwt, {
secret: process.env.JWT_SECRET!,
sign: { expiresIn: '7d' }
})
await app.register(fastifyWebsocket, {
options: {
maxPayload: 1048576, // 1MB
verifyClient: (info) => {
// WebSocket连接验证
return verifyWebSocketClient(info)
}
}
})
await app.register(fastifyCors, {
origin: process.env.CORS_ORIGINS?.split(',') || ['http://localhost:3000'],
credentials: true
})
await app.register(fastifyRateLimit, {
max: 100,
timeWindow: '1 minute',
errorResponseBuilder: (request, context) => {
return {
code: 429,
error: 'Too Many Requests',
message: `请求过于频繁，请${Math.round(context.ttl / 1000)}秒后重试`
}
}
})
// 注册路由
await app.register(authRoutes, { prefix: '/api/auth' })
await app.register(userRoutes, { prefix: '/api/users' })
await app.register(roomRoutes, { prefix: '/api/rooms' })
await app.register(gameRoutes, { prefix: '/api/games' })
await app.register(websocketRoutes, { prefix: '/ws' })
// 错误处理
app.setErrorHandler(errorHandler)
app.setNotFoundHandler(notFoundHandler)
return app
}
// 健康检查端点
app.get('/health', async (request, reply) => {
const health = {
status: 'ok',
timestamp: new Date().toISOString(),
services: {
database: await checkDatabaseHealth(),
redis: await checkRedisHealth(),
websocket: checkWebSocketHealth()
}
}
reply.send(health)
})
```
### 2.2 认证服务设计
```typescript
// services/auth.service.ts
import jwt from 'jsonwebtoken'
import { User } from '../models/User'
import { redisClient } from '../config/redis'
export class AuthService {
// 微信小程序登录
async wxLogin(code: string): Promise<{ user: User; token: string }> {
try {
// 1. 通过code获取openid
const wxSession = await this.getWxSession(code)
// 2. 查找或创建用户
let user = await User.findOne({ openid: wxSession.openid })
if (!user) {
user = await User.create({
openid: wxSession.openid,
sessionKey: wxSession.session_key,
unionid: wxSession.unionid,
createdAt: new Date()
})
} else {
// 更新session_key
user.sessionKey = wxSession.session_key
await user.save()
}
// 3. 生成JWT token
const token = this.generateToken(user._id.toString())
// 4. 缓存用户会话
await this.cacheUserSession(user._id.toString(), token)
return { user, token }
} catch (error) {
throw new Error('微信登录失败')
}
}
// 获取微信session
private async getWxSession(code: string): Promise<WxSessionResponse> {
const response = await fetch(`https://api.weixin.qq.com/sns/jscode2session`, {
method: 'GET',
params: {
appid: process.env.WX_APPID!,
secret: process.env.WX_APP_SECRET!,
js_code: code,
grant_type: 'authorization_code'
}
})
const data = await response.json()
if (data.errcode) {
throw new Error(`微信API错误: ${data.errmsg}`)
}
return data
}
// 生成JWT token
private generateToken(userId: string): string {
return jwt.sign(
{ userId, type: 'access' },
process.env.JWT_SECRET!,
{ expiresIn: '7d' }
)
}
// 验证token
async verifyToken(token: string): Promise<{ userId: string; valid: boolean }> {
try {
const decoded = jwt.verify(token, process.env.JWT_SECRET!) as any
// 检查会话是否仍然有效
const sessionExists = await redisClient.exists(`session:${decoded.userId}`)
return {
userId: decoded.userId,
valid: sessionExists === 1
}
} catch (error) {
return { userId: '', valid: false }
}
}
// 缓存用户会话
private async cacheUserSession(userId: string, token: string): Promise<void> {
const sessionData = {
token,
createdAt: new Date().toISOString(),
lastActive: new Date().toISOString()
}
await redisClient.setex(
`session:${userId}`,
7 * 24 * 60 * 60, // 7天过期
JSON.stringify(sessionData)
)
}
// 刷新用户活跃时间
async refreshUserActivity(userId: string): Promise<void> {
const sessionKey = `session:${userId}`
const sessionData = await redisClient.get(sessionKey)
if (sessionData) {
const session = JSON.parse(sessionData)
session.lastActive = new Date().toISOString()
await redisClient.setex(
sessionKey,
7 * 24 * 60 * 60,
JSON.stringify(session)
)
}
}
// 用户登出
async logout(userId: string): Promise<void> {
await redisClient.del(`session:${userId}`)
}
}
// 认证中间件
export const authMiddleware = async (request: FastifyRequest, reply: FastifyReply) => {
try {
const authHeader = request.headers.authorization
if (!authHeader || !authHeader.startsWith('Bearer ')) {
return reply.code(401).send({ error: '缺少认证令牌' })
}
const token = authHeader.substring(7)
const authService = new AuthService()
const { userId, valid } = await authService.verifyToken(token)
if (!valid) {
return reply.code(401).send({ error: '无效的认证令牌' })
}
// 刷新用户活跃时间
await authService.refreshUserActivity(userId)
// 将用户ID添加到请求上下文
request.user = { id: userId }
} catch (error) {
return reply.code(401).send({ error: '认证失败' })
}
}
```
### 2.3 房间管理服务
```typescript
// services/room.service.ts
import { Room } from '../models/Room'
import { User } from '../models/User'
import { redisClient } from '../config/redis'
import { websocketService } from './websocket.service'
export class RoomService {
// 创建房间
async createRoom(hostId: string): Promise<Room> {
const roomCode = this.generateRoomCode()
const room = await Room.create({
code: roomCode,
hostId,
status: 'waiting',
maxPlayers: 2,
currentPlayers: 1,
createdAt: new Date()
})
// 缓存房间信息
await this.cacheRoomData(room)
// 通知房间列表更新
await websocketService.broadcastRoomListUpdate()
return room
}
// 加入房间
async joinRoom(roomCode: string, playerId: string): Promise<Room> {
const room = await Room.findOne({ code: roomCode })
if (!room) {
throw new Error('房间不存在')
}
if (room.status !== 'waiting') {
throw new Error('房间已开始游戏或已结束')
}
if (room.currentPlayers >= room.maxPlayers) {
throw new Error('房间已满')
}
if (room.hostId === playerId) {
throw new Error('不能加入自己创建的房间')
}
// 更新房间信息
room.guestId = playerId
room.currentPlayers = 2
room.status = 'ready'
await room.save()
// 更新缓存
await this.cacheRoomData(room)
// 通知房间内玩家
await websocketService.notifyRoomUpdate(roomCode, {
type: 'PLAYER_JOINED',
room: room.toObject(),
playerId
})
return room
}
// 离开房间
async leaveRoom(roomCode: string, playerId: string): Promise<void> {
const room = await Room.findOne({ code: roomCode })
if (!room) {
throw new Error('房间不存在')
}
if (room.hostId === playerId) {
// 房主离开，删除房间
await Room.deleteOne({ code: roomCode })
await redisClient.del(`room:${roomCode}`)
// 通知客人
if (room.guestId) {
await websocketService.notifyPlayer(room.guestId, {
type: 'ROOM_CLOSED',
message: '房主已离开，房间关闭'
})
}
} else if (room.guestId === playerId) {
// 客人离开
room.guestId = undefined
room.currentPlayers = 1
room.status = 'waiting'
await room.save()
await this.cacheRoomData(room)
// 通知房主
await websocketService.notifyPlayer(room.hostId, {
type: 'PLAYER_LEFT',
room: room.toObject()
})
}
// 更新房间列表
await websocketService.broadcastRoomListUpdate()
}
// 获取房间列表
async getRoomList(): Promise<Room[]> {
const rooms = await Room.find({
status: 'waiting',
currentPlayers: { $lt: 2 }
}).populate('host', 'nickname avatar').lean()
return rooms
}
// 获取房间详情
async getRoomDetails(roomCode: string): Promise<Room | null> {
// 先从缓存获取
const cachedRoom = await redisClient.get(`room:${roomCode}`)
if (cachedRoom) {
return JSON.parse(cachedRoom)
}
// 从数据库获取
const room = await Room.findOne({ code: roomCode })
.populate('host', 'nickname avatar')
.populate('guest', 'nickname avatar')
.lean()
if (room) {
await this.cacheRoomData(room)
}
return room
}
// 开始游戏
async startGame(roomCode: string, hostId: string): Promise<void> {
const room = await Room.findOne({ code: roomCode })
if (!room) {
throw new Error('房间不存在')
}
if (room.hostId !== hostId) {
throw new Error('只有房主可以开始游戏')
}
if (room.currentPlayers < 2) {
throw new Error('等待其他玩家加入')
}
// 更新房间状态
room.status = 'playing'
await room.save()
// 创建游戏会话
const gameService = new GameService()
const gameSession = await gameService.createGameSession(room)
// 通知玩家游戏开始
await websocketService.notifyRoomUpdate(roomCode, {
type: 'GAME_STARTED',
gameSession: gameSession.toObject()
})
}
// 生成房间码
private generateRoomCode(): string {
const chars = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789'
let result = ''
for (let i = 0; i < 6; i++) {
result += chars.charAt(Math.floor(Math.random() * chars.length))
}
return result
}
// 缓存房间数据
private async cacheRoomData(room: any): Promise<void> {
await redisClient.setex(
`room:${room.code}`,
30 * 60, // 30分钟过期
JSON.stringify(room)
)
}
}
```
### 2.4 游戏核心服务
```typescript
// services/game.service.ts
import { GameSession } from '../models/GameSession'
import { Room } from '../models/Room'
import { GameLogic } from '../utils/gameLogic'
import { websocketService } from './websocket.service'
export class GameService {
// 创建游戏会话
async createGameSession(room: Room): Promise<GameSession> {
const gameSession = await GameSession.create({
roomId: room._id,
roomCode: room.code,
players: [room.hostId, room.guestId],
gameState: {
phase: 'PLACING',
currentPlayer: room.hostId, // 房主先开始
boards: {
[room.hostId]: GameLogic.createEmptyBoard(),
[room.guestId!]: GameLogic.createEmptyBoard()
},
moves: [],
startedAt: new Date()
},
createdAt: new Date()
})
return gameSession
}
// 放置飞机
async placePlanes(
gameSessionId: string,
playerId: string,
planes: PlaneData[]
): Promise<void> {
const session = await GameSession.findById(gameSessionId)
if (!session) {
throw new Error('游戏会话不存在')
}
if (session.gameState.phase !== 'PLACING') {
throw new Error('当前不是飞机放置阶段')
}
// 验证飞机放置是否合法
const isValid = GameLogic.validatePlanesPlacement(planes)
if (!isValid) {
throw new Error('飞机放置不合法')
}
// 更新游戏状态
session.gameState.boards[playerId] = GameLogic.placePlanesOnBoard(
session.gameState.boards[playerId],
planes
)
// 标记玩家已准备
session.gameState.playersReady = session.gameState.playersReady || {}
session.gameState.playersReady[playerId] = true
// 检查是否所有玩家都已准备
const allReady = session.players.every(p =>
session.gameState.playersReady[p]
)
if (allReady) {
// 开始对战阶段
session.gameState.phase = 'BATTLING'
session.gameState.battleStartedAt = new Date()
}
await session.save()
// 通知所有玩家状态更新
await websocketService.notifyGameUpdate(session.roomCode, {
type: 'PLACEMENT_UPDATE',
playerId,
ready: true,
allReady,
gameState: session.gameState
})
}
// 执行攻击
async attack(
gameSessionId: string,
attackerId: string,
position: Position
): Promise<AttackResult> {
const session = await GameSession.findById(gameSessionId)
if (!session) {
throw new Error('游戏会话不存在')
}
if (session.gameState.phase !== 'BATTLING') {
throw new Error('当前不是对战阶段')
}
if (session.gameState.currentPlayer !== attackerId) {
throw new Error('不是你的回合')
}
// 确定被攻击的玩家
const defenderId = session.players.find(p => p !== attackerId)!
const defenderBoard = session.gameState.boards[defenderId]
// 执行攻击逻辑
const attackResult = GameLogic.processAttack(defenderBoard, position)
// 更新游戏状态
session.gameState.boards[defenderId] = attackResult.updatedBoard
session.gameState.moves.push({
playerId: attackerId,
type: 'ATTACK',
position,
result: attackResult.type,
timestamp: new Date()
})
// 检查游戏是否结束
if (attackResult.gameEnded) {
session.gameState.phase = 'FINISHED'
session.gameState.winner = attackerId
session.gameState.endedAt = new Date()
// 更新玩家统计
await this.updatePlayerStats(attackerId, defenderId)
} else {
// 切换当前玩家
session.gameState.currentPlayer = defenderId
}
await session.save()
// 通知所有玩家攻击结果
await websocketService.notifyGameUpdate(session.roomCode, {
type: 'ATTACK_RESULT',
attackerId,
defenderId,
position,
result: attackResult,
gameState: session.gameState
})
return attackResult
}
// 获取游戏状态
async getGameState(gameSessionId: string, playerId: string): Promise<any> {
const session = await GameSession.findById(gameSessionId)
if (!session) {
throw new Error('游戏会话不存在')
}
if (!session.players.includes(playerId)) {
throw new Error('你不在这个游戏中')
}
// 返回过滤后的游戏状态（隐藏对手飞机位置）
const filteredState = {
...session.gameState,
boards: {
[playerId]: session.gameState.boards[playerId],
// 对手棋盘只显示攻击结果，不显示飞机位置
opponent: GameLogic.filterOpponentBoard(
session.gameState.boards[session.players.find(p => p !== playerId)!]
)
}
}
return filteredState
}
// 玩家投降
async surrender(gameSessionId: string, playerId: string): Promise<void> {
const session = await GameSession.findById(gameSessionId)
if (!session) {
throw new Error('游戏会话不存在')
}
if (session.gameState.phase === 'FINISHED') {
throw new Error('游戏已结束')
}
const winnerId = session.players.find(p => p !== playerId)!
// 更新游戏状态
session.gameState.phase = 'FINISHED'
session.gameState.winner = winnerId
session.gameState.endedAt = new Date()
session.gameState.surrendered = true
await session.save()
// 更新玩家统计
await this.updatePlayerStats(winnerId, playerId)
// 通知游戏结束
await websocketService.notifyGameUpdate(session.roomCode, {
type: 'GAME_ENDED',
winner: winnerId,
reason: 'SURRENDER',
gameState: session.gameState
})
}
// 更新玩家统计
private async updatePlayerStats(winnerId: string, loserId: string): Promise<void> {
const User = require('../models/User').User
// 更新获胜者统计
await User.updateOne(
{ _id: winnerId },
{
$inc: {
'stats.totalGames': 1,
'stats.wins': 1
}
}
)
// 更新失败者统计
await User.updateOne(
{ _id: loserId },
{
$inc: {
'stats.totalGames': 1
}
}
)
// 重新计算胜率
const users = await User.find({ _id: { $in: [winnerId, loserId] } })
for (const user of users) {
user.stats.winRate = user.stats.totalGames > 0
? (user.stats.wins / user.stats.totalGames * 100).toFixed(2)
: 0
await user.save()
}
}
}
```
## 3. WebSocket服务设计
### 3.1 WebSocket连接管理
```typescript
// websocket/connection.ts
import { WebSocket } from 'ws'
import { EventEmitter } from 'events'
import { redisClient } from '../config/redis'
export class WebSocketManager extends EventEmitter {
private connections = new Map<string, WebSocketConnection>()
private userConnections = new Map<string, string[]>() // userId -> connectionIds[]
private roomConnections = new Map<string, string[]>() // roomCode -> connectionIds[]
// 添加连接
addConnection(connectionId: string, ws: WebSocket, userId: string): void {
const connection = new WebSocketConnection(connectionId, ws, userId)
this.connections.set(connectionId, connection)
// 建立用户映射
if (!this.userConnections.has(userId)) {
this.userConnections.set(userId, [])
}
this.userConnections.get(userId)!.push(connectionId)
// 设置连接事件处理
connection.on('message', (message) => {
this.handleMessage(connectionId, message)
})
connection.on('close', () => {
this.removeConnection(connectionId)
})
connection.on('error', (error) => {
console.error(`WebSocket连接错误 ${connectionId}:`, error)
this.removeConnection(connectionId)
})
console.log(`WebSocket连接已建立: ${connectionId} (用户: ${userId})`)
}
// 移除连接
removeConnection(connectionId: string): void {
const connection = this.connections.get(connectionId)
if (!connection) return
const userId = connection.userId
// 移除连接映射
this.connections.delete(connectionId)
// 移除用户映射
const userConns = this.userConnections.get(userId)
if (userConns) {
const index = userConns.indexOf(connectionId)
if (index > -1) {
userConns.splice(index, 1)
}
if (userConns.length === 0) {
this.userConnections.delete(userId)
}
}
// 移除房间映射
for (const [roomCode, connections] of this.roomConnections.entries()) {
const index = connections.indexOf(connectionId)
if (index > -1) {
connections.splice(index, 1)
if (connections.length === 0) {
this.roomConnections.delete(roomCode)
}
// 通知房间内其他用户
this.notifyRoomUpdate(roomCode, {
type: 'PLAYER_DISCONNECTED',
playerId: userId
})
}
}
console.log(`WebSocket连接已关闭: ${connectionId} (用户: ${userId})`)
}
}
Reference in New Issue View Git Blame Copy Permalink