@nimbus2d/core 0.0.1

package/src/utils/MemoryChecker.js

@@ -0,0 +1,374 @@
+// ============================================================================
+// Nimbus2D - MemoryChecker 内存泄漏检测工具
+// ----------------------------------------------------------------------------
+// 职责：
+//   开发/调试模式下的内存泄漏检测工具。基于 WeakRef + FinalizationRegistry
+//   实现无侵入追踪，帮助开发者发现对象未释放、对象池使用率异常等问题。
+//
+// 设计决策：
+//   - 不继承 Subsystem：MemoryChecker 是工具类，不参与 Lifecycle 调度
+//   - WeakRef + FinalizationRegistry：无侵入追踪，不影响对象生命周期
+//   - unregisterToken 使用独立空对象：避免以 obj 自身作为 token 导致
+//     FinalizationRegistry 持有 obj 的强引用，阻止 GC 回收
+//   - 开发模式自动挂钩 PoolManager/AssetManager，生产模式不挂钩
+//   - 自动检测通过 setInterval 定期执行，广播 memory:leak:suspected 事件
+//   - destroy() 时清理所有定时器和引用
+//
+// 文件位置：
+//   src/utils/MemoryChecker.js
+// ============================================================================
+
+class MemoryChecker {
+  // --------------------------------------------------------------------------
+  // 构造函数
+  // --------------------------------------------------------------------------
+
+  /**
+   * 构造函数
+   * @param {import('../core/EventBus/EventBus.js').EventBus} eventBus - 全局事件总线
+   * @param {import('../core/ConfigSystem/ConfigSystem.js').ConfigSystem} config - 配置系统
+   * @param {import('../core/Logger/Logger.js').Logger} logger - 日志系统
+   */
+  constructor(eventBus, config, logger) {
+    /** @type {import('../core/EventBus/EventBus.js').EventBus} 全局事件总线 */
+    this._eventBus = eventBus
+
+    /** @type {import('../core/ConfigSystem/ConfigSystem.js').ConfigSystem} 配置系统 */
+    this._config = config
+
+    /** @type {import('../core/Logger/Logger.js').Logger} 日志系统 */
+    this._logger = logger
+
+    /** @type {boolean} 是否已销毁 */
+    this._isDestroyed = false
+
+    // --- 手动追踪 ---
+    /** @type {Map<string, { total: number, alive: number, collected: number, refs: Map<WeakRef, { timestamp: number, unregisterToken: object }> }>} 追踪记录（label → 统计条目） */
+    this._tracked = new Map()
+
+    /** @type {FinalizationRegistry<string>} GC 回调注册表（回调参数为 label） */
+    this._finalizationRegistry = new FinalizationRegistry((label) => {
+      this._onObjectCollected(label)
+    })
+
+    // --- 自动挂钩 ---
+    /** @type {import('../core/PoolManager/PoolManager.js').PoolManager|null} 挂钩的 PoolManager */
+    this._poolManagerHooked = null
+
+    /** @type {import('../core/AssetManager/AssetManager.js').AssetManager|null} 挂钩的 AssetManager */
+    this._assetManagerHooked = null
+
+    /** @type {ReturnType<typeof setInterval>|null} 自动检测定时器 ID */
+    this._autoCheckTimer = null
+  }
+
+  // --------------------------------------------------------------------------
+  // 手动追踪
+  // --------------------------------------------------------------------------
+
+  /**
+   * 手动追踪对象
+   * 使用 WeakRef 持有对象引用，不阻止对象被 GC 回收。
+   * 当对象被 GC 回收时，FinalizationRegistry 通知 _onObjectCollected。
+   *
+   * @param {Object} obj - 要追踪的对象（必须是对象类型）
+   * @param {string} label - 追踪标签（用于分组统计，如 'sprite'、'collider'）
+   * @returns {Function} - 取消追踪函数（调用后移除追踪记录）
+   */
+  track(obj, label) {
+    // 已销毁时忽略
+    if (this._isDestroyed) return () => {}
+
+    // 参数校验：只能追踪对象类型
+    if (!obj || typeof obj !== 'object') {
+      this._logger.warn('MemoryChecker.track', '只能追踪对象类型')
+      return () => {}
+    }
+
+    // 参数校验：标签必须是非空字符串
+    if (!label || typeof label !== 'string') {
+      this._logger.warn('MemoryChecker.track', '标签必须是非空字符串')
+      return () => {}
+    }
+
+    // 获取或创建追踪条目
+    if (!this._tracked.has(label)) {
+      this._tracked.set(label, { total: 0, alive: 0, collected: 0, refs: new Map() })
+    }
+    const entry = this._tracked.get(label)
+
+    // 创建 WeakRef 引用（不阻止对象被 GC 回收）
+    const weakRef = new WeakRef(obj)
+    const timestamp = Date.now()
+
+    // 使用独立的 unregister token 对象，避免对目标对象产生强引用
+    // 注意：若以 obj 作为 unregister token，FinalizationRegistry 会持有 obj 的强引用，
+    // 导致 obj 永远无法被 GC 回收，完全破坏 WeakRef 追踪机制
+    const unregisterToken = {}
+
+    entry.refs.set(weakRef, { timestamp, unregisterToken })
+    entry.total++
+    entry.alive++
+
+    // 注册到 FinalizationRegistry（unregisterToken 为独立对象，不阻止 obj 被 GC）
+    this._finalizationRegistry.register(obj, label, unregisterToken)
+
+    // 返回取消追踪函数
+    return () => {
+      if (this._isDestroyed) return
+      if (!this._tracked.has(label)) return
+
+      const currentEntry = this._tracked.get(label)
+      if (currentEntry.refs.has(weakRef)) {
+        currentEntry.refs.delete(weakRef)
+        currentEntry.total--
+
+        // 仅在对象仍然存活时递减 alive（若已被 GC 回收，_onObjectCollected 已递减）
+        if (weakRef.deref() !== undefined) {
+          currentEntry.alive--
+        }
+
+        // 从 FinalizationRegistry 注销（避免回调对已取消追踪的对象触发）
+        this._finalizationRegistry.unregister(unregisterToken)
+      }
+    }
+  }
+
+  // --------------------------------------------------------------------------
+  // GC 回调
+  // --------------------------------------------------------------------------
+
+  /**
+   * 对象被 GC 回收时的回调（由 FinalizationRegistry 触发）
+   * @param {string} label - 追踪标签
+   * @private
+   */
+  _onObjectCollected(label) {
+    // 已销毁时忽略（destroy() 会清理 _tracked，之后 FinalizationRegistry 回调安全忽略）
+    if (this._isDestroyed) return
+    const entry = this._tracked.get(label)
+    if (entry) {
+      entry.alive--
+      entry.collected++
+    }
+  }
+
+  // --------------------------------------------------------------------------
+  // 报告
+  // --------------------------------------------------------------------------
+
+  /**
+   * 获取内存追踪报告
+   * 包含手动追踪统计、PoolManager 统计（若已挂钩）、AssetManager 统计（若已挂钩）
+   *
+   * @returns {{
+   *   timestamp: number,
+   *   manual: { total: number, alive: number, collected: number, byLabel: Object },
+   *   poolManager: Object|null,
+   *   assetManager: Object|null
+   * }}
+   */
+  getReport() {
+    const report = {
+      timestamp: Date.now(),
+      manual: { total: 0, alive: 0, collected: 0, byLabel: {} },
+      poolManager: null,
+      assetManager: null
+    }
+
+    // 手动追踪统计
+    for (const [label, entry] of this._tracked) {
+      // 清理已失效的 WeakRef（deref() 返回 undefined 表示对象已被 GC 回收）
+      for (const weakRef of entry.refs.keys()) {
+        if (weakRef.deref() === undefined) {
+          // 移除失效的 WeakRef 引用，但不调整 alive/collected 计数
+          // （alive 已由 _onObjectCollected 递减，collected 已递增）
+          entry.refs.delete(weakRef)
+        }
+      }
+
+      report.manual.total += entry.total
+      report.manual.alive += entry.alive
+      report.manual.collected += entry.collected
+      report.manual.byLabel[label] = {
+        total: entry.total,
+        alive: entry.alive,
+        collected: entry.collected
+      }
+    }
+
+    // PoolManager 统计
+    if (this._poolManagerHooked && !this._poolManagerHooked.isDestroyed) {
+      const poolStats = this._poolManagerHooked.getStats()
+      report.poolManager = { pools: poolStats.pools }
+    }
+
+    // AssetManager 统计
+    if (this._assetManagerHooked && !this._assetManagerHooked.isDestroyed) {
+      report.assetManager = this._getAssetManagerStats()
+    }
+
+    return report
+  }
+
+  // --------------------------------------------------------------------------
+  // 自动检测
+  // --------------------------------------------------------------------------
+
+  /**
+   * 启用自动检测
+   * 定期检查追踪统计，发现潜在泄漏时通过 Logger 警告和 EventBus 事件通知
+   *
+   * @param {number} [interval=5000] - 检测间隔（毫秒）
+   * @param {Object} [options={}] - 检测选项
+   * @param {number} [options.leakThreshold=100] - 泄漏疑似阈值（存活对象数超过此值且无任何回收时报告）
+   */
+  enableAutoCheck(interval = 5000, options = {}) {
+    // 已销毁时忽略
+    if (this._isDestroyed) return
+
+    // 已有定时器时忽略（避免重复注册）
+    if (this._autoCheckTimer) return
+
+    const leakThreshold = options.leakThreshold ?? 100
+
+    this._autoCheckTimer = setInterval(() => {
+      const report = this.getReport()
+
+      // 检查手动追踪的泄漏：存活对象数 > leakThreshold 且无任何被回收的记录
+      for (const [label, stats] of Object.entries(report.manual.byLabel)) {
+        if (stats.alive > 0 && stats.collected === 0 && stats.alive > leakThreshold) {
+          this._logger.warn(
+            'MemoryChecker.autoCheck',
+            `检测到潜在泄漏: '${label}' 有 ${stats.alive} 个对象未释放`
+          )
+          this._eventBus.emit('memory:leak:suspected', {
+            label,
+            alive: stats.alive
+          })
+        }
+      }
+
+      // 检查 PoolManager 泄漏：对象池使用率超过 80%
+      if (report.poolManager) {
+        for (const [name, stats] of Object.entries(report.poolManager.pools)) {
+          if (stats.inUse > 0 && stats.inUse > stats.size * 0.8) {
+            this._logger.warn(
+              'MemoryChecker.autoCheck',
+              `对象池 '${name}' 使用率过高: ${stats.inUse}/${stats.size}`
+            )
+          }
+        }
+      }
+    }, interval)
+  }
+
+  /**
+   * 禁用自动检测
+   * 清除定时器，停止定期检测
+   */
+  disableAutoCheck() {
+    if (this._autoCheckTimer) {
+      clearInterval(this._autoCheckTimer)
+      this._autoCheckTimer = null
+    }
+  }
+
+  // --------------------------------------------------------------------------
+  // 挂钩管理器
+  // --------------------------------------------------------------------------
+
+  /**
+   * 挂钩 PoolManager
+   * 使 getReport() 包含对象池统计信息
+   * @param {import('../core/PoolManager/PoolManager.js').PoolManager} poolManager - PoolManager 实例
+   */
+  hookPoolManager(poolManager) {
+    if (this._isDestroyed) return
+    this._poolManagerHooked = poolManager
+    this._logger.info('MemoryChecker.hookPoolManager', '已挂钩 PoolManager')
+  }
+
+  /**
+   * 挂钩 AssetManager
+   * 使 getReport() 包含资源管理统计信息
+   * @param {import('../core/AssetManager/AssetManager.js').AssetManager} assetManager - AssetManager 实例
+   */
+  hookAssetManager(assetManager) {
+    if (this._isDestroyed) return
+    this._assetManagerHooked = assetManager
+    this._logger.info('MemoryChecker.hookAssetManager', '已挂钩 AssetManager')
+  }
+
+  // --------------------------------------------------------------------------
+  // 内部方法
+  // --------------------------------------------------------------------------
+
+  /**
+   * 获取 AssetManager 统计信息
+   * 若 AssetManager 有 getStats() 方法则调用，否则返回 null
+   * @returns {Object|null}
+   * @private
+   */
+  _getAssetManagerStats() {
+    if (!this._assetManagerHooked) return null
+    // AssetManager 内部统计通过 getStats() 获取
+    // 若 AssetManager 无 getStats()，则返回 null
+    if (typeof this._assetManagerHooked.getStats === 'function') {
+      return this._assetManagerHooked.getStats()
+    }
+    return null
+  }
+
+  // --------------------------------------------------------------------------
+  // 生命周期
+  // --------------------------------------------------------------------------
+
+  /**
+   * 销毁内存检测工具
+   * 清理所有追踪记录、定时器和挂钩引用。
+   * 遍历所有追踪条目，从 FinalizationRegistry 中注销未回收的对象，
+   * 防止 GC 回收时触发已销毁的回调（虽然有 _isDestroyed 检查，但注销更彻底）。
+   */
+  destroy() {
+    if (this._isDestroyed) return
+
+    // 停止自动检测
+    this.disableAutoCheck()
+
+    // 遍历所有追踪条目，从 FinalizationRegistry 中注销未回收的对象
+    // 防止 GC 回收时触发回调（虽然 _onObjectCollected 有 _isDestroyed 检查，但注销更彻底）
+    for (const entry of this._tracked.values()) {
+      for (const { unregisterToken } of entry.refs.values()) {
+        try {
+          this._finalizationRegistry.unregister(unregisterToken)
+        } catch (e) {
+          // 注销失败安全忽略（unregisterToken 可能已失效）
+        }
+      }
+    }
+
+    // 清理追踪记录
+    this._tracked.clear()
+
+    // 清理挂钩引用
+    this._poolManagerHooked = null
+    this._assetManagerHooked = null
+
+    // 清理核心引用
+    this._eventBus = null
+    this._config = null
+    this._logger = null
+
+    this._isDestroyed = true
+  }
+
+  // --------------------------------------------------------------------------
+  // Getter
+  // --------------------------------------------------------------------------
+
+  /** @type {boolean} 是否已销毁 */
+  get isDestroyed() { return this._isDestroyed }
+}
+
+export { MemoryChecker }

