From 704fdaa2c83fa17d0f17386c255d87fa8830efbb Mon Sep 17 00:00:00 2001 From: gewuyou <95328647+GeWuYou@users.noreply.github.com> Date: Wed, 22 Apr 2026 15:32:22 +0800 Subject: [PATCH] =?UTF-8?q?docs(core):=20=E5=AF=B9=E9=BD=90=20Core=20?= =?UTF-8?q?=E6=A8=A1=E5=9D=97=E6=96=87=E6=A1=A3=E5=85=A5=E5=8F=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 更新 Core 与 Core.Abstractions README 的目录映射和 XML 阅读入口 - 重写 Core Abstractions 页面，改为契约边界与最小接入路径说明 - 补充 Core landing page、API 参考入口和 ai-plan 跟踪记录 --- GFramework.Core.Abstractions/README.md | 38 +-- GFramework.Core/README.md | 15 +- ...ation-full-coverage-governance-tracking.md | 19 +- ...entation-full-coverage-governance-trace.md | 7 +- docs/zh-CN/abstractions/core-abstractions.md | 235 +++++------------- docs/zh-CN/api-reference/index.md | 2 +- docs/zh-CN/core/index.md | 45 +++- 7 files changed, 160 insertions(+), 201 deletions(-) diff --git a/GFramework.Core.Abstractions/README.md b/GFramework.Core.Abstractions/README.md index 4be033ab..410a5822 100644 --- a/GFramework.Core.Abstractions/README.md +++ b/GFramework.Core.Abstractions/README.md @@ -2,6 +2,8 @@ `GFramework.Core.Abstractions` 承载 `Core` 运行时对应的接口、枚举和值对象，用来定义跨模块协作边界。 +它只描述契约，不提供默认的架构、事件、状态、资源或 IoC 实现；这些实现都在 `GFramework.Core` 中。 + ## 什么时候单独依赖它 - 你在做插件、适配层或扩展包，只想依赖契约，不想把完整运行时拉进来 @@ -20,23 +22,17 @@ ## 契约地图 -| 目录 | 作用 | +| 目录族 | 作用 | | --- | --- | -| `Architectures/` | `IArchitecture`、模块、阶段监听与服务管理契约 | -| `Command/` / `Query/` | 旧版命令与查询执行器接口 | -| `Controller/` | `IController` | -| `Events/` | 事件契约、解绑接口与传播上下文 | -| `Model/` / `Systems/` / `Utility/` | 核心组件接口 | -| `State/` / `StateManagement/` | 状态机、Store、reducer、selector 契约 | -| `Property/` | `IBindableProperty` 与只读属性接口 | -| `Resource/` | 资源管理与释放策略契约 | -| `Localization/` | 本地化表、格式化与异常类型 | -| `Logging/` | logger、log entry、factory 相关契约 | -| `Ioc/` | `IIocContainer` | -| `Lifecycle/` | 初始化 / 销毁生命周期契约 | -| `Coroutine/` | 时间源、yield 指令与协程状态枚举 | -| `Pause/` | 暂停栈、token 与状态事件 | -| `Storage/` / `Serializer/` / `Versioning/` | 通用存储、序列化与版本化契约 | +| `Architectures/` `Lifecycle/` `Registries/` | `IArchitecture`、上下文、模块、服务模块、阶段监听、注册表基类与生命周期契约 | +| `Bases/` `Controller/` `Model/` `Systems/` `Utility/` `Rule/` | 组件角色接口、优先级 / key 值对象、上下文感知约束与扩展边界 | +| `Command/` `Query/` `Cqrs/` | 旧版命令 / 查询执行器接口，以及 `ICqrsRuntime` 这类新请求模型接线契约 | +| `Events/` `Property/` `State/` `StateManagement/` | 事件总线、解绑对象、可绑定属性、状态机、Store / reducer / middleware 契约 | +| `Coroutine/` `Time/` `Pause/` `Concurrency/` | 协程状态、时间源、暂停栈、键控异步锁和统计对象 | +| `Resource/` `Pool/` `Logging/` `Localization/` | 资源句柄、对象池、日志、日志工厂、本地化表与格式化契约 | +| `Configuration/` `Environment/` | 配置管理器、环境对象与运行时环境访问契约 | +| `Data/` `Serializer/` `Storage/` `Versioning/` | 数据装载、序列化、存储与版本化契约 | +| `Enums/` `Properties/` | 架构阶段枚举，以及架构 / logger 相关属性键 | ## 采用建议 @@ -44,8 +40,18 @@ - 若你只需要对接口编程，可以仅引用本包，再在应用层自行提供实现 - 若你在写上层模块，优先把公共契约放在 `*.Abstractions`，实现放在对应 runtime 包 +## 重点 XML 关注点 + +如果你在做契约审计、模块拆分或测试替身，优先看这些类型族的 XML 文档： + +- 架构与模块入口：`IArchitecture`、`IArchitectureContext`、`IServiceModule` +- 运行时基础设施：`IIocContainer`、`ILogger`、`IResourceManager`、`IConfigurationManager` +- 状态与并发能力：`IStateMachine`、`IStore`、`IAsyncKeyLockManager`、`ITimeProvider` +- 迁移与组合边界：`ICommandExecutor`、`IQueryExecutor`、`ICqrsRuntime` + ## 对应文档 - 抽象接口栏目：[`../docs/zh-CN/abstractions/index.md`](../docs/zh-CN/abstractions/index.md) - Core 抽象页：[`../docs/zh-CN/abstractions/core-abstractions.md`](../docs/zh-CN/abstractions/core-abstractions.md) - Core 运行时入口：[`../GFramework.Core/README.md`](../GFramework.Core/README.md) +- API 参考入口：[`../docs/zh-CN/api-reference/index.md`](../docs/zh-CN/api-reference/index.md) diff --git a/GFramework.Core/README.md b/GFramework.Core/README.md index 8287bd24..eaae5ece 100644 --- a/GFramework.Core/README.md +++ b/GFramework.Core/README.md @@ -10,9 +10,10 @@ - `Architecture` 与 `ArchitectureContext` - `Model` / `System` / `Utility` 运行时 -- 旧版 `Command` / `Query` 执行器 -- 事件、属性、状态机、状态管理 -- 资源、日志、协程、并发、环境与本地化 +- 旧版 `Command` / `Query` 执行器，以及与新版 `CQRS` runtime 的接线入口 +- 事件、属性、状态机、状态管理、规则与上下文扩展 +- 资源、对象池、日志、协程、并发、环境、配置与本地化 +- 服务模块管理、时间提供器与默认的 IoC 容器适配 它不负责： @@ -37,6 +38,7 @@ | 目录 | 作用 | | --- | --- | | `Architectures/` | 架构入口、上下文、生命周期、模块安装与组件注册 | +| `Services/` | 服务模块注册、生命周期协调与模块管理 | | `Command/` | 旧版命令执行器与同步 / 异步命令基类 | | `Query/` | 旧版查询执行器与同步 / 异步查询基类 | | `Events/` | 事件总线、事件作用域、统计与过滤 | @@ -44,12 +46,17 @@ | `State/` | 状态机与状态切换事件 | | `StateManagement/` | Store、selector、middleware 与状态诊断 | | `Coroutine/` | 协程调度、快照、统计与优先级 | +| `Time/` | 默认时间提供器与协程时间源 | | `Resource/` | 资源缓存、句柄和释放策略 | +| `Pool/` | 对象池系统与常用池化辅助实现 | | `Logging/` | logger、factory、配置与组合日志器 | | `Ioc/` | 基于 `Microsoft.Extensions.DependencyInjection` 的容器适配 | | `Concurrency/` | 键控异步锁与统计 | +| `Configuration/` | 配置管理器与配置监听解绑对象 | +| `Environment/` | 运行环境对象与上下文环境扩展 | | `Pause/` | 暂停栈和暂停范围 | | `Localization/` | 本地化表与格式化入口 | +| `Rule/` | `ContextAwareBase` 等上下文感知基类 | | `Functional/` | `Option`、`Result` 等轻量函数式工具 | | `Extensions/` | 上下文与集合等扩展方法 | @@ -80,5 +87,7 @@ dotnet add package GeWuYou.GFramework.Core.Abstractions ## 对应文档 - Core 栏目：[`../docs/zh-CN/core/index.md`](../docs/zh-CN/core/index.md) +- Core 抽象层：[`../docs/zh-CN/abstractions/core-abstractions.md`](../docs/zh-CN/abstractions/core-abstractions.md) +- API 参考入口：[`../docs/zh-CN/api-reference/index.md`](../docs/zh-CN/api-reference/index.md) - CQRS：[`../docs/zh-CN/core/cqrs.md`](../docs/zh-CN/core/cqrs.md) - 入门指南：[`../docs/zh-CN/getting-started/index.md`](../docs/zh-CN/getting-started/index.md) diff --git a/ai-plan/public/documentation-full-coverage-governance/todos/documentation-full-coverage-governance-tracking.md b/ai-plan/public/documentation-full-coverage-governance/todos/documentation-full-coverage-governance-tracking.md index 1bddcd54..22bc302c 100644 --- a/ai-plan/public/documentation-full-coverage-governance/todos/documentation-full-coverage-governance-tracking.md +++ b/ai-plan/public/documentation-full-coverage-governance/todos/documentation-full-coverage-governance-tracking.md @@ -33,12 +33,16 @@ - 在根 `README.md` 中补齐 `GFramework.Ecs.Arch.Abstractions` 入口，并声明内部支撑模块 owner - 为抽象接口栏目补齐 `Ecs.Arch.Abstractions` 页面与 sidebar 入口 - 将 `docs/zh-CN/api-reference/index.md` 重写为模块到 XML / README / 教程的阅读链路入口 + - 为 `GFramework.Core/README.md` 补齐 `Services`、`Configuration`、`Environment`、`Pool`、`Rule`、`Time` 等当前目录映射 + - 为 `GFramework.Core.Abstractions/README.md` 补齐契约族地图与 XML 阅读重点 + - 将 `docs/zh-CN/abstractions/core-abstractions.md` 从过时的接口摘录页重写为契约边界 / 包关系 / 最小接入路径页面 + - 为 `docs/zh-CN/core/index.md` 补齐 frontmatter、能力域导航和 API / XML 阅读入口 ## Inventory（第一版） | 模块族 | 当前状态 | 当前证据 | 下一动作 | | --- | --- | --- | --- | -| `Core` / `Core.Abstractions` | `已验证` | 根 README、模块 README、`docs/zh-CN/core/**`、`docs/zh-CN/abstractions/core-abstractions.md` 已存在 | 进入首轮波次时补 XML 文档 inventory | +| `Core` / `Core.Abstractions` | `入口已收口，XML inventory 待补齐` | 根 README、模块 README、`docs/zh-CN/core/**`、`docs/zh-CN/abstractions/core-abstractions.md` 已对齐当前目录与采用路径 | 下一恢复点为类型族级 XML 覆盖清单 | | `Cqrs` / `Cqrs.Abstractions` / `Cqrs.SourceGenerators` | `待重写` | README 已存在；站内入口目前分散在 `docs/zh-CN/core/cqrs.md` 与 `docs/zh-CN/source-generators/**` | 在 `Cqrs` 波次里补 dedicated landing / API map 审计 | | `Game` / `Game.Abstractions` / `Game.SourceGenerators` | `已验证` | 根 README、模块 README、`docs/zh-CN/game/**` 和 abstractions 页已存在 | 后续波次补 XML / 教程链路审计 | | `Godot` / `Godot.SourceGenerators` | `已验证` | 上一轮归档 topic 已完成核心 landing / topic / tutorial 校验 | 进入巡检周期，重点看回漂 | @@ -63,9 +67,11 @@ - `docs/zh-CN/ecs/index.md` 与 `docs/zh-CN/ecs/arch.md` 仍保留较多早期表述，本轮只先完成 inventory 与入口补齐 - 缓解措施：把 `Ecs.Arch` 排进前五波次，并把 runtime docs 重写列为该波次的必做项 - XML 文档尚未按模块做全量类型审计 - - 缓解措施：下一恢复点先从 `Core` 模块族建立“类型族 -> XML 覆盖状态”清单 + - 缓解措施：当前已补 `Core` / `Core.Abstractions` 的 XML 阅读入口；下一恢复点继续建立“类型族 -> XML 覆盖状态”清单 - 新功能分支若修改 README / docs / 公共 API 却不挂文档 topic，仍可能回漂 - 缓解措施：将本 topic 作为长期 active topic 保留，并在后续巡检中记录回漂来源 +- VitePress 页面不能直接链接到 `docs/` 目录之外的模块 `README.md` + - 缓解措施：站内页面用模块路径文本或站内 API 入口表达，仓库级 README 仍保留仓库文件链接 ## 验证说明 @@ -75,15 +81,22 @@ - 结果：通过 - `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/api-reference/index.md` - 结果：通过 +- `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/core/index.md` +- 结果：通过 +- `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/abstractions/core-abstractions.md` +- 结果：通过 - `cd docs && bun run build` - 结果：通过 - 备注：仅保留 VitePress 大 chunk warning，无构建失败 - `dotnet build GFramework.Ecs.Arch.Abstractions/GFramework.Ecs.Arch.Abstractions.csproj -c Release -p:RestoreFallbackFolders=` - 结果：通过 - 备注：`0 Warning(s) / 0 Error(s)` +- `DOTNET_CLI_HOME=/tmp/dotnet-home dotnet build GFramework.Core.Abstractions/GFramework.Core.Abstractions.csproj -c Release -p:RestoreFallbackFolders=` +- 结果：通过 +- 备注：`0 Warning(s) / 0 Error(s)` ## 下一步 -1. 按波次顺序启动 `Core` / `Core.Abstractions` 的 XML 文档与 API 链路 inventory +1. 继续 `Core` / `Core.Abstractions` 波次，为公开类型族补一份“类型族 -> XML 覆盖状态”清单 2. 在 `Ecs` 波次重写 `docs/zh-CN/ecs/index.md` 与 `docs/zh-CN/ecs/arch.md` 3. 为每个模块族补一份“README / landing / tutorials / API reference / XML”对照表，持续清零 `P0` / `P1` diff --git a/ai-plan/public/documentation-full-coverage-governance/traces/documentation-full-coverage-governance-trace.md b/ai-plan/public/documentation-full-coverage-governance/traces/documentation-full-coverage-governance-trace.md index f87f45cd..cb71b105 100644 --- a/ai-plan/public/documentation-full-coverage-governance/traces/documentation-full-coverage-governance-trace.md +++ b/ai-plan/public/documentation-full-coverage-governance/traces/documentation-full-coverage-governance-trace.md @@ -18,6 +18,8 @@ - 本轮先做治理基础设施与 inventory，不把整个长期计划伪装成单轮完成 - `api-reference` 页面改为“模块 -> README / docs / XML / tutorial”的阅读链路入口，避免继续维护失真的伪签名列表 - `Ecs.Arch` family 被列为高优先 backlog：抽象层入口已补齐，但 runtime docs 仍需按源码重写 +- `Core` / `Core.Abstractions` 波次先收口 README、landing page 和 abstractions 页的目录映射，再补显式 XML 覆盖 inventory +- VitePress 站内页面不直接链接仓库根模块 `README.md`；站内仅保留可构建的 docs 链接，模块 README 以文本路径或仓库 README 承接 ### 当前验证 @@ -25,11 +27,14 @@ - `validate-all.sh docs/zh-CN/abstractions/index.md`：通过 - `validate-all.sh docs/zh-CN/abstractions/ecs-arch-abstractions.md`：通过 - `validate-all.sh docs/zh-CN/api-reference/index.md`：通过 + - `validate-all.sh docs/zh-CN/core/index.md`：通过 + - `validate-all.sh docs/zh-CN/abstractions/core-abstractions.md`：通过 - 构建校验： - `cd docs && bun run build`：通过 + - `DOTNET_CLI_HOME=/tmp/dotnet-home dotnet build GFramework.Core.Abstractions/GFramework.Core.Abstractions.csproj -c Release -p:RestoreFallbackFolders=`：通过，`0 Warning(s) / 0 Error(s)` - `dotnet build GFramework.Ecs.Arch.Abstractions/GFramework.Ecs.Arch.Abstractions.csproj -c Release -p:RestoreFallbackFolders=`：通过，`0 Warning(s) / 0 Error(s)` ### 下一步 -1. 进入 `Core` / `Core.Abstractions` 波次，先建立 XML 文档覆盖 inventory +1. 继续 `Core` / `Core.Abstractions` 波次，按类型族建立 XML 文档覆盖 inventory 2. 在 `Ecs` 波次重写运行时 docs，并把 `Ecs.Arch.Abstractions` 纳入完整模块闭环 diff --git a/docs/zh-CN/abstractions/core-abstractions.md b/docs/zh-CN/abstractions/core-abstractions.md index 4a139d74..d42386e1 100644 --- a/docs/zh-CN/abstractions/core-abstractions.md +++ b/docs/zh-CN/abstractions/core-abstractions.md @@ -1,192 +1,87 @@ +--- +title: Core Abstractions +description: GFramework.Core.Abstractions 的契约边界、包关系与 XML 阅读重点。 +--- + # Core Abstractions -> GFramework.Core.Abstractions 核心抽象接口定义 +`GFramework.Core.Abstractions` 是 `Core` 运行时的契约包。 -## 概述 +它负责定义架构、生命周期、事件、状态、资源、日志、配置、并发和持久化相关的接口、枚举和值对象，用来建立跨模块协作边界； +默认实现、基类、容器适配和运行时装配则在 `GFramework.Core` 中。 -GFramework.Core.Abstractions 包含了框架的所有核心接口定义，这些接口定义了组件之间的契约，实现了依赖倒置和面向接口编程。 +如果你要开箱即用地使用框架能力，应依赖 `GFramework.Core`；如果你在做扩展包、测试替身、工具层或多模块拆分，才单独消费本包。 -## 核心接口 +## 什么时候单独依赖它 -### IArchitecture +- 你在写插件、模块扩展或测试替身，只想依赖接口而不拉入默认运行时 +- 你需要让多个程序集共享架构、状态、资源或日志契约 +- 你希望把公共边界放进 `*.Abstractions`，而把具体实现留在应用层或宿主层 -应用程序架构接口： +## 包关系 + +- 契约层：`GFramework.Core.Abstractions` +- 运行时实现：`GFramework.Core` +- 常见相邻契约：`GFramework.Cqrs.Abstractions`、`GFramework.Game.Abstractions` + +## 契约地图 + +| 契约族 | 作用 | +| --- | --- | +| `Architectures/` `Lifecycle/` `Registries/` | `IArchitecture`、上下文、模块、服务模块、阶段监听、注册表与初始化 / 销毁生命周期契约 | +| `Bases/` `Controller/` `Model/` `Systems/` `Utility/` `Rule/` | 组件角色接口、优先级 / key 值对象、上下文感知边界 | +| `Command/` `Query/` `Cqrs/` | 旧版命令 / 查询执行器接口，以及与新版请求模型衔接的运行时契约 | +| `Events/` `Property/` `State/` `StateManagement/` | 事件总线、解绑对象、可绑定属性、状态机、Store / reducer / middleware 契约 | +| `Coroutine/` `Time/` `Pause/` `Concurrency/` | 协程状态、时间源、暂停栈、键控异步锁与统计对象 | +| `Resource/` `Pool/` `Logging/` `Localization/` | 资源句柄、对象池、日志、logger factory、本地化表与格式化契约 | +| `Configuration/` `Environment/` | 配置管理器、环境对象与运行时环境访问契约 | +| `Data/` `Serializer/` `Storage/` `Versioning/` | 数据装载、序列化、存储与版本化契约 | +| `Enums/` `Properties/` | 架构阶段枚举，以及架构 / logger 相关属性键 | + +## 最小接入路径 + +### 1. 只面向契约编程 ```csharp -public interface IArchitecture -{ - void Initialize(); - void Destroy(); - - T GetModel() where T : IModel; - T GetSystem() where T : ISystem; - T GetUtility() where T : IUtility; - - void RegisterModel(IModel model); - void RegisterSystem(ISystem system); - void RegisterUtility(IUtility utility); -} -``` +using GFramework.Core.Abstractions.Architectures; +using GFramework.Core.Abstractions.Logging; -### IModel - -数据模型接口： - -```csharp -public interface IModel -{ - void Init(); - void Dispose(); - - IArchitecture Architecture { get; } -} -``` - -### ISystem - -业务逻辑系统接口： - -```csharp -public interface ISystem -{ - void Init(); - void Dispose(); - - IArchitecture Architecture { get; } -} -``` - -### IController - -控制器接口： - -```csharp -public interface IController : IBelongToArchitecture -{ - void Init(); - void Dispose(); -} -``` - -### IUtility - -工具类接口： - -```csharp -public interface IUtility -{ -} -``` - -## 事件接口 - -### IEvent - -事件基接口： - -```csharp -public interface IEvent -{ -} -``` - -### IEventHandler - -事件处理器接口： - -```csharp -public interface IEventHandler where TEvent : IEvent -{ - void Handle(TEvent @event); -} -``` - -## 命令查询接口 - -### ICommand - -命令接口： - -```csharp -public interface ICommand -{ - void Execute(); -} -``` - -### IQuery - -查询接口： - -```csharp -public interface IQuery -{ - TResult Execute(); -} -``` - -## 依赖注入接口 - -### IIocContainer - -IoC 容器接口： - -```csharp -public interface IIocContainer -{ - void Register() where TImplementation : TInterface; - void Register(TInterface instance); - TInterface Resolve(); - bool IsRegistered(); -} -``` - -## 生命周期接口 - -### ILifecycle - -组件生命周期接口： - -```csharp -public interface ILifecycle -{ - void OnInit(); - void OnDestroy(); -} -``` - -## 使用示例 - -### 通过接口实现依赖注入 - -```csharp -public class MyService : IMyService +public sealed class DiagnosticsFeature { private readonly IArchitecture _architecture; - - public MyService(IArchitecture architecture) + private readonly ILogger _logger; + + public DiagnosticsFeature(IArchitecture architecture, ILogger logger) { _architecture = architecture; + _logger = logger; } } ``` -### 自定义事件 +### 2. 什么时候切到运行时包 -```csharp -public class PlayerDiedEvent : IEvent -{ - public int PlayerId { get; set; } - public Vector2 Position { get; set; } -} -``` +下面这些需求都属于 `GFramework.Core` 的职责，而不是本包： ---- +- 继承 `Architecture` 并完成默认初始化流程 +- 使用 `ContextAwareBase`、`AbstractModel`、`AbstractSystem` 等默认基类 +- 使用默认的 `CommandExecutor`、`QueryExecutor`、`BindableProperty`、`StateMachine` +- 直接启用默认的 `Microsoft.Extensions.DependencyInjection` 容器适配或资源 / 协程 / 日志实现 -**相关文档**： +## XML 阅读重点 -- [Core 概述](../core/index.md) -- [Architecture](../core/architecture) -- [Events](../core/events) -- [Command](../core/command) -- [Query](../core/query) +如果你在做契约审计、采用设计或扩展适配，优先核对这些类型族的 XML 文档： + +- 架构与模块入口：`IArchitecture`、`IArchitectureContext`、`IServiceModule` +- 运行时基础设施：`IIocContainer`、`ILogger`、`IResourceManager`、`IConfigurationManager` +- 状态与并发能力：`IStateMachine`、`IStore`、`IAsyncKeyLockManager`、`ITimeProvider` +- 迁移与组合边界：`ICommandExecutor`、`IQueryExecutor`、`ICqrsRuntime` + +## 阅读顺序 + +1. 先读本页，确认你是否真的只需要契约层 +2. 再看 [`../core/index.md`](../core/index.md) 了解默认运行时怎么组织这些契约 +3. 回到模块 README： + - `GFramework.Core.Abstractions/README.md` + - `GFramework.Core/README.md` +4. 需要统一导航时，再看 [`../api-reference/index.md`](../api-reference/index.md) diff --git a/docs/zh-CN/api-reference/index.md b/docs/zh-CN/api-reference/index.md index 9dc1d72a..02d63fd1 100644 --- a/docs/zh-CN/api-reference/index.md +++ b/docs/zh-CN/api-reference/index.md @@ -29,7 +29,7 @@ description: GFramework 的 API 阅读入口，按模块映射 README、专题 | 模块族 | 模块 README | 站内入口 | XML 文档关注点 | | --- | --- | --- | --- | -| `Core` / `Core.Abstractions` | `GFramework.Core/README.md`、`GFramework.Core.Abstractions/README.md` | [`../core/index.md`](../core/index.md)、[`../abstractions/core-abstractions.md`](../abstractions/core-abstractions.md) | 架构入口、生命周期、命令 / 查询 / 事件 / 状态 / 资源 / 日志契约 | +| `Core` / `Core.Abstractions` | `GFramework.Core/README.md`、`GFramework.Core.Abstractions/README.md` | [`../core/index.md`](../core/index.md)、[`../abstractions/core-abstractions.md`](../abstractions/core-abstractions.md) | 架构入口、生命周期、命令 / 查询 / 事件 / 状态 / 资源 / 日志 / 配置 / 并发契约 | | `Cqrs` / `Cqrs.Abstractions` / `Cqrs.SourceGenerators` | `GFramework.Cqrs/README.md`、`GFramework.Cqrs.Abstractions/README.md`、`GFramework.Cqrs.SourceGenerators/README.md` | [`../core/cqrs.md`](../core/cqrs.md)、[`../source-generators/index.md`](../source-generators/index.md) | request / notification / handler / pipeline / registry contract | | `Game` / `Game.Abstractions` / `Game.SourceGenerators` | `GFramework.Game/README.md`、`GFramework.Game.Abstractions/README.md`、`GFramework.Game.SourceGenerators/README.md` | [`../game/index.md`](../game/index.md)、[`../abstractions/game-abstractions.md`](../abstractions/game-abstractions.md) | 配置、数据、设置、场景、UI、存储、序列化契约 | | `Godot` / `Godot.SourceGenerators` | `GFramework.Godot/README.md`、`GFramework.Godot.SourceGenerators/README.md` | [`../godot/index.md`](../godot/index.md)、[`../source-generators/index.md`](../source-generators/index.md) | 节点扩展、场景 / UI 适配、资源 / 存储 / 日志接入 | diff --git a/docs/zh-CN/core/index.md b/docs/zh-CN/core/index.md index d8a600a6..931197f8 100644 --- a/docs/zh-CN/core/index.md +++ b/docs/zh-CN/core/index.md @@ -1,3 +1,8 @@ +--- +title: Core +description: GFramework.Core 与 GFramework.Core.Abstractions 的运行时入口、采用顺序和 XML 阅读导航。 +--- + # Core `Core` 栏目对应 `GFramework` 的基础运行时层，主要覆盖 `GFramework.Core` 与 `GFramework.Core.Abstractions`，以及与之直接相邻的旧版 @@ -29,28 +34,53 @@ dotnet add package GeWuYou.GFramework.Core.Abstractions `Core` 栏目不是旧版“完整框架教程”的镜像，而是当前实现的入口导航。这里的页面按能力域组织： -- 架构与上下文 +- 架构与生命周期 - [architecture](./architecture.md) - [context](./context.md) - [lifecycle](./lifecycle.md) + - [async-initialization](./async-initialization.md) +- 组件角色与运行时接入 + - [model](./model.md) + - [system](./system.md) + - [utility](./utility.md) + - [environment](./environment.md) + - [extensions](./extensions.md) - 旧版命令 / 查询执行器与迁移入口 - [command](./command.md) - [query](./query.md) - [cqrs](./cqrs.md) -- 核心横切能力 +- 状态、事件与规则 - [events](./events.md) - [property](./property.md) + - [rule](./rule.md) - [logging](./logging.md) - - [resource](./resource.md) - - [coroutine](./coroutine.md) - - [ioc](./ioc.md) -- 状态与扩展能力 - [state-machine](./state-machine.md) - [state-management](./state-management.md) +- 运行时支撑能力 + - [resource](./resource.md) + - [pool](./pool.md) + - [coroutine](./coroutine.md) - [pause](./pause.md) - [localization](./localization.md) + - [configuration](./configuration.md) + - [ioc](./ioc.md) +- 通用辅助能力 - [functional](./functional.md) - - [extensions](./extensions.md) + +## XML 与 API 阅读入口 + +如果你已经知道模块归属，但想确认公开类型的契约边界，建议按下面顺序阅读： + +1. 先看模块 README `GFramework.Core/README.md`，确认包关系和目录边界 +2. 再看本栏目对应专题页，确认采用顺序、生命周期与推荐接线方式 +3. 最后回到源码中的 XML 文档，重点核对这些类型族： + - `Architecture` / `IArchitectureContext` + - `CommandExecutor` / `QueryExecutor` + - `ILogger` / `ILoggerFactory` + - `IResourceManager` / `IConfigurationManager` + - `IAsyncKeyLockManager` / `ITimeProvider` + +统一入口见 [`../api-reference/index.md`](../api-reference/index.md)。 ## 最小接入路径 @@ -104,4 +134,5 @@ public sealed class CounterArchitecture : Architecture - `GFramework.Core/README.md` - `GFramework.Core.Abstractions/README.md` +- `docs/zh-CN/api-reference/index.md` - 仓库根 `README.md`