gewuyou/GFramework
1
0
Fork 0
mirror of https://github.com/GeWuYou/GFramework.git synced 2026-05-07 00:39:00 +08:00
Code Issues Packages Projects Releases Wiki Activity
GFramework/CLAUDE.md
GeWuYou 38f98ea7ea docs: 添加 CQRS 架构模式和源代码生成器完整文档 
- 新增 CQRS 核心概念、命令查询处理器实现指南
- 添加请求分发器、通知发布和管道行为使用说明
- 提供流式处理、验证行为等高级特性文档
- 完善源代码生成器模块介绍和配置说明
- 包含 Log、ContextAware、EnumExtensions 等生成器详细用法
- 添加 Godot 专用生成器如 GetNode、AutoUiPage 等使用指南
- 整理诊断信息、最佳实践和常见问题解答
2026-04-17 16:33:29 +08:00

6.6 KiB
Raw Blame History

CLAUDE.md

This file provides project understanding for AI agents working in this repository.

Project Overview

GFramework 是面向游戏开发的模块化 C# 框架，核心能力与引擎解耦。项目灵感参考 QFramework，并在模块边界、工程组织和可扩展性方面持续重构。

AI Agent Instructions

All coding rules are defined in:

@AGENTS.md

Follow them strictly.

Module Dependency Graph

GFramework (meta package) ─→ Core + Game
GFramework.Cqrs ─→ Cqrs.Abstractions, Core.Abstractions
GFramework.Core ─→ Core.Abstractions
GFramework.Game ─→ Game.Abstractions, Core, Core.Abstractions
GFramework.Godot ─→ Core, Game, Core.Abstractions, Game.Abstractions
GFramework.Ecs.Arch ─→ Ecs.Arch.Abstractions, Core, Core.Abstractions
GFramework.Core.SourceGenerators ─→ Core.SourceGenerators.Abstractions, SourceGenerators.Common
GFramework.Game.SourceGenerators ─→ SourceGenerators.Common
GFramework.Godot.SourceGenerators ─→ Godot.SourceGenerators.Abstractions, SourceGenerators.Common
GFramework.Cqrs.SourceGenerators ─→ SourceGenerators.Common
  • Abstractions projects (netstandard2.1): 只包含接口和契约定义，不承载运行时实现逻辑。
  • Core / Game / Ecs.Arch (net8.0;net9.0;net10.0): 平台无关的核心实现层。
  • Godot: Godot 引擎集成层，负责与节点、场景和引擎生命周期对接。
  • SourceGenerators family (netstandard2.0/netstandard2.1): 按 Core / Game / Godot / Cqrs 拆分的 Roslyn 增量源码生成器，以及共享的 abstractions/common 基础设施。

Architecture Pattern

框架核心采用 Architecture / Model / System / Utility 四层结构：

  • IArchitecture: 顶层容器，负责生命周期管理、组件注册、模块安装和统一服务访问。
  • IContextAware: 统一上下文访问接口，组件通过 SetContext(IArchitectureContext) 获取架构上下文。
  • IModel: 数据与状态层，负责长期状态和业务数据建模。
  • ISystem: 业务逻辑层，负责命令执行、流程编排和规则落地。
  • IUtility: 通用无状态工具层，供其他层复用。

关键实现位于 GFramework.Core/Architectures/Architecture.cs，其职责是作为总协调器串联生命周期、组件注册和模块系统。

Architecture Details

Lifecycle

Architecture 负责统一生命周期编排，核心阶段包括：

  • Init
  • Ready
  • Destroy

在实现层中，生命周期被拆分为更细粒度的初始化与销毁阶段，用于保证 Utility、Model、System、服务模块和钩子的顺序一致性。

Component Coordination

框架通过独立组件协作完成架构编排：

  • ArchitectureLifecycle: 管理生命周期阶段、阶段转换和生命周期钩子。
  • ArchitectureComponentRegistry: 管理 Model、System、Utility 的注册与解析。
  • ArchitectureModules: 管理模块安装、服务模块接入和扩展点注册。

