mirror of https://github.com/GeWuYou/GFramework.git synced 2026-03-22 10:34:30 +08:00

GeWuYou 05c4f06717 docs(guide): 添加 CLAUDE.md 文件提供项目开发指导

- 新增项目概述说明，介绍 GFramework 框架的核心特性
- 添加构建和测试命令指南，包括 dotnet 构建和测试脚本
- 提供模块依赖关系图，说明各模块之间的依赖结构
- 详细描述架构模式，包括四层结构和关键设计模式
- 添加代码约定说明，涵盖命名空间、隐式引用等规范
- 补充测试框架信息，说明测试结构和基类使用方式
- 介绍源码生成器功能，列出四个主要生成器的作用
- 提供文档站点信息，说明 VitePress 文档的本地预览方法

2026-03-18 09:44:06 +08:00

4.2 KiB

Raw Blame History

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

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

Build & Test Commands

# 构建整个解决方案
dotnet build GFramework.sln -c Release

# 运行全部测试
dotnet test GFramework.sln -c Release

# 运行单个测试项目
dotnet test GFramework.Core.Tests -c Release
dotnet test GFramework.Game.Tests -c Release
dotnet test GFramework.SourceGenerators.Tests -c Release
dotnet test GFramework.Ecs.Arch.Tests -c Release

# 运行单个测试方法（NUnit filter）
dotnet test GFramework.Core.Tests -c Release --filter "FullyQualifiedName~CommandExecutorTests.Execute"

# 命名规范验证（CI 中使用）
bash scripts/validate-csharp-naming.sh

Module Dependency Graph

GFramework (meta package) ─→ Core + Game
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.SourceGenerators ─→ SourceGenerators.Common, SourceGenerators.Abstractions

Abstractions projects (netstandard2.1): 只含接口定义，零实现依赖
Core/Game (net8.0;net9.0;net10.0): 平台无关实现
Godot: Godot 引擎集成层
SourceGenerators (netstandard2.1): Roslyn 增量生成器

Architecture Pattern

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

IArchitecture: 顶层容器，管理生命周期（Init → Ready → Destroy）、注册 Model/System/Utility
IContextAware: 统一上下文访问接口，所有组件通过 SetContext(IArchitectureContext) 获得对 Architecture 服务的引用
IModel: 数据层（状态管理），继承 IContextAware
ISystem: 业务逻辑层，继承 IContextAware
IUtility: 无状态工具层

关键实现类：GFramework.Core/Architectures/Architecture.cs（主流程编排）

Key Patterns

CQRS: Command/Query 分离，支持同步与异步。Mediator 模式通过 Mediator.SourceGenerator 实现。

EventBus: 类型安全事件总线，支持优先级、过滤器、弱引用订阅。IEventBus.Send<T>() / Register<T>(handler) → IUnRegister。

BindableProperty: 响应式属性绑定，IBindableProperty<T>.Value 变更自动触发 OnValueChanged。

Coroutine: 帧驱动协程系统，IYieldInstruction + CoroutineScheduler，提供 WaitForSeconds/WaitForEvent/WaitForTask 等指令。

IoC: 通过 MicrosoftDiContainer 封装 Microsoft.Extensions.DependencyInjection。

Service Modules: IServiceModule 模式用于向 Architecture 注册内置服务（EventBus、CommandExecutor、QueryExecutor 等）。

Code Conventions

命名空间: GFramework.{Module}.{Feature} (PascalCase)，CI 通过 scripts/validate-csharp-naming.sh 强制校验
ImplicitUsings: disabled — 所有 using 必须显式声明
Nullable: enabled
LangVersion: preview
GenerateDocumentationFile: true — 公共 API 需要 XML 文档注释
Analyzers: Meziantou.Analyzer 在构建时强制代码规范

Testing

Framework: NUnit 4.x + Moq
测试结构: 镜像源码目录（如 Core.Tests/Command/ 对应 Core/Command/）
基类: ArchitectureTestsBase<T> 提供 Architecture 初始化/销毁模板；SyncTestArchitecture / AsyncTestArchitecture 用于集成测试
Target frameworks: net8.0;net10.0

Source Generators

四个生成器，均为 Roslyn 增量源码生成器：

LoggerGenerator ([Log]): 自动生成 ILogger 字段和日志方法
PriorityGenerator ([Priority]): 生成优先级比较实现
EnumExtensionsGenerator ([GenerateEnumExtensions]): 枚举扩展方法
ContextAwareGenerator ([ContextAware]): 自动实现 IContextAware 接口

测试使用快照验证（Verify + snapshot files）。

Documentation

VitePress 站点位于 docs/，内容为中文 (docs/zh-CN/)。修改文档后本地预览：

cd docs && bun install && bun run dev

4.2 KiB Raw Blame History Unescape Escape