package/src/utils/Validator.js

@@ -0,0 +1,60 @@
+// ============================================================================
+// Nimbus2D - 参数校验辅助函数
+// ----------------------------------------------------------------------------
+// 职责：
+//   1. 提供类型检查辅助函数（isNonEmptyString/isPositiveNumber/isPositiveInteger）
+//   2. 提供开发模式参数校验函数（validateDev）
+//   3. 开发模式校验仅在 core.developmentMode 为 true 时生效，
+//      生产模式下跳过校验以获得最佳性能
+//
+// 使用方式：
+//   import { validateDev, isNonEmptyString } from '../../utils/Validator.js'
+//   validateDev(this._config, isNonEmptyString(name), 'name 必须是非空字符串', PoolError)
+// ============================================================================
+
+/**
+ * 检查是否为非空字符串
+ * @param {*} value - 待检查的值
+ * @returns {boolean}
+ */
+export function isNonEmptyString(value) {
+  return typeof value === 'string' && value.length > 0
+}
+
+/**
+ * 检查是否为正数
+ * @param {*} value - 待检查的值
+ * @returns {boolean}
+ */
+export function isPositiveNumber(value) {
+  return typeof value === 'number' && value > 0
+}
+
+/**
+ * 检查是否为正整数
+ * @param {*} value - 待检查的值
+ * @returns {boolean}
+ */
+export function isPositiveInteger(value) {
+  return Number.isInteger(value) && value > 0
+}
+
+/**
+ * 开发模式参数校验
+ * 仅在 core.developmentMode 为 true（默认）时执行校验，
+ * 生产模式下跳过校验以获得最佳性能
+ *
+ * @param {import('../core/ConfigSystem/ConfigSystem.js').ConfigSystem} config - 配置系统
+ * @param {boolean} condition - 校验条件（true 表示通过）
+ * @param {string} message - 校验失败时的错误消息
+ * @param {Function} ErrorClass - 校验失败时抛出的错误类
+ * @throws {Error} 开发模式下条件不满足时抛出指定错误
+ */
+export function validateDev(config, condition, message, ErrorClass) {
+  // 默认为开发模式（developmentMode 为 true 或未设置时执行校验）
+  if (config.get('core.developmentMode') !== false) {
+    if (!condition) {
+      throw new ErrorClass(message)
+    }
+  }
+}