这组拆分的目标是降低单个核心类的职责密度，同时保持对外 API 稳定。

Context Propagation

IArchitectureContext 和相关 Provider 类型负责在组件之间传播上下文能力，使 Model、System 和外部扩展都能通过统一入口访问架构服务，而不直接耦合具体实现细节。

Key Patterns

CQRS

命令与查询分离，支持同步与异步执行。当前版本内建自有 CQRS runtime、行为管道和 handler 自动注册；历史 Mediator 兼容别名已从公开 API 移除，统一使用 Cqrs 命名入口。

EventBus

类型安全事件总线支持事件发布、订阅、优先级、过滤器和弱引用订阅。它是模块之间松耦合通信的核心基础设施之一。

BindableProperty

响应式属性模型通过值变化通知驱动界面或业务层更新，适合表达轻量级状态同步。

Coroutine

帧驱动协程系统基于 IYieldInstruction 和调度器抽象，支持等待时间、事件和任务完成等常见模式。

IoC

依赖注入通过 MicrosoftDiContainer 对 Microsoft.Extensions.DependencyInjection 进行封装，用于统一组件注册和服务解析体验。

Service Modules

IServiceModule 模式用于向 Architecture 注册内置服务，例如 EventBus、CommandExecutor、QueryExecutor 等。这一模式承担“基础设施能力装配”的职责。

Source Generators

当前仓库包含多类 Roslyn 增量源码生成器：

  • LoggerGenerator ([Log]): 自动生成日志字段和日志辅助方法。
  • PriorityGenerator ([Priority]): 生成优先级比较相关实现。
  • EnumExtensionsGenerator ([GenerateEnumExtensions]): 生成枚举扩展能力。
  • ContextAwareGenerator ([ContextAware]): 自动实现 IContextAware 相关样板逻辑。
  • CqrsHandlerRegistryGenerator: 为消费端程序集生成 CQRS handler 注册器，运行时优先使用生成产物，无法覆盖时回退到反射扫描；非默认程序集可通过 RegisterCqrsHandlersFromAssembly(...) / RegisterCqrsHandlersFromAssemblies(...) 显式接入同一路径。

这些生成器的目标是减少重复代码，同时保持框架层 API 的一致性与可维护性。

Module Structure

仓库以“抽象层 + 实现层 + 集成层 + 生成器层”的方式组织：

  • GFramework.Core.Abstractions / GFramework.Game.Abstractions: 约束接口和公共契约。
  • GFramework.Cqrs.Abstractions / GFramework.Cqrs: 提供 CQRS 契约、runtime 与 handler 注册基础设施。
  • GFramework.Core / GFramework.Game: 提供平台无关实现。
  • GFramework.Godot: 提供与 Godot 运行时集成的适配实现。
  • GFramework.Ecs.Arch: 提供 ECS Architecture 相关扩展。
  • GFramework.Core.SourceGenerators / GFramework.Game.SourceGenerators / GFramework.Godot.SourceGenerators / GFramework.Cqrs.SourceGenerators 与相关 Abstractions/Common: 提供代码生成能力。

这种结构的核心设计目标是让抽象稳定、实现可替换、引擎集成隔离、生成器能力可独立演进。

Documentation Structure

项目文档位于 docs/，中文内容位于 docs/zh-CN/。文档内容覆盖：

  • 入门与安装
  • Core / Game / Godot / ECS 各模块能力
  • Source Generator 使用说明
  • 教程、最佳实践与故障排查

阅读顺序通常建议先看根目录 README.md 和各子模块 README.md，再进入 docs/ 查阅专题说明。

Design Intent

GFramework 的设计重点不是把所有能力堆进单一核心类，而是通过清晰的模块边界、可组合的服务注册方式、稳定的抽象契约以及适度自动化的源码生成，构建一个适合长期演进的游戏开发基础框架。