whale-town-end/src/core/location_broadcast_core

Location Broadcast Core 模块

模块概述

Location Broadcast Core 是位置广播系统的核心技术实现模块，专门为位置广播业务提供技术支撑。该模块负责管理用户会话、位置数据缓存、数据持久化等核心技术功能，确保位置广播系统的高性能和可靠性。

模块组成

• LocationBroadcastCore: 位置广播核心服务，处理会话管理和位置缓存
• UserPositionCore: 用户位置持久化核心服务，处理数据库操作
• 接口定义: 核心服务接口和数据结构定义

技术架构

• 架构层级: Core层（核心技术实现）
• 命名规范: 使用_core后缀，表明为业务支撑模块
• 职责边界: 专注技术实现，不包含业务逻辑

对外接口

LocationBroadcastCore 服务接口

会话管理

• addUserToSession(sessionId, userId, socketId) - 添加用户到会话
• removeUserFromSession(sessionId, userId) - 从会话中移除用户
• getSessionUsers(sessionId) - 获取会话中的用户列表

位置数据管理

• setUserPosition(userId, position) - 设置用户位置到Redis缓存
• getUserPosition(userId) - 从Redis获取用户位置
• getSessionPositions(sessionId) - 获取会话中所有用户位置
• getMapPositions(mapId) - 获取地图中所有用户位置

数据清理维护

• cleanupUserData(userId) - 清理用户相关数据
• cleanupEmptySession(sessionId) - 清理空会话
• cleanupExpiredData(expireTime) - 清理过期数据

UserPositionCore 服务接口

数据持久化

• saveUserPosition(userId, position) - 保存用户位置到数据库
• loadUserPosition(userId) - 从数据库加载用户位置

历史记录管理

• savePositionHistory(userId, position, sessionId?) - 保存位置历史记录
• getPositionHistory(userId, limit?) - 获取位置历史记录

批量操作

• batchUpdateUserStatus(userIds, status) - 批量更新用户状态
• cleanupExpiredPositions(expireTime) - 清理过期位置数据

统计分析

• getUserPositionStats(userId) - 获取用户位置统计信息
• migratePositionData(fromUserId, toUserId) - 迁移位置数据

内部依赖

项目内部依赖

Redis服务依赖

• 依赖标识: REDIS_SERVICE
• 用途: 高性能位置数据缓存、会话状态管理
• 关键操作: sadd, setex, get, del, smembers, scard等

用户档案服务依赖

• 依赖标识: IUserProfilesService
• 用途: 用户位置数据持久化、用户信息查询
• 关键操作: updatePosition, findByUserId, batchUpdateStatus

数据结构依赖

• Position接口: 位置数据结构定义
• SessionUser接口: 会话用户数据结构
• PositionHistory接口: 位置历史记录结构
• 核心服务接口: ILocationBroadcastCore, IUserPositionCore

核心特性

技术特性

高性能缓存

• Redis缓存: 位置数据存储在Redis中，支持毫秒级读写
• 过期策略: 会话数据3600秒过期，位置数据1800秒过期
• 批量操作: 支持批量数据读写，优化性能

数据一致性

• 双写策略: 位置数据同时写入Redis缓存和MySQL数据库
• 事务处理: 确保数据操作的原子性
• 异常恢复: 完善的错误处理和数据恢复机制

可扩展性

• 接口抽象: 通过依赖注入实现服务解耦
• 模块化设计: 清晰的职责分离和边界定义
• 配置化: 关键参数通过常量定义，便于调整

功能特性

实时会话管理

• 用户加入/离开: 实时更新会话状态
• Socket映射: 维护用户与WebSocket连接的映射关系
• 自动清理: 空会话和过期数据的自动清理

位置数据处理

• 多地图支持: 支持用户在不同地图间切换
• 位置历史: 记录用户位置变化轨迹
• 地理查询: 按地图或会话查询用户位置

数据维护

• 定期清理: 支持过期数据的批量清理
• 数据迁移: 支持用户数据的迁移操作
• 统计分析: 提供位置数据的统计功能

质量特性

可靠性

• 异常处理: 全面的错误处理和日志记录
• 数据校验: 严格的输入参数验证
• 容错机制: 部分失败不影响整体功能

可观测性

• 详细日志: 操作开始、成功、失败的完整日志
• 性能监控: 记录操作耗时和性能指标
• 错误追踪: 完整的错误堆栈和上下文信息

可测试性

• 单元测试: 60个测试用例，100%方法覆盖
• Mock支持: 完善的依赖Mock机制
• 边界测试: 包含正常、异常、边界条件测试

潜在风险

技术风险

Redis依赖风险

• 风险描述: Redis服务不可用导致位置数据无法缓存
• 影响程度: 高 - 影响实时位置功能
• 缓解措施:
  • 实现Redis连接重试机制
  • 考虑Redis集群部署
  • 添加降级策略，临时使用数据库

内存使用风险

• 风险描述: 大量用户同时在线导致Redis内存占用过高
• 影响程度: 中 - 可能影响系统性能
• 缓解措施:
  • 合理设置数据过期时间
  • 监控内存使用情况
  • 实现数据清理策略

数据一致性风险

• 风险描述: Redis和数据库数据不一致
• 影响程度: 中 - 可能导致数据错误
• 缓解措施:
  • 实现数据同步检查机制
  • 添加数据修复功能
  • 定期进行数据一致性校验

业务风险

位置数据丢失

• 风险描述: 系统故障导致用户位置数据丢失
• 影响程度: 中 - 影响用户体验
• 缓解措施:
  • 实现位置数据备份机制
  • 添加数据恢复功能
  • 提供位置重置选项

会话状态错误

• 风险描述: 用户会话状态不正确，影响位置广播
• 影响程度: 中 - 影响功能正常使用
• 缓解措施:
  • 实现会话状态校验
  • 添加会话修复机制
  • 提供手动会话管理功能

运维风险

性能监控缺失

• 风险描述: 缺乏有效的性能监控，问题发现滞后
• 影响程度: 中 - 影响问题响应速度
• 缓解措施:
  • 集成APM监控工具
  • 设置关键指标告警
  • 建立性能基线

日志存储风险

• 风险描述: 大量日志导致存储空间不足
• 影响程度: 低 - 可能影响日志记录
• 缓解措施:
  • 实现日志轮转机制
  • 设置日志级别控制
  • 定期清理历史日志

安全风险

数据访问控制

• 风险描述: 位置数据可能被未授权访问
• 影响程度: 高 - 涉及用户隐私
• 缓解措施:
  • 实现严格的权限控制
  • 添加数据访问审计
  • 对敏感数据进行加密

注入攻击风险

• 风险描述: 恶意输入可能导致数据库注入攻击
• 影响程度: 高 - 可能导致数据泄露
• 缓解措施:
  • 使用参数化查询
  • 严格输入验证
  • 实现SQL注入检测

缓存投毒风险

• 风险描述: 恶意数据写入Redis缓存
• 影响程度: 中 - 可能影响数据准确性
• 缓解措施:
  • 实现数据校验机制
  • 添加缓存数据签名
  • 定期缓存数据校验

---

版本信息

• 当前版本: 1.0.6
• 最后更新: 2026-01-08
• 维护者: moyin
• 测试覆盖: 60个测试用例全部通过