package/src/utils/index.js

@@ -0,0 +1,84 @@
+// ============================================================================
+// Nimbus2D - 工具函数
+// ----------------------------------------------------------------------------
+// 通用工具函数集合
+// ============================================================================
+
+// 从 ConfigMerger 重导出 deepMerge，避免重复定义
+export { deepMerge } from '../core/ConfigSystem/ConfigMerger.js'
+
+// 参数校验辅助函数（三期新增）
+export { isNonEmptyString, isPositiveNumber, isPositiveInteger, validateDev } from './Validator.js'
+
+// 内存泄漏检测工具（三期新增）
+export { MemoryChecker } from './MemoryChecker.js'
+
+/**
+ * 生成唯一 ID
+ * @param {string} [prefix=''] - 前缀
+ * @returns {string} 唯一 ID
+ */
+export function generateId(prefix = '') {
+  const timestamp = Date.now().toString(36)
+  const random = Math.random().toString(36).substring(2, 8)
+  return prefix ? `${prefix}_${timestamp}_${random}` : `${timestamp}_${random}`
+}
+
+/**
+ * 防抖函数
+ * @param {Function} fn - 要防抖的函数
+ * @param {number} delay - 延迟时间（毫秒）
+ * @returns {Function} 防抖后的函数
+ */
+export function debounce(fn, delay) {
+  let timer = null
+  return function (...args) {
+    if (timer) clearTimeout(timer)
+    timer = setTimeout(() => {
+      fn.apply(this, args)
+      timer = null
+    }, delay)
+  }
+}
+
+/**
+ * 节流函数
+ * @param {Function} fn - 要节流的函数
+ * @param {number} interval - 间隔时间（毫秒）
+ * @returns {Function} 节流后的函数
+ */
+export function throttle(fn, interval) {
+  let lastTime = 0
+  return function (...args) {
+    const now = Date.now()
+    if (now - lastTime >= interval) {
+      fn.apply(this, args)
+      lastTime = now
+    }
+  }
+}
+
+/**
+ * 安全的 JSON 解析
+ * @param {string} str - JSON 字符串
+ * @param {*} defaultValue - 解析失败时的默认值
+ * @returns {*} 解析结果或默认值
+ */
+export function safeJsonParse(str, defaultValue = null) {
+  try {
+    return JSON.parse(str)
+  } catch {
+    return defaultValue
+  }
+}
+
+/**
+ * 限制数值范围
+ * @param {number} value - 输入值
+ * @param {number} min - 最小值
+ * @param {number} max - 最大值
+ * @returns {number} 限制后的值
+ */
+export function clamp(value, min, max) {
+  return Math.min(Math.max(value, min), max)
+}