Phase 79 — 共享资源层与依赖注入容器设计

版本: v4.0.0-alpha 创建日期: 2026-03-10 状态: ✅ 已实现

---

一、模块概述

Phase 79 构建统一的共享资源层，包括依赖注入容器（ServiceContainer）、共享缓存管理器（SharedCacheManager）、跨模块事件总线（EventBus）和资源池管理器（ResourcePool），消除模块间的硬编码依赖和重复资源分配。

1.1 核心目标

1. 依赖注入: ServiceContainer实现IoC模式，支持单例/瞬态生命周期和循环依赖检测
2. 共享缓存: LRU + TTL双策略缓存，支持命名空间隔离和统计监控
3. 事件总线: 跨模块发布/订阅通信，支持事件历史回放和通配符订阅
4. 资源池化: 定时器统一管理、连接池复用，避免资源泄漏

1.2 技术架构

┌──────────────────────────────────────────────────────┐
│             Shared Resource Layer                      │
│                                                        │
│  ┌─────────────────────┐  ┌─────────────────────────┐ │
│  │  ServiceContainer   │  │  SharedCacheManager     │ │
│  │  DI容器+生命周期     │  │  LRU+TTL+命名空间       │ │
│  │  循环依赖检测        │  │  统计+淘汰策略          │ │
│  └─────────────────────┘  └─────────────────────────┘ │
│  ┌─────────────────────┐  ┌─────────────────────────┐ │
│  │  EventBus           │  │  ResourcePool           │ │
│  │  发布/订阅+通配符    │  │  定时器管理+连接池      │ │
│  │  事件历史+回放       │  │  资源监控+自动回收      │ │
│  └─────────────────────┘  └─────────────────────────┘ │
│  ┌──────────────────────────────────────────────────┐  │
│  │            Core IPC (4 handlers)                  │  │
│  └──────────────────────────────────────────────────┘  │
└──────────────────────────────────────────────────────┘

---

二、核心模块设计

2.1 ServiceContainer (shared/service-container.js)

依赖注入容器，管理服务注册、解析和生命周期。

生命周期类型:

• SINGLETON — 全局唯一实例，首次解析时创建
• TRANSIENT — 每次解析创建新实例
• SCOPED — 作用域内共享实例

核心方法:

• register(name, factory, { lifecycle, dependencies }) — 注册服务工厂函数
• resolve(name) — 解析服务（自动注入依赖，检测循环依赖）
• registerInstance(name, instance) — 直接注册已有实例（单例）
• has(name) — 检查服务是否已注册
• unregister(name) — 注销服务并清理缓存实例
• getRegisteredServices() — 获取所有已注册服务名称和元数据
• createScope() — 创建子作用域容器
• dispose() — 销毁容器，清理所有单例实例
• getHealthStatus() — 获取容器健康状态（注册数、解析数、错误数）

2.2 SharedCacheManager (shared/shared-cache.js)

支持命名空间的LRU + TTL混合缓存。

核心方法:

• get(namespace, key) — 获取缓存值（自动检查TTL过期）
• set(namespace, key, value, { ttl, priority }) — 设置缓存值
• delete(namespace, key) — 删除缓存条目
• clearNamespace(namespace) — 清空指定命名空间
• clearAll() — 清空所有缓存
• getStats(namespace?) — 获取缓存统计（命中率、大小、淘汰数）
• setMaxSize(namespace, maxSize) — 设置命名空间最大容量
• getNamespaces() — 列出所有命名空间

2.3 EventBus (shared/event-bus.js)

跨模块事件发布/订阅系统。

核心方法:

• on(event, handler) — 订阅事件（支持通配符 module:*）
• off(event, handler) — 取消订阅
• emit(event, data) — 发布事件（同步通知所有订阅者）
• once(event, handler) — 一次性订阅（触发后自动移除）
• getHistory(event?, limit?) — 获取事件历史记录
• replay(event, fromTimestamp) — 重放指定时间后的事件
• getStats() — 获取事件总线统计（事件总数、订阅者数、历史大小）
• clearHistory() — 清空事件历史
• getSubscribers(event) — 获取指定事件的订阅者列表

2.4 ResourcePool (shared/resource-pool.js)

统一资源池管理，避免定时器泄漏和连接浪费。

核心方法:

• createTimer(name, callback, intervalMs, { type }) — 创建托管定时器（interval/timeout）
• clearTimer(name) — 清除指定定时器
• clearAllTimers() — 清除所有托管定时器
• acquireConnection(poolName) — 从连接池获取连接
• releaseConnection(poolName, connection) — 归还连接到池
• createPool(name, { factory, maxSize, idleTimeoutMs }) — 创建连接池
• getResourceUsage() — 获取资源使用报告（定时器数、连接池状态）
• dispose() — 销毁所有资源池和定时器

---

三、核心文件

文件	说明
src/main/shared/service-container.js	DI容器（注册、解析、循环依赖检测）
src/main/shared/shared-cache.js	LRU+TTL共享缓存（命名空间隔离）
src/main/shared/event-bus.js	跨模块事件总线（发布/订阅+历史回放）
src/main/shared/resource-pool.js	资源池管理（定时器+连接池）
src/main/shared/core-ipc.js	共享资源层IPC handler注册

---

四、IPC Handlers

Channel	说明
core:cache-stats	获取共享缓存统计（各命名空间命中率、大小、淘汰数）
core:event-bus-stats	获取事件总线统计（事件总数、活跃订阅者、历史大小）
core:service-health	获取服务容器健康状态（已注册服务数、解析次数、错误）
core:resource-usage	获取资源使用报告（活跃定时器数、连接池状态、内存占用）

---

五、数据库表

本Phase不引入新数据库表。所有共享资源状态均为运行时内存数据，通过IPC接口暴露查询。

---

六、测试覆盖

测试文件	测试数量	状态
src/main/shared/__tests__/service-container.test.js	24	✅ 通过
src/main/shared/__tests__/shared-cache.test.js	22	✅ 通过
src/main/shared/__tests__/event-bus.test.js	20	✅ 通过
src/main/shared/__tests__/resource-pool.test.js	19	✅ 通过
合计	85	✅ 全部通过

测试要点

• ServiceContainer循环依赖检测（A→B→C→A抛出异常）
• 单例/瞬态/作用域生命周期隔离验证
• LRU淘汰策略和TTL过期清理
• 命名空间隔离（不同命名空间同名key互不影响）
• EventBus通配符匹配和事件历史回放
• once订阅的自动移除验证
• ResourcePool定时器泄漏检测（dispose后无残留）
• 连接池最大连接数限制和空闲回收

---

七、前端集成

Pinia Store

• sharedResource.ts — 缓存统计、事件总线状态、服务健康、资源使用

Vue Pages

• SharedResourceDashboard.vue — 共享资源监控面板（缓存命中率图表、事件流、服务拓扑）

Routes

• /admin/shared-resources — 共享资源管理

---

八、配置选项

sharedResource: {
  enabled: true,
  cache: {
    defaultMaxSize: 1000,             // 默认命名空间最大条目数
    defaultTtlMs: 300000,             // 默认TTL（5分钟）
    evictionPolicy: 'lru',            // 淘汰策略: lru | lfu
  },
  eventBus: {
    historyEnabled: true,
    maxHistorySize: 10000,            // 最大历史记录数
    wildcardEnabled: true,            // 是否启用通配符订阅
  },
  resourcePool: {
    maxTimers: 200,                   // 最大托管定时器数
    defaultPoolSize: 10,              // 默认连接池大小
    idleTimeoutMs: 60000,             // 连接空闲超时
  },
}