gewuyou/GFramework
1
0
Fork 0
mirror of https://github.com/GeWuYou/GFramework.git synced 2026-03-26 06:16:43 +08:00
Code Issues Packages Projects Releases Wiki Activity
GFramework/.qoder/repowiki/zh/content/教程和指南/高级模式教程/领域驱动设计/领域服务.md
GeWuYou a79f02c987 docs(api): 添加 Core API 参考文档与事件系统接口文档 
- 新增 Core API 参考文档，涵盖架构与模块、数据模型与系统、命令与查询等核心组件
- 添加事件系统接口详细文档，包括 IEvent、IEventBus、IUnRegister 等接口说明
- 提供完整的 API 使用示例路径、最佳实践与性能建议
- 包含架构图、依赖关系图与故障排查指南
- 添加测试用例参考与扩展方法说明
- [skip ci]
2026-01-21 23:45:10 +08:00

20 KiB
Raw Blame History

领域服务

**本文引用的文件** - [AbstractSystem.cs](file://GFramework.Core/system/AbstractSystem.cs) - [ISystem.cs](file://GFramework.Core.Abstractions/system/ISystem.cs) - [AbstractContextUtility.cs](file://GFramework.Core/utility/AbstractContextUtility.cs) - [IContextUtility.cs](file://GFramework.Core.Abstractions/utility/IContextUtility.cs) - [ContextAwareBase.cs](file://GFramework.Core/rule/ContextAwareBase.cs) - [IocContainer.cs](file://GFramework.Core/ioc/IocContainer.cs) - [GameContext.cs](file://GFramework.Core/architecture/GameContext.cs) - [ArchitectureContext.cs](file://GFramework.Core/architecture/ArchitectureContext.cs) - [README.md（System 使用说明）](file://GFramework.Core/system/README.md) - [README.md（Utility 使用说明）](file://GFramework.Core/utility/README.md) - [AbstractModule.cs](file://GFramework.Game/architecture/AbstractModule.cs) - [IArchitecture.cs](file://GFramework.Core.Abstractions/architecture/IArchitecture.cs) - [README.md（源生成器示例）](file://GFramework.SourceGenerators/README.md) - [AbstractContextUtilityTests.cs](file://GFramework.Core.Tests/utility/AbstractContextUtilityTests.cs)

目录

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

简介

本篇文档围绕 GFramework 中“领域服务”的概念展开，结合现有代码库中的 System 与 Utility 层，系统阐述领域服务的定义、职责与设计原则，并明确其与 System、Utility 的边界与协作方式。文档同时给出在 GFramework 中实现领域服务的完整路径：从抽象基类、上下文感知、依赖注入到服务注册与跨服务协作，最后提供战斗计算、物品合成、AI 决策等典型游戏场景的设计与实现思路。

项目结构

GFramework 的核心层由以下关键模块组成：

  • system：业务逻辑层，负责复杂业务流程与跨聚合协作
  • utility：工具层，提供无状态的通用功能
  • architecture：架构上下文与组件访问入口
  • ioc：依赖注入容器，统一管理对象注册与获取
  • rule：上下文感知基类，为需要访问架构上下文的组件提供基础设施
  • game/game.abstractions：游戏层与抽象定义（模块化扩展）
graph TB
subgraph "核心层"
SYS["System<br/>业务逻辑层"]
UTL["Utility<br/>工具层"]
ARC["ArchitectureContext<br/>组件访问入口"]
IOC["IocContainer<br/>依赖注入容器"]
RUL["ContextAwareBase<br/>上下文感知基类"]
end
subgraph "游戏层"
MOD["AbstractModule<br/>模块基类"]
end
SYS --> ARC
UTL --> ARC
ARC --> IOC
SYS --> RUL
UTL --> RUL
MOD --> ARC

图表来源

章节来源

核心组件

  • 领域服务（在 GFramework 中体现为 System）：负责复杂业务逻辑、跨聚合协作、事件驱动与状态变更，强调“有状态”和“业务编排”。参考 AbstractSystem.cs、ISystem.cs。
  • 工具服务（Utility）：提供无状态的通用功能，如数学、序列化、随机等，强调“纯函数”和“可复用”。参考 AbstractContextUtility.cs、IContextUtility.cs。
  • 上下文感知基类：为需要访问架构上下文的组件提供统一能力，包括上下文设置与获取。参考 ContextAwareBase.cs。
  • 依赖注入容器：集中管理对象注册、获取与生命周期，支持单例、多实现注册与冻结保护。参考 IocContainer.cs。
  • 架构上下文：统一暴露系统、模型、工具的获取入口，以及命令、查询、事件的执行通道。参考 ArchitectureContext.cs。

章节来源

架构总览

GFramework 的领域服务通过“系统（System）+ 工具（Utility）+ 架构上下文（ArchitectureContext）+ 依赖注入（IocContainer）+ 上下文感知（ContextAwareBase）”协同工作，形成清晰的分层与职责边界。

sequenceDiagram
participant C as "调用方"
participant AC as "ArchitectureContext"
participant IOC as "IocContainer"
participant SYS as "System领域服务"
participant UTL as "Utility工具"
C->>AC : 请求获取系统/工具
AC->>IOC : Get<TService>()
IOC-->>AC : 返回实例或空
AC-->>C : 返回缓存或新实例
C->>SYS : 调用领域服务方法
SYS->>UTL : 使用工具进行纯函数计算
SYS-->>C : 返回业务结果

图表来源

详细组件分析

领域服务（System）设计与实现

classDiagram
class ContextAwareBase {
-IArchitectureContext Context
+SetContext(context)
+GetContext() IArchitectureContext
#OnContextReady()
}
class ISystem {
<<interface>>
+Init()
+Destroy()
+OnArchitecturePhase(phase)
}
class AbstractSystem {
-ILogger _logger
+Init()
+Destroy()
+OnArchitecturePhase(phase)
#OnInit()
#OnDestroy()
}
ContextAwareBase <|-- AbstractSystem
ISystem <|.. AbstractSystem

图表来源

章节来源

工具（Utility）与领域服务的关系

  • 无状态与纯函数：Utility 是无状态的工具集合，提供纯函数式能力，避免依赖模型或系统。参考 README.md（Utility 使用说明）。
  • 与 System 的协作：System 通过 ArchitectureContext 获取 Utility，将复杂计算与通用逻辑下沉至 Utility，提升可测试性与复用性。参考 ArchitectureContext.cs。
  • 上下文工具（IContextUtility）：当工具需要访问架构上下文时，可继承 AbstractContextUtility，获得上下文注入与日志记录能力。参考 AbstractContextUtility.cs、IContextUtility.cs。
classDiagram
class IContextUtility {
<<interface>>
+Init()
}
class AbstractContextUtility {
-ILogger Logger
+Init()
+Destroy()
#OnInit()
#OnDestroy()
}
IContextUtility <|.. AbstractContextUtility

图表来源

章节来源

依赖注入与服务注册

  • 注册与获取：IocContainer 支持 Register/Get/GetAll/GetRequired 等方法，提供线程安全与冻结保护。参考 IocContainer.cs、IocContainer.cs。
  • 架构上下文缓存：ArchitectureContext 对服务进行缓存，避免重复解析与降低开销。参考 ArchitectureContext.cs。
  • 架构接口：IArchitecture 提供 RegisterSystem/RegisterModel/RegisterUtility 等注册入口。参考 IArchitecture.cs。
flowchart TD
Start(["开始"]) --> Reg["注册服务到 IocContainer"]
Reg --> Get["通过 ArchitectureContext.GetService 获取"]
Get --> Cache{"缓存命中？"}
Cache --> |是| Return["返回缓存实例"]
Cache --> |否| Resolve["IocContainer 解析并缓存"]
Resolve --> Return
Return --> End(["结束"])

图表来源

章节来源

领域服务与系统（System）和工具（Utility）的区别与联系

  • 区别
  • 联系
    • 两者均通过 ArchitectureContext 获取，System 可调用 Utility 完成纯函数计算。
    • 两者均可继承 ContextAwareBase，获得上下文注入能力。参考 ContextAwareBase.cs。

章节来源

实现示例与最佳实践

章节来源

典型游戏场景设计与实现思路

  • 战斗计算服务
    • 设计要点：封装伤害计算、减伤、暴击、等级差影响等复杂逻辑；将纯计算下沉至 Utility，System 负责事件驱动与状态更新。
    • 参考实现路径：System 通过 ArchitectureContext 获取 Utility 完成计算，再更新模型并发布事件。参考 README.md（System 使用说明）、README.md（Utility 使用说明）。
  • 物品合成服务
    • 设计要点：根据配方与材料数量判断是否可合成；跨系统协作发放奖励；事件驱动状态变更。
    • 参考实现路径：System 监听配方事件，校验条件后触发奖励发放事件。参考 README.md（System 使用说明）。
  • AI 决策服务

章节来源

依赖分析

  • 组件耦合与内聚
    • System 与 Utility 通过 ArchitectureContext 解耦，内聚于各自职责边界。
    • IocContainer 提供统一注册与获取，避免各层直接依赖具体实现。
  • 直接与间接依赖
    • System/Utility 间接依赖 IocContainer 与 ArchitectureContext。
    • ContextAwareBase 为 System/Utility 提供上下文注入能力。
  • 循环依赖
    • 通过接口与架构上下文解耦，避免循环依赖风险。
  • 外部依赖与集成点
    • 事件总线、命令总线、查询总线通过 ArchitectureContext 统一接入。
graph LR
SYS["System"] --> ARC["ArchitectureContext"]
UTL["Utility"] --> ARC
ARC --> IOC["IocContainer"]
SYS --> RUL["ContextAwareBase"]
UTL --> RUL

图表来源

章节来源

性能考虑

章节来源

故障排查指南

  • 初始化失败
  • 依赖缺失
    • 现象：调用 GetService/GetSystem/GetUtility 返回空。
    • 排查：确认已在架构中注册对应服务；检查 IocContainer 的注册与冻结状态。参考 IocContainer.cs、ArchitectureContext.cs。
  • 生命周期问题
    • 现象：重复初始化/销毁异常。
    • 排查：遵循 AbstractSystem/AbstractContextUtility 的生命周期规范；避免在 Destroy 后继续使用实例。参考 AbstractContextUtilityTests.cs。

章节来源

结论

在 GFramework 中，领域服务以 System 为核心载体，通过 ArchitectureContext 与 IocContainer 实现解耦与可扩展，借助 ContextAwareBase 提供上下文感知能力；Utility 则承担无状态的通用计算与工具职责，二者协同完成复杂业务的封装与复用。遵循“System 有状态、Utility 无状态”的设计原则，配合事件驱动与模块化扩展，可构建高内聚、低耦合且易于维护的游戏业务框架。

附录

章节来源