gewuyou/GFramework
1
0
Fork 0
mirror of https://github.com/GeWuYou/GFramework.git synced 2026-03-22 10:34:30 +08:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #110 from GeWuYou/docs/remove-migration-guide

Browse Source 
Docs/remove migration guide
This commit is contained in:
gewuyou 2026-03-13 22:44:29 +08:00 committed by GitHub
commit 2d89efa4b7
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
2 changed files with 0 additions and 951 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
docs/.vitepress/config.mts
View File

@ -59,7 +59,6 @@ export default defineConfig({
{ text: 'API 参考', link: '/zh-CN/api-reference' },
{ text: '常见问题', link: '/zh-CN/faq' },
{ text: '故障排查', link: '/zh-CN/troubleshooting' },
{ text: '迁移指南', link: '/zh-CN/migration-guide' },
{ text: '贡献指南', link: '/zh-CN/contributing' }
]
}

950
docs/zh-CN/migration-guide.md
View File

@ -1,950 +0,0 @@
# 版本迁移指南
本文档提供 GFramework 不同版本之间的迁移指导，帮助开发者平滑升级到新版本。
## 概述
### 迁移指南的使用
本迁移指南旨在帮助开发者：
- **了解版本间的重大变更**：明确不同版本之间的 API 变化和行为差异
- **规划迁移路径**：根据项目实际情况选择合适的迁移策略
- **减少迁移风险**：通过详细的步骤说明和代码示例降低升级风险
- **快速定位问题**：提供常见问题的解决方案和回滚策略
### 阅读建议
1. **确认当前版本**：查看项目中使用的 GFramework 版本号
2. **查看目标版本**：确定要升级到的目标版本
3. **阅读相关章节**：重点关注涉及的版本迁移章节
4. **测试验证**：在测试环境中完成迁移并充分测试
5. **逐步升级**：对于跨多个大版本的升级，建议分步进行
## 版本兼容性
### 版本号说明
GFramework 遵循 [语义化版本](https://semver.org/lang/zh-CN/) 规范：
```
主版本号.次版本号.修订号 (MAJOR.MINOR.PATCH)
```
- **主版本号（MAJOR）**：不兼容的 API 变更
- **次版本号（MINOR）**：向后兼容的功能新增
- **修订号（PATCH）**：向后兼容的问题修正
### 兼容性矩阵
| 源版本 | 目标版本 | 兼容性 | 迁移难度 | 说明 |
|-------|-------|---------|------|---------------|
| 0.0.x | 0.0.y | ✅ 完全兼容 | 低 | 修订版本，直接升级 |
| 0.0.x | 1.0.0 | ⚠️ 部分兼容 | 中 | 需要代码调整 |
| 0.x.x | 1.x.x | ❌ 不兼容 | 高 | 重大变更，需要重构 |
| 1.x.x | 1.y.y | ✅ 向后兼容 | 低 | 次版本升级，可能有废弃警告 |
| 1.x.x | 2.0.0 | ❌ 不兼容 | 高 | 重大变更，需要重构 |
### .NET 版本支持
| GFramework 版本 | .NET 8.0 | .NET 9.0 | .NET 10.0 |
|---------------|----------|----------|-----------|
| 0.0.x | ✅ | ✅ | ✅ |
| 1.0.x | ✅ | ✅ | ✅ |
| 2.0.x | ❌ | ✅ | ✅ |
### Godot 版本支持
| GFramework 版本 | Godot 4.3 | Godot 4.4 | Godot 4.5 | Godot 4.6+ |
|---------------|-----------|-----------|-----------|------------|
| 0.0.x | ✅ | ✅ | ✅ | ✅ |
| 1.0.x | ❌ | ✅ | ✅ | ✅ |
| 2.0.x | ❌ | ❌ | ✅ | ✅ |
## 从 0.x 迁移到 1.x
### 重大变更概述
1.0 版本是 GFramework 的第一个稳定版本，引入了多项重大变更以提升框架的稳定性、性能和可维护性。
#### 架构层面变更
- **架构初始化方式变更**：统一使用异步初始化
- **生命周期阶段调整**：简化阶段流程，移除冗余阶段
- **IOC 容器增强**：支持作用域和生命周期管理
- **模块系统重构**：引入新的模块注册机制
#### API 变更
- **命名空间调整**：部分类型移动到新的命名空间
- **接口签名变更**：部分接口方法签名调整
- **废弃 API 移除**：移除 0.x 中标记为废弃的 API
- **泛型约束调整**：部分泛型方法增加或调整约束
#### 行为变更
- **事件传播机制**：优化事件传播逻辑
- **协程调度策略**：改进协程调度算法
- **资源管理策略**：引入新的资源释放策略
### 迁移前准备
#### 1. 备份项目
```bash
# 创建项目备份
git checkout -b backup-before-migration
git push origin backup-before-migration
# 或使用文件系统备份
cp -r YourProject YourProject-backup
```
#### 2. 检查当前版本
```bash
# 查看当前使用的 GFramework 版本
dotnet list package | grep GFramework
```
#### 3. 更新依赖工具
```bash
# 更新 .NET SDK
dotnet --version
# 更新 NuGet 客户端
dotnet nuget --version
```
#### 4. 运行现有测试
```bash
# 确保所有测试通过
dotnet test
# 记录测试结果作为基准
dotnet test --logger "trx;LogFileName=baseline-tests.trx"
```
### 迁移步骤
#### 步骤 1：更新 NuGet 包
```bash
# 更新核心包
dotnet add package GeWuYou.GFramework.Core --version 1.0.0
dotnet add package GeWuYou.GFramework.Core.Abstractions --version 1.0.0
# 更新游戏扩展包
dotnet add package GeWuYou.GFramework.Game --version 1.0.0
dotnet add package GeWuYou.GFramework.Game.Abstractions --version 1.0.0
# 更新 Godot 集成包（如果使用）
dotnet add package GeWuYou.GFramework.Godot --version 1.0.0
# 更新源码生成器
dotnet add package GeWuYou.GFramework.SourceGenerators --version 1.0.0
```
#### 步骤 2：更新命名空间引用
**0.x 版本：**
```csharp
using GFramework.Core;
using GFramework.Core.Architecture;
using GFramework.Core.Events;
```
**1.x 版本：**
```csharp
using GFramework.Core.Abstractions.Architecture;
using GFramework.Core.Abstractions.Events;
using GFramework.Core.Architecture;
using GFramework.Core.Events;
```
#### 步骤 3：更新架构初始化代码
**0.x 版本：**
```csharp
public class GameArchitecture : Architecture
{
protected override void Init()
{
RegisterModel(new PlayerModel());
RegisterSystem(new GameplaySystem());
}
}
// 同步初始化
var architecture = new GameArchitecture();
architecture.Initialize();
```
**1.x 版本：**
```csharp
public class GameArchitecture : Architecture
{
protected override void Init()
{
RegisterModel(new PlayerModel());
RegisterSystem(new GameplaySystem());
}
}
// 推荐使用异步初始化
var architecture = new GameArchitecture();
await architecture.InitializeAsync();
// 或者使用同步初始化（不推荐）
// architecture.Initialize();
```
#### 步骤 4：更新事件注册代码
**0.x 版本：**
```csharp
// 注册事件
this.RegisterEvent<PlayerDiedEvent>(OnPlayerDied);
// 发送事件
this.SendEvent(new PlayerDiedEvent());
```
**1.x 版本：**
```csharp
// 注册事件（API 保持兼容）
this.RegisterEvent<PlayerDiedEvent>(OnPlayerDied);
// 发送事件（API 保持兼容）
this.SendEvent(new PlayerDiedEvent());
// 新增：带优先级的事件注册
this.RegisterEvent<PlayerDiedEvent>(OnPlayerDied, priority: 100);
```
#### 步骤 5：更新命令和查询代码
**0.x 版本：**
```csharp
public class MovePlayerCommand : AbstractCommand
{
public Vector2 Direction { get; set; }
protected override void OnDo()
{
// 执行逻辑
}
}
// 发送命令
this.SendCommand(new MovePlayerCommand { Direction = direction });
```
**1.x 版本：**
```csharp
// 命令 API 保持兼容
public class MovePlayerCommand : AbstractCommand
{
public Vector2 Direction { get; set; }
protected override void OnDo()
{
// 执行逻辑
}
}
// 发送命令（API 保持兼容）
this.SendCommand(new MovePlayerCommand { Direction = direction });
// 新增：异步命令支持
public class LoadDataCommand : AbstractAsyncCommand
{
protected override async Task OnDoAsync()
{
await Task.Delay(100);
}
}
```
#### 步骤 6：更新 IOC 容器使用
**0.x 版本：**
```csharp
// 注册服务
RegisterUtility(new StorageUtility());
// 获取服务
var storage = this.GetUtility<StorageUtility>();
```
**1.x 版本：**
```csharp
// 注册服务（API 保持兼容）
RegisterUtility(new StorageUtility());
// 获取服务（API 保持兼容）
var storage = this.GetUtility<StorageUtility>();
// 新增：按优先级获取服务
var storages = this.GetUtilities<IStorageUtility>();
var primaryStorage = storages.FirstOrDefault();
```
#### 步骤 7：更新协程代码
**0.x 版本：**
```csharp
// 启动协程
var handle = CoroutineHelper.Start(MyCoroutine());
// 等待协程
yield return new WaitForCoroutine(handle);
```
**1.x 版本：**
```csharp
// 启动协程（API 保持兼容）
var handle = CoroutineHelper.Start(MyCoroutine());
// 等待协程（API 保持兼容）
yield return new WaitForCoroutine(handle);
// 新增：协程分组和优先级
var handle = CoroutineHelper.Start(
MyCoroutine(),
group: "gameplay",
priority: CoroutinePriority.High
);
```
### API 变更详解
#### 废弃的 API
以下 API 在 1.0 版本中已被移除：
##### 1. 同步命令查询扩展（已废弃）
**0.x 版本：**
```csharp
// 这些方法在 1.0 中已移除
this.SendCommandSync(command);
this.SendQuerySync(query);
```
**1.x 版本：**
```csharp
// 使用标准方法
this.SendCommand(command);
this.SendQuery(query);
// 或使用异步方法
await this.SendCommandAsync(command);
await this.SendQueryAsync(query);
```
##### 2. 旧版事件 API（已废弃）
**0.x 版本：**
```csharp
// 旧版事件注册方式
EventBus.Register<MyEvent>(handler);
```
**1.x 版本：**
```csharp
// 使用新的事件注册方式
this.RegisterEvent<MyEvent>(handler);
// 或使用事件总线
this.GetEventBus().Register<MyEvent>(handler);
```
##### 3. 直接访问 IOC 容器（已限制）
**0.x 版本：**
```csharp
// 直接访问容器
var container = architecture.Container;
container.Register<IService, ServiceImpl>();
```
**1.x 版本：**
```csharp
// 使用架构提供的注册方法
architecture.RegisterUtility<IService>(new ServiceImpl());
// 或在 Init 方法中注册
protected override void Init()
{
RegisterUtility<IService>(new ServiceImpl());
}
```
#### 新增的 API
##### 1. 优先级支持
```csharp
// 事件优先级
this.RegisterEvent<MyEvent>(handler, priority: 100);
// 服务优先级
RegisterUtility<IService>(service, priority: 10);
// 协程优先级
CoroutineHelper.Start(routine, priority: CoroutinePriority.High);
```
##### 2. 异步初始化增强
```csharp
// 异步初始化架构
await architecture.InitializeAsync();
// 等待架构就绪
await architecture.WaitUntilReadyAsync();
// 异步初始化组件
public class MyModel : AbstractModel, IAsyncInitializable
{
public async Task InitializeAsync()
{
await LoadDataAsync();
}
}
```
##### 3. 事件过滤和统计
```csharp
// 事件过滤
this.RegisterEvent<MyEvent>(handler, filter: e => e.IsValid);
// 事件统计
var stats = eventBus.GetStatistics();
Console.WriteLine($"Total events: {stats.TotalEventsSent}");
```
##### 4. 协程分组管理
```csharp
// 创建协程组
var handle = CoroutineHelper.Start(
routine,
group: "ui-animations"
);
// 暂停协程组
CoroutineHelper.PauseGroup("ui-animations");
// 恢复协程组
CoroutineHelper.ResumeGroup("ui-animations");
// 停止协程组
CoroutineHelper.StopGroup("ui-animations");
```
### 配置变更
#### 架构配置
**0.x 版本：**
```csharp
var architecture = new GameArchitecture();
```
**1.x 版本：**
```csharp
// 使用配置对象
var config = new ArchitectureConfiguration
{
ArchitectureProperties = new ArchitectureProperties
{
StrictPhaseValidation = true,
AllowLateRegistration = false
},
LoggerProperties = new LoggerProperties
{
MinimumLevel = LogLevel.Information
}
};
var architecture = new GameArchitecture(configuration: config);
```
#### 日志配置
**0.x 版本：**
```csharp
// 使用默认日志
```
**1.x 版本：**
```csharp
// 配置日志系统
var logConfig = new LoggingConfiguration
{
MinimumLevel = LogLevel.Debug,
Appenders = new List<ILogAppender>
{
new ConsoleAppender(),
new FileAppender("logs/game.log")
},
Filters = new List<ILogFilter>
{
new LogLevelFilter(LogLevel.Warning),
new NamespaceFilter("GFramework.*")
}
};
```
### 依赖变更
#### NuGet 包更新
| 包名 | 0.x 版本 | 1.x 版本 | 变更说明 |
|------------------------------------------|--------|--------|----------|
| Microsoft.Extensions.DependencyInjection | 8.0.0 | 10.0.3 | 升级到最新版本 |
| Arch | 1.x | 2.1.0 | ECS 框架升级 |
| Arch.System | 1.0.x | 1.1.0 | 系统组件升级 |
#### 包拆分
1.0 版本对包结构进行了优化：
**0.x 版本：**
```xml
<PackageReference Include="GeWuYou.GFramework" Version="0.0.200" />
```
**1.x 版本：**
```xml
<!-- 推荐按需引用 -->
<PackageReference Include="GeWuYou.GFramework.Core" Version="1.0.0" />
<PackageReference Include="GeWuYou.GFramework.Core.Abstractions" Version="1.0.0" />
<PackageReference Include="GeWuYou.GFramework.Game" Version="1.0.0" />
<PackageReference Include="GeWuYou.GFramework.Godot" Version="1.0.0" />
```
### 代码迁移工具
#### 自动化迁移工具
GFramework 提供了迁移工具来自动化部分迁移工作：
```bash
# 安装迁移工具
dotnet tool install -g GFramework.MigrationTool
# 运行迁移分析
gframework-migrate analyze --project YourProject.csproj
# 执行自动迁移
gframework-migrate apply --project YourProject.csproj --target-version 1.0.0
# 生成迁移报告
gframework-migrate report --output migration-report.html
```
#### 手动迁移检查清单
使用以下清单确保完整迁移：
- [ ] 更新所有 NuGet 包到 1.0.0
- [ ] 更新命名空间引用
- [ ] 替换废弃的 API
- [ ] 更新架构初始化代码
- [ ] 更新配置代码
- [ ] 运行所有单元测试
- [ ] 运行集成测试
- [ ] 执行性能测试
- [ ] 更新文档和注释
- [ ] 代码审查
### 测试迁移
#### 单元测试更新
**0.x 版本：**
```csharp
[Test]
public void TestArchitectureInit()
{
var architecture = new TestArchitecture();
architecture.Initialize();
Assert.That(architecture.CurrentPhase, Is.EqualTo(ArchitecturePhase.Ready));
}
```
**1.x 版本：**
```csharp
[Test]
public async Task TestArchitectureInit()
{
var architecture = new TestArchitecture();
await architecture.InitializeAsync();
Assert.That(architecture.CurrentPhase, Is.EqualTo(ArchitecturePhase.Ready));
}
```
#### 集成测试更新
**0.x 版本：**
```csharp
[Test]
public void TestGameFlow()
{
var game = new GameArchitecture();
game.Initialize();
game.SendCommand(new StartGameCommand());
var score = game.SendQuery(new GetScoreQuery());
Assert.That(score, Is.EqualTo(0));
}
```
**1.x 版本：**
```csharp
[Test]
public async Task TestGameFlow()
{
var game = new GameArchitecture();
await game.InitializeAsync();
await game.SendCommandAsync(new StartGameCommand());
var score = await game.SendQueryAsync(new GetScoreQuery());
Assert.That(score, Is.EqualTo(0));
}
```
## 常见问题
### 编译错误
#### 问题 1：命名空间找不到
**错误信息：**
```
error CS0246: The type or namespace name 'IArchitecture' could not be found
```
**解决方案：**
```csharp
// 添加正确的命名空间引用
using GFramework.Core.Abstractions.Architecture;
```
#### 问题 2：方法签名不匹配
**错误信息：**
```
error CS1501: No overload for method 'RegisterEvent' takes 1 arguments
```
**解决方案：**
```csharp
// 0.x 版本
this.RegisterEvent&lt;MyEvent&gt;(handler);
// 1.x 版本（兼容）
this.RegisterEvent&lt;MyEvent&gt;(handler);
// 1.x 版本（带优先级）
this.RegisterEvent&lt;MyEvent&gt;(handler, priority: 100);
```
#### 问题 3：泛型约束不满足
**错误信息：**
```
error CS0311: The type 'MyType' cannot be used as type parameter 'T'
in the generic type or method. There is no implicit reference conversion
from 'MyType' to 'GFramework.Core.Abstractions.IModel'.
```
**解决方案：**
```csharp
// 确保类型实现了正确的接口
public class MyModel : AbstractModel, IModel
{
// 实现
}
```
### 运行时错误
#### 问题 1：架构未初始化
**错误信息：**
```
InvalidOperationException: Architecture is not initialized
```
**解决方案：**
```csharp
// 确保在使用前初始化架构
var architecture = new GameArchitecture();
await architecture.InitializeAsync();
await architecture.WaitUntilReadyAsync();
// 然后再使用
this.SendCommand(new MyCommand());
```
#### 问题 2：服务未注册
**错误信息：**
```
InvalidOperationException: Service of type 'IMyService' is not registered
```
**解决方案：**
```csharp
// 在 Init 方法中注册服务
protected override void Init()
{
RegisterUtility&lt;IMyService&gt;(new MyServiceImpl());
}
```
#### 问题 3：事件处理器未触发
**问题描述：**
事件发送后，注册的处理器没有被调用。
**解决方案：**
```csharp
// 确保事件处理器正确注册
var unregister = this.RegisterEvent&lt;MyEvent&gt;(OnMyEvent);
// 确保在对象销毁时注销
protected override void OnDestroy()
{
unregister?.UnRegister();
}
// 检查事件类型是否匹配
this.SendEvent(new MyEvent()); // 确保类型完全一致
```
### 性能问题
#### 问题 1：初始化时间过长
**问题描述：**
架构初始化耗时明显增加。
**解决方案：**
```csharp
// 使用异步初始化
await architecture.InitializeAsync();
// 对于耗时的初始化操作，使用异步方法
public class MyModel : AbstractModel, IAsyncInitializable
{
public async Task InitializeAsync()
{
// 异步加载数据
await LoadDataAsync();
}
}
```
#### 问题 2：事件处理性能下降
**问题描述：**
事件处理速度变慢。
**解决方案：**
```csharp
// 使用事件过滤减少不必要的处理
this.RegisterEvent&lt;MyEvent&gt;(
handler,
filter: e => e.ShouldProcess
);
// 使用优先级控制处理顺序
this.RegisterEvent&lt;MyEvent&gt;(
criticalHandler,
priority: 100
);
```
### 兼容性问题
#### 问题 1：Godot 版本不兼容
**问题描述：**
升级后在 Godot 4.3 中无法运行。
**解决方案：**
```bash
# GFramework 1.0 要求 Godot 4.4+
# 升级 Godot 到 4.4 或更高版本
```
#### 问题 2：.NET 版本不兼容
**问题描述：**
项目使用 .NET 7.0，无法使用 GFramework 1.0。
**解决方案：**
```xml
<!-- 升级项目到 .NET 8.0 或更高版本 -->
<PropertyGroup>
<TargetFramework>net8.0</TargetFramework>
</PropertyGroup>
```
## 回滚方案
如果迁移过程中遇到无法解决的问题，可以按以下步骤回滚：
### 步骤 1：恢复包版本
```bash
# 回滚到 0.x 版本
dotnet add package GeWuYou.GFramework.Core --version 0.0.200
dotnet add package GeWuYou.GFramework.Core.Abstractions --version 0.0.200
dotnet add package GeWuYou.GFramework.Game --version 0.0.200
dotnet add package GeWuYou.GFramework.Godot --version 0.0.200
```
### 步骤 2：恢复代码
```bash
# 从备份分支恢复
git checkout backup-before-migration
# 或从文件系统备份恢复
rm -rf YourProject
cp -r YourProject-backup YourProject
```
### 步骤 3：验证回滚
```bash
# 清理构建缓存
dotnet clean
rm -rf bin obj
# 重新构建
dotnet build
# 运行测试
dotnet test
```
### 步骤 4：记录问题
创建问题报告，包含：
- 遇到的具体错误
- 错误发生的环境信息
- 复现步骤
- 相关代码片段
提交到 [GitHub Issues](https://github.com/GeWuYou/GFramework/issues)。
## 获取帮助
### 官方资源
- **文档中心**：[https://gewuyou.github.io/GFramework/](https://gewuyou.github.io/GFramework/)
- **GitHub 仓库**：[https://github.com/GeWuYou/GFramework](https://github.com/GeWuYou/GFramework)
- **问题追踪**：[https://github.com/GeWuYou/GFramework/issues](https://github.com/GeWuYou/GFramework/issues)
- **讨论区**：[https://github.com/GeWuYou/GFramework/discussions](https://github.com/GeWuYou/GFramework/discussions)
### 社区支持
- 在 GitHub Discussions 中提问
- 查看已有的 Issues 和 Pull Requests
- 参考示例项目和教程
### 商业支持
如需专业的迁移支持服务，请联系项目维护团队。
## 附录
### A. 完整的 API 对照表
| 0.x API | 1.x API | 说明 |
|-----------------------------|----------------------------------------|------------|
| `architecture.Initialize()` | `await architecture.InitializeAsync()` | 推荐使用异步初始化 |
| `this.SendCommandSync()` | `this.SendCommand()` | 移除 Sync 后缀 |
| `this.SendQuerySync()` | `this.SendQuery()` | 移除 Sync 后缀 |
| `EventBus.Register()` | `this.RegisterEvent()` | 使用扩展方法 |
| `Container.Register()` | `RegisterUtility()` | 使用架构方法 |
### B. 迁移时间估算
| 项目规模 | 预估时间 | 说明 |
|---------------|-------|--------------|
| 小型（&lt;10k 行） | 1-2 天 | 主要是包更新和测试 |
| 中型（10k-50k 行） | 3-5 天 | 需要代码审查和重构 |
| 大型（&gt;50k 行） | 1-2 周 | 需要分模块迁移和充分测试 |
### C. 相关资源
- [架构设计文档](./core/architecture.md)
- [事件系统文档](./core/events.md)
- [命令查询文档](./core/command.md)
- [协程系统文档](./core/coroutine.md)
- [最佳实践](./best-practices/architecture-patterns.md)
---
**文档版本**：1.0.0
**最后更新**：2026-03-07
**许可证**：Apache 2.0