# 依赖管理

<cite>
**本文引用的文件**
- [IocContainer.cs](file://GFramework.Core/ioc/IocContainer.cs)
- [IIocContainer.cs](file://GFramework.Core.Abstractions/ioc/IIocContainer.cs)
- [Architecture.cs](file://GFramework.Core/architecture/Architecture.cs)
- [ArchitectureServices.cs](file://GFramework.Core/architecture/ArchitectureServices.cs)
- [AbstractSystem.cs](file://GFramework.Core/system/AbstractSystem.cs)
- [ContextAwareBase.cs](file://GFramework.Core/rule/ContextAwareBase.cs)
- [IContextAware.cs](file://GFramework.Core.Abstractions/rule/IContextAware.cs)
- [ISystem.cs](file://GFramework.Core.Abstractions/system/ISystem.cs)
- [AbstractModel.cs](file://GFramework.Core/model/AbstractModel.cs)
- [ConsoleLoggerFactoryProvider.cs](file://GFramework.Core/logging/ConsoleLoggerFactoryProvider.cs)
- [IocContainerTests.cs](file://GFramework.Core.Tests/ioc/IocContainerTests.cs)
- [TestSystem.cs](file://GFramework.Core.Tests/system/TestSystem.cs)
- [architecture-patterns.md](file://docs/best-practices/architecture-patterns.md)
- [rule README.md](file://GFramework.Core/rule/README.md)
- [system README.md](file://GFramework.Core/system/README.md)
</cite>

## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构总览](#架构总览)
5. [详细组件分析](#详细组件分析)
6. [依赖分析](#依赖分析)
7. [性能考量](#性能考量)
8. [故障排查指南](#故障排查指南)
9. [结论](#结论)
10. [附录](#附录)

## 简介
本文件面向GFramework的依赖管理最佳实践，围绕“构造函数注入”“接口隔离”“依赖倒置”三大原则，结合框架中的IoC容器、架构服务、系统与模型基类、上下文感知机制，给出可落地的实现范式与测试策略。文档同时覆盖常见陷阱与规避方案，帮助团队在复杂游戏架构中建立稳定、可测试、可演进的依赖体系。

## 项目结构
GFramework采用分层与职责分离的组织方式，核心依赖管理相关模块分布如下：
- 核心容器与接口：GFramework.Core/ioc 与 GFramework.Core.Abstractions/ioc
- 架构与服务：GFramework.Core/architecture
- 系统与模型基类：GFramework.Core/system、GFramework.Core/model
- 上下文感知与规则：GFramework.Core/rule
- 日志与测试：GFramework.Core/logging、GFramework.Core.Tests

```mermaid
graph TB
subgraph "核心容器与接口"
IIoc["IIocContainer 接口"]
Ioc["IocContainer 实现"]
end
subgraph "架构与服务"
Arch["Architecture 架构基类"]
Svc["ArchitectureServices 架构服务"]
end
subgraph "系统与模型"
Sys["AbstractSystem 系统基类"]
Mod["AbstractModel 模型基类"]
end
subgraph "上下文感知"
Ctx["ContextAwareBase 基类"]
ICtx["IContextAware 接口"]
end
subgraph "日志与测试"
LogProv["ConsoleLoggerFactoryProvider"]
Tests["IocContainerTests 等测试"]
end
IIoc --> Ioc
Svc --> Ioc
Arch --> Svc
Sys --> ICtx
Mod --> ICtx
Ctx --> ICtx
Ioc --> LogProv
Tests --> Ioc
```

图表来源
- [IIocContainer.cs](file://GFramework.Core.Abstractions/ioc/IIocContainer.cs#L1-L116)
- [IocContainer.cs](file://GFramework.Core/ioc/IocContainer.cs#L1-L373)
- [ArchitectureServices.cs](file://GFramework.Core/architecture/ArchitectureServices.cs#L1-L106)
- [Architecture.cs](file://GFramework.Core/architecture/Architecture.cs#L1-L569)
- [AbstractSystem.cs](file://GFramework.Core/system/AbstractSystem.cs#L1-L62)
- [AbstractModel.cs](file://GFramework.Core/model/AbstractModel.cs#L1-L34)
- [ContextAwareBase.cs](file://GFramework.Core/rule/ContextAwareBase.cs#L1-L43)
- [IContextAware.cs](file://GFramework.Core.Abstractions/rule/IContextAware.cs#L1-L21)
- [ConsoleLoggerFactoryProvider.cs](file://GFramework.Core/logging/ConsoleLoggerFactoryProvider.cs#L1-L24)
- [IocContainerTests.cs](file://GFramework.Core.Tests/ioc/IocContainerTests.cs#L1-L346)

章节来源
- [IIocContainer.cs](file://GFramework.Core.Abstractions/ioc/IIocContainer.cs#L1-L116)
- [IocContainer.cs](file://GFramework.Core/ioc/IocContainer.cs#L1-L373)
- [ArchitectureServices.cs](file://GFramework.Core/architecture/ArchitectureServices.cs#L1-L106)
- [Architecture.cs](file://GFramework.Core/architecture/Architecture.cs#L1-L569)
- [AbstractSystem.cs](file://GFramework.Core/system/AbstractSystem.cs#L1-L62)
- [AbstractModel.cs](file://GFramework.Core/model/AbstractModel.cs#L1-L34)
- [ContextAwareBase.cs](file://GFramework.Core/rule/ContextAwareBase.cs#L1-L43)
- [IContextAware.cs](file://GFramework.Core.Abstractions/rule/IContextAware.cs#L1-L21)
- [ConsoleLoggerFactoryProvider.cs](file://GFramework.Core/logging/ConsoleLoggerFactoryProvider.cs#L1-L24)
- [IocContainerTests.cs](file://GFramework.Core.Tests/ioc/IocContainerTests.cs#L1-L346)

## 核心组件
- 依赖注入容器（IIocContainer/IocContainer）
  - 提供注册（单例、多样性、系统）、解析（Get/GetRequired/GetAll/GetAllSorted）、冻结保护、包含性检查与清空等能力。
  - 支持线程安全的读写锁与冻结状态，防止初始化后误注册。
- 架构服务（ArchitectureServices）
  - 聚合容器、事件总线、命令/查询总线，统一对外暴露。
  - 在SetContext时同步传递上下文给容器与各总线。
- 架构基类（Architecture）
  - 通过Services.Container访问IocContainer，统一注册系统/模型/工具，维护生命周期队列与阶段流转。
  - 初始化完成后冻结容器，保证运行期依赖解析的确定性。
- 系统与模型基类（AbstractSystem/AbstractModel）
  - 均继承ContextAwareBase，具备上下文感知能力，便于在OnInit/Init中按需获取依赖。
- 上下文感知（ContextAwareBase/IContextAware）
  - 为组件提供SetContext/GetContext能力，支持延迟绑定与默认回退。

章节来源
- [IIocContainer.cs](file://GFramework.Core.Abstractions/ioc/IIocContainer.cs#L1-L116)
- [IocContainer.cs](file://GFramework.Core/ioc/IocContainer.cs#L1-L373)
- [ArchitectureServices.cs](file://GFramework.Core/architecture/ArchitectureServices.cs#L1-L106)
- [Architecture.cs](file://GFramework.Core/architecture/Architecture.cs#L1-L569)
- [AbstractSystem.cs](file://GFramework.Core/system/AbstractSystem.cs#L1-L62)
- [AbstractModel.cs](file://GFramework.Core/model/AbstractModel.cs#L1-L34)
- [ContextAwareBase.cs](file://GFramework.Core/rule/ContextAwareBase.cs#L1-L43)
- [IContextAware.cs](file://GFramework.Core.Abstractions/rule/IContextAware.cs#L1-L21)

## 架构总览
下图展示了依赖注入在架构中的位置与交互路径：架构服务聚合容器与总线；架构基类在初始化阶段注册组件并冻结容器；系统/模型通过上下文感知获取依赖；日志工厂提供统一日志能力。

```mermaid
graph TB
Arch["Architecture 架构基类"]
Svc["ArchitectureServices 架构服务"]
Ctn["IocContainer 容器"]
EB["EventBus 事件总线"]
CB["CommandBus 命令总线"]
QB["QueryBus 查询总线"]
ACB["AsyncQueryBus 异步查询总线"]
Arch --> Svc
Svc --> Ctn
Svc --> EB
Svc --> CB
Svc --> QB
Svc --> ACB
Arch --> |"注册系统/模型/工具"| Ctn
Arch --> |"冻结容器"| Ctn
```

图表来源
- [Architecture.cs](file://GFramework.Core/architecture/Architecture.cs#L1-L569)
- [ArchitectureServices.cs](file://GFramework.Core/architecture/ArchitectureServices.cs#L1-L106)
- [IocContainer.cs](file://GFramework.Core/ioc/IocContainer.cs#L1-L373)

章节来源
- [Architecture.cs](file://GFramework.Core/architecture/Architecture.cs#L1-L569)
- [ArchitectureServices.cs](file://GFramework.Core/architecture/ArchitectureServices.cs#L1-L106)
- [IocContainer.cs](file://GFramework.Core/ioc/IocContainer.cs#L1-L373)

## 详细组件分析

### 依赖注入容器（IocContainer）
- 注册策略
  - RegisterSingleton：单例注册，防重复与冻结保护。
  - RegisterPlurality/Register：按具体类型与实现接口同时注册，便于接口解析。
  - RegisterSystem：专门注册系统实例，等价于RegisterPlurality。
- 解析策略
  - Get：返回首个匹配实例，适合具体类型。
  - GetRequired：要求唯一实例，否则抛出异常。
  - GetAll/GetAllSorted：返回全部实例，支持排序（系统调度场景）。
- 容器治理
  - Freeze：初始化完成后冻结，禁止后续注册。
  - Clear/Contains/ContainsInstance：容器清理与存在性检查。
- 线程安全
  - 使用ReaderWriterLockSlim实现读写锁，避免并发问题。

```mermaid
classDiagram
class IIocContainer {
+RegisterSingleton<T>(instance)
+RegisterPlurality(instance)
+RegisterSystem(system)
+Register<T>(instance)
+Register(type, instance)
+Get<T>()
+GetRequired<T>()
+GetAll<T>()
+GetAllSorted<T>(comparison)
+Contains<T>()
+ContainsInstance(instance)
+Clear()
+Freeze()
}
class IocContainer {
-ReaderWriterLockSlim _lock
-bool _frozen
-HashSet<object> _objects
-Dictionary<Type, HashSet<object>> _typeIndex
-ILogger _logger
+RegisterSingleton<T>(instance)
+RegisterPlurality(instance)
+RegisterSystem(system)
+Register<T>(instance)
+Register(type, instance)
+Get<T>()
+GetRequired<T>()
+GetAll<T>()
+GetAllSorted<T>(comparison)
+Contains<T>()
+ContainsInstance(instance)
+Clear()
+Freeze()
}
IIocContainer <|.. IocContainer
```

图表来源
- [IIocContainer.cs](file://GFramework.Core.Abstractions/ioc/IIocContainer.cs#L1-L116)
- [IocContainer.cs](file://GFramework.Core/ioc/IocContainer.cs#L1-L373)

章节来源
- [IIocContainer.cs](file://GFramework.Core.Abstractions/ioc/IIocContainer.cs#L1-L116)
- [IocContainer.cs](file://GFramework.Core/ioc/IocContainer.cs#L1-L373)

### 架构服务（ArchitectureServices）
- 职责
  - 组合并持有容器、事件总线、命令/查询总线。
  - 在构造时将核心服务注册到容器，供架构基类统一获取。
- 上下文传播
  - SetContext时将上下文传递给容器与各总线，确保解析与事件路由一致。

```mermaid
sequenceDiagram
participant S as "ArchitectureServices"
participant C as "IocContainer"
participant E as "EventBus"
participant Cmd as "CommandBus"
participant Q as "QueryBus"
participant AQ as "AsyncQueryBus"
S->>C : "new IocContainer()"
S->>E : "new EventBus()"
S->>Cmd : "new CommandBus()"
S->>Q : "new QueryBus()"
S->>AQ : "new AsyncQueryBus()"
S->>C : "RegisterPlurality(...)"
S->>C : "SetContext(context)"
S->>E : "SetContext(context)"
S->>Cmd : "SetContext(context)"
S->>Q : "SetContext(context)"
S->>AQ : "SetContext(context)"
```

图表来源
- [ArchitectureServices.cs](file://GFramework.Core/architecture/ArchitectureServices.cs#L1-L106)

章节来源
- [ArchitectureServices.cs](file://GFramework.Core/architecture/ArchitectureServices.cs#L1-L106)

### 架构基类（Architecture）与生命周期
- 模块/组件注册
  - InstallModule：注册模块并安装。
  - RegisterSystem/RegisterModel/RegisterUtility：注册系统/模型/工具，注入上下文并登记生命周期。
- 初始化流程
  - Initialize/InitializeAsync：设置日志工厂、环境、上下文，调用子类Init，随后按阶段初始化工具/模型/系统，最后冻结容器。
- 阶段与钩子
  - EnterPhase/NotifyPhase/NotifyPhaseAwareObjects：阶段转换与通知。
  - RegisterLifecycleHook：允许在Ready前注册生命周期钩子。

```mermaid
flowchart TD
Start(["开始 Initialize/InitializeAsync"]) --> Setup["设置日志工厂/环境<br/>初始化架构上下文"]
Setup --> CallUserInit["调用子类 Init()"]
CallUserInit --> InitComponents["按阶段初始化组件<br/>工具/模型/系统"]
InitComponents --> Freeze["冻结容器"]
Freeze --> Ready["进入 Ready 阶段"]
Ready --> End(["结束"])
```

图表来源
- [Architecture.cs](file://GFramework.Core/architecture/Architecture.cs#L1-L569)

章节来源
- [Architecture.cs](file://GFramework.Core/architecture/Architecture.cs#L1-L569)

### 系统与模型基类（AbstractSystem/AbstractModel）
- AbstractSystem
  - 提供Init/Destroy与架构阶段回调，内部通过ContextAwareBase获取日志工厂。
- AbstractModel
  - 实现IInitializable.Init，委托子类OnInit；支持架构阶段回调。

```mermaid
classDiagram
class ISystem {
<<interface>>
}
class IContextAware {
<<interface>>
}
class IArchitecturePhaseAware {
<<interface>>
}
class ILifecycle {
<<interface>>
}
class ContextAwareBase {
-IArchitectureContext Context
+SetContext(context)
+GetContext()
#OnContextReady()
}
class AbstractSystem {
-ILogger _logger
+Init()
+Destroy()
+OnArchitecturePhase(phase)
#OnInit()
#OnDestroy()
}
class AbstractModel {
+Init()
+OnArchitecturePhase(phase)
#OnInit()
}
ISystem --> IContextAware
ISystem --> IArchitecturePhaseAware
ISystem --> ILifecycle
AbstractSystem --> ContextAwareBase
AbstractModel --> ContextAwareBase
```

图表来源
- [ISystem.cs](file://GFramework.Core.Abstractions/system/ISystem.cs#L1-L11)
- [ContextAwareBase.cs](file://GFramework.Core/rule/ContextAwareBase.cs#L1-L43)
- [AbstractSystem.cs](file://GFramework.Core/system/AbstractSystem.cs#L1-L62)
- [AbstractModel.cs](file://GFramework.Core/model/AbstractModel.cs#L1-L34)

章节来源
- [ISystem.cs](file://GFramework.Core.Abstractions/system/ISystem.cs#L1-L11)
- [ContextAwareBase.cs](file://GFramework.Core/rule/ContextAwareBase.cs#L1-L43)
- [AbstractSystem.cs](file://GFramework.Core/system/AbstractSystem.cs#L1-L62)
- [AbstractModel.cs](file://GFramework.Core/model/AbstractModel.cs#L1-L34)

### 构造函数注入与接口隔离的实际应用
- 构造函数注入
  - 在系统类中通过构造函数接收依赖，避免在OnInit中动态解析，提升可测试性与明确性。
  - 示例参考：[architecture-patterns.md](file://docs/best-practices/architecture-patterns.md#L468-L527)
- 接口隔离
  - 将职责拆分为小而专注的接口，通过接口组合实现能力拼装，降低耦合度。
  - 示例参考：[architecture-patterns.md](file://docs/best-practices/architecture-patterns.md#L529-L576)
- 依赖倒置
  - 高层模块（如系统）依赖抽象（接口），通过IoC容器注入具体实现，便于替换与测试。
  - 示例参考：[architecture-patterns.md](file://docs/best-practices/architecture-patterns.md#L186-L282)

章节来源
- [architecture-patterns.md](file://docs/best-practices/architecture-patterns.md#L186-L282)
- [architecture-patterns.md](file://docs/best-practices/architecture-patterns.md#L468-L527)
- [architecture-patterns.md](file://docs/best-practices/architecture-patterns.md#L529-L576)

### 在PlayerCombatSystem等组件中的依赖注入实践
- 依赖注入实现范式
  - 通过构造函数注入模型与服务接口，系统内仅持有抽象，不直接依赖具体实现。
  - 在系统OnInit中注册事件监听，处理业务逻辑。
- 与架构集成
  - 系统通过ContextAwareBase获取日志工厂；通过架构上下文解析模型/系统/事件总线等。
- 参考示例
  - 系统职责划分与事件驱动：[system README.md](file://GFramework.Core/system/README.md#L434-L490)
  - 控制器与系统协作示例（含上下文获取与事件发送）：[rule README.md](file://GFramework.Core/rule/README.md#L166-L267)

章节来源
- [system README.md](file://GFramework.Core/system/README.md#L434-L490)
- [rule README.md](file://GFramework.Core/rule/README.md#L166-L267)

## 依赖分析
- 组件耦合与内聚
  - IocContainer与ArchitectureServices高内聚，共同支撑架构生命周期与依赖解析。
  - Architecture通过Services间接依赖容器，降低外部直接耦合。
- 直接与间接依赖
  - AbstractSystem/AbstractModel依赖ContextAwareBase，间接获得上下文能力。
  - ArchitectureServices向容器注册核心总线，形成间接依赖链。
- 循环依赖规避
  - 通过冻结容器与阶段化初始化，避免运行期循环依赖导致的解析死锁。
  - 通过接口隔离与依赖倒置，减少实现间的直接耦合。

```mermaid
graph LR
Arch["Architecture"] --> Svc["ArchitectureServices"]
Svc --> Ctn["IocContainer"]
Sys["AbstractSystem"] --> Ctx["ContextAwareBase"]
Mod["AbstractModel"] --> Ctx
Arch --> Sys
Arch --> Mod
Svc --> EB["EventBus"]
Svc --> CB["CommandBus"]
Svc --> QB["QueryBus"]
Svc --> ACB["AsyncQueryBus"]
```

图表来源
- [Architecture.cs](file://GFramework.Core/architecture/Architecture.cs#L1-L569)
- [ArchitectureServices.cs](file://GFramework.Core/architecture/ArchitectureServices.cs#L1-L106)
- [IocContainer.cs](file://GFramework.Core/ioc/IocContainer.cs#L1-L373)
- [AbstractSystem.cs](file://GFramework.Core/system/AbstractSystem.cs#L1-L62)
- [AbstractModel.cs](file://GFramework.Core/model/AbstractModel.cs#L1-L34)
- [ContextAwareBase.cs](file://GFramework.Core/rule/ContextAwareBase.cs#L1-L43)

章节来源
- [Architecture.cs](file://GFramework.Core/architecture/Architecture.cs#L1-L569)
- [ArchitectureServices.cs](file://GFramework.Core/architecture/ArchitectureServices.cs#L1-L106)
- [IocContainer.cs](file://GFramework.Core/ioc/IocContainer.cs#L1-L373)
- [AbstractSystem.cs](file://GFramework.Core/system/AbstractSystem.cs#L1-L62)
- [AbstractModel.cs](file://GFramework.Core/model/AbstractModel.cs#L1-L34)
- [ContextAwareBase.cs](file://GFramework.Core/rule/ContextAwareBase.cs#L1-L43)

## 性能考量
- 解析成本
  - Get/GetAll基于类型索引与快照，读取为O(1)查找+拷贝，建议在初始化阶段缓存常用依赖引用，避免每帧重复解析。
- 线程安全
  - 读写锁保障并发安全，但频繁写入（注册）会带来开销；尽量在初始化阶段完成注册，运行期避免动态注册。
- 冻结容器
  - 初始化完成后冻结容器，避免运行期变更带来的额外校验与潜在竞争。

章节来源
- [IocContainer.cs](file://GFramework.Core/ioc/IocContainer.cs#L1-L373)
- [Architecture.cs](file://GFramework.Core/architecture/Architecture.cs#L1-L569)

## 故障排查指南
- 常见错误与定位
  - 注册单例重复：抛出InvalidOperationException，检查是否重复注册同一类型。
  - 冻结后注册：抛出InvalidOperationException，确认是否在初始化后仍尝试注册。
  - GetRequired无实例或多实例：抛出InvalidOperationException，检查注册数量与类型映射。
  - 容器为空：Get返回null，GetAll返回空列表，确认Register/注册类型映射是否正确。
- 日志与诊断
  - 容器内部使用日志工厂输出调试信息，可通过ConsoleLoggerFactoryProvider设置最小日志级别。
- 测试策略
  - 使用IocContainerTests覆盖注册、解析、冻结、包含性等核心行为。
  - 使用TestSystem验证系统生命周期与上下文传递。

```mermaid
sequenceDiagram
participant T as "测试用例"
participant C as "IocContainer"
participant L as "日志工厂"
T->>C : "Register/Get/GetAll/Freeze"
C->>L : "Debug/Info/Error"
T-->>T : "断言结果与异常"
```

图表来源
- [IocContainerTests.cs](file://GFramework.Core.Tests/ioc/IocContainerTests.cs#L1-L346)
- [ConsoleLoggerFactoryProvider.cs](file://GFramework.Core/logging/ConsoleLoggerFactoryProvider.cs#L1-L24)

章节来源
- [IocContainerTests.cs](file://GFramework.Core.Tests/ioc/IocContainerTests.cs#L1-L346)
- [ConsoleLoggerFactoryProvider.cs](file://GFramework.Core/logging/ConsoleLoggerFactoryProvider.cs#L1-L24)

## 结论
GFramework通过清晰的接口边界、可冻结的IoC容器与阶段化的架构初始化，为依赖管理提供了坚实基础。配合构造函数注入、接口隔离与依赖倒置原则，团队可以在保持系统解耦的同时，显著提升可测试性与可维护性。建议在实际开发中：
- 优先使用构造函数注入与接口解析；
- 严格遵守接口隔离，按职责拆分接口；
- 在初始化阶段完成依赖注册，运行期避免动态变更；
- 通过测试用例覆盖容器行为与系统生命周期。

## 附录
- 术语
  - 构造函数注入：通过构造函数显式传入依赖，提升可测试性与明确性。
  - 接口隔离：将职责拆分为小而专注的接口，避免“胖接口”。
  - 依赖倒置：高层模块依赖抽象而非具体实现，通过容器注入替换。
- 参考示例
  - 构造函数注入与依赖倒置示例：[architecture-patterns.md](file://docs/best-practices/architecture-patterns.md#L186-L282)
  - 接口隔离示例：[architecture-patterns.md](file://docs/best-practices/architecture-patterns.md#L529-L576)
  - 系统职责与事件驱动示例：[system README.md](file://GFramework.Core/system/README.md#L434-L490)