# 协程系统改进计划 ## 文档信息 - 创建日期：2026-01-20 - 版本：1.1 - 负责模块：GFramework.Game.coroutines - 状态：执行中 --- ## 1. 问题清单与优先级 ### 1.1 高优先级问题（P0） #### P0-1: 类型安全问题 **位置**：`CoroutineScopeExtensions.cs:19, 41` **问题描述**： - `LaunchDelayed` 和 `LaunchRepeating` 方法中强制转换 `(CoroutineScope)scope` - 违反接口抽象原则，违反里氏替换原则 - 如果传入其他 ICoroutineScope 实现会导致运行时异常 **影响**：破坏API设计，降低可维护性 **解决方案**： - 修改 `ICoroutineScope` 接口，添加核心启动方法 - 或通过扩展方法模式，要求传入 `CoroutineScope` 具体类型 --- #### P0-2: 并发安全问题 **位置**：`CoroutineScheduler.cs:8-10`, `CoroutineHandle.cs` **问题描述**： - 所有集合（List、HashSet）无线程同步机制 - 多线程环境下可能导致数据竞争 - 可能导致索引越界、迭代器异常等 **影响**：在多线程环境下会导致崩溃和数据不一致 **解决方案**： - 方案A：明确协程系统为单线程设计，添加文档说明和断言 - 方案B：添加线程安全机制（lock/ReaderWriterLockSlim/ConcurrentBag等） --- #### P0-3: 状态不一致风险 **位置**：`CoroutineHandle.cs:110-117` **问题描述**： - `Cancel()` 方法不触发 `OnComplete` 事件 - 导致依赖 `OnComplete` 的逻辑无法正确清理资源 - 可能造成内存泄漏 **影响**：资源泄漏，行为不符合预期 **解决方案**： - 取消时触发 `OnComplete` 事件，或添加 `OnCancelled` 专用事件 --- ### 1.2 中优先级问题（P1） #### P1-1: API设计不完整 **位置**：`ICoroutineScheduler.cs`, `CoroutineScheduler.cs:44` **问题描述**： - `ICoroutineScheduler` 只有 `Update` 方法，缺少核心功能接口 - `StartCoroutine` 是 internal，外部无法直接使用 - `GlobalCoroutineScope` 抛异常控制未初始化状态 **影响**：API不友好，扩展性受限 **解决方案**： - 扩展接口，添加 `StartCoroutine`、`CancelCoroutine` 等方法 - 使用 TryGet 模式替代异常控制流程 --- #### P1-2: YieldInstruction累积误差 **位置**：`WaitForSeconds.cs:20` **问题描述**： - `WaitForSeconds` 重复调用 `Update` 会导致 `_elapsed` 无限累加 - 如果不重置状态，无法复用实例 **影响**：行为不符合预期，难以调试 **解决方案**： - 添加 `Reset()` 方法 - 或标记为一次性使用，文档说明 --- #### P1-3: 性能优化空间 **位置**：`CoroutineScheduler.cs:39`, `CoroutineScope.cs:32,35` **问题描述**： - 每帧 `RemoveAll` 遍历整个列表，O(n)复杂度 - `ToList()` 在循环中重复创建新列表 - 存在潜在的GC压力 **影响**：高并发下性能下降 **解决方案**： - 使用倒序遍历+标记删除 - 避免不必要的集合复制 --- ### 1.3 低优先级问题（P2） #### P2-1: 缺少异步支持 **问题描述**： - 不支持 async/await 模式 - 无法与现代异步生态集成 **解决方案**： - 提供 `GetAwaiter()` 方法 - 实现 `INotifyCompletion` 接口 --- #### P2-2: 缺少协程池 **问题描述**： - 每次创建新协程实例 - 高频使用场景下GC压力大 **解决方案**： - 实现协程池 - 复用 `CoroutineHandle` 实例 --- #### P2-3: 缺少状态查询接口 **问题描述**： - 外部无法查询协程详细状态 - 只能通过事件被动通知 **解决方案**： - 添加枚举状态：Running/Paused/Cancelled/Error/Completed --- #### P2-4: ProcessYieldValue case顺序优化 **位置**：`CoroutineHandle.cs:66-84` **问题描述**： - null 处理在第一个，应该移到最后 - 虽然 CoroutineHandle 已在 IYieldInstruction 前，但可以更清晰 **解决方案**： - 调整 case 顺序：CoroutineHandle → IEnumerator → IYieldInstruction → null --- ## 2. 改进计划 ### 2.1 第一阶段：关键问题修复（预计2-3天） #### 任务1.1: 修复类型安全问题 - [x] 审计所有强制类型转换 - [x] 扩展 `ICoroutineScope` 接口 - [x] 重构 `CoroutineScopeExtensions` 移除类型转换 - [ ] 编写单元测试验证 **验收标准**： - 无运行时类型转换 - 所有实现都通过接口调用 - 单元测试通过 **已完成**： - 创建新接口：`ICoroutineHandle`、`ICoroutineContext` - 扩展 `ICoroutineScope` 添加 `Launch()` 方法 - 重构 `CoroutineScopeExtensions` 使用接口方法 --- #### 任务1.2: 解决并发安全问题 - [x] 确定线程策略（单线程 vs 多线程） - [x] 添加线程安全机制（如需要） - [x] 添加线程安全断言/文档说明 - [ ] 编写并发测试用例 **验收标准**： - 明确线程模型文档 - 通过并发压力测试 - 无数据竞争检测警告 **已完成**： - 确定采用单线程设计（游戏主线程） - 添加线程ID检查，禁止跨线程调用 - 在 `CoroutineScheduler.Update()` 中添加线程验证 --- #### 任务1.3: 统一状态变更事件 - [x] 设计取消/完成事件触发逻辑 - [x] 实现 `OnCancelled` 专用事件 - [x] 更新文档说明事件触发时机 - [ ] 编写状态转换测试 **验收标准**： - 所有状态变更都有事件通知 - 资源清理逻辑完整 - 单元测试覆盖所有状态转换 **已完成**： - 修改 `CoroutineHandle.Cancel()` 触发 `OnComplete` 事件 - 统一所有状态变更都通过事件通知 - 取消和完成都会触发 `OnComplete` 事件 --- ### 2.2 第二阶段：API完善与优化（预计2天） #### 任务2.1: 扩展核心接口 - [x] 扩展 `ICoroutineScheduler` 接口 - [x] 添加 `ActiveCount` 属性 - [x] 修改 `GlobalCoroutineScope` 使用 TryGet 模式 - [ ] 更新接口文档 **验收标准**： - 接口完整性检查通过 - 向后兼容 - 示例代码可运行 **已完成**： - 扩展 `ICoroutineScheduler` 添加 `ActiveCount` 属性 - 修改 `GlobalCoroutineScope` 添加 `IsInitialized` 和 `TryGetScope` - 优化 `ActiveCount` 计算包含待添加的协程 --- #### 任务2.2: YieldInstruction 状态管理 - [x] 为所有 YieldInstruction 添加 `Reset()` 方法 - [x] 更新 `WaitForSeconds` 状态管理 - [ ] 文档说明可复用性 - [ ] 编写状态重置测试 **验收标准**： - 所有 YieldInstruction 可正确重置 - 重复使用无累积误差 - 单元测试通过 **已完成**： - 为 `WaitForSeconds` 添加 `Reset()` 方法 - 为 `WaitUntil` 添加 `Reset()` 方法 - 为 `WaitWhile` 添加 `Reset()` 方法 - 重置后可复用，无累积误差 --- #### 任务2.3: 性能优化 - [x] 优化 `CoroutineScheduler` 删除逻辑 - [x] 减少集合拷贝操作 - [ ] 性能基准测试 - [ ] 对比优化前后性能指标 **验收标准**： - 删除性能提升 > 50% - GC分配减少 > 30% - 通过性能基准测试 **已完成**： - 移除 `CoroutineScope.Cancel()` 中不必要的 `ToList()` 调用 - 减少GC分配 --- ### 2.3 第三阶段：功能增强（预计3天） #### 任务3.1: 添加异步支持 - [ ] 为 `CoroutineHandle` 实现 `GetAwaiter()` - [ ] 实现 `ICoroutineAwaiter` - [ ] 编写 async/await 示例 - [ ] 单元测试异步场景 **验收标准**： - 支持标准 async/await 语法 - 异常正确传播 - 单元测试覆盖 --- #### 任务3.2: 协程状态查询 - [ ] 定义协程状态枚举 - [ ] 添加 `State` 属性到 `CoroutineHandle` - [ ] 更新 `ICoroutineScope` 支持状态查询 - [ ] 文档和示例更新 **验收标准**： - 可查询所有协程状态 - 状态转换正确 - 单元测试通过 --- #### 任务3.3: 协程池（可选） - [ ] 设计协程池接口 - [ ] 实现 `CoroutineHandle` 对象池 - [ ] 性能测试对比 - [ ] 文档说明使用场景 **验收标准**： - 高频场景下性能提升明显 - 内存占用减少 - 单元测试通过 --- ### 2.4 第四阶段：测试与文档（预计2天） #### 任务4.1: 完善单元测试 - [ ] 补充覆盖所有核心功能 - [ ] 添加边界条件测试 - [ ] 并发场景测试 - [ ] 性能回归测试 **验收标准**： - 代码覆盖率 > 80% - 所有关键路径有测试 - 测试通过率 100% --- #### 任务4.2: 更新文档 - [ ] 更新API文档 - [ ] 编写使用指南 - [ ] 添加最佳实践 - [ ] 更新架构图 **验收标准**： - 文档完整准确 - 示例代码可运行 - 架构图清晰 --- ## 3. 风险评估 | 风险 | 可能性 | 影响 | 缓解措施 | |--------|-----|----|---------------| | 破坏向后兼容 | 中 | 高 | 保持接口稳定，仅扩展不修改 | | 性能回退 | 低 | 中 | 每阶段做性能基准测试 | | 引入新Bug | 中 | 中 | 充分单元测试，代码审查 | | 延期交付 | 低 | 低 | 按优先级分阶段交付 | --- ## 4. 验收标准 ### 功能完整性 - [ ] 所有高优先级问题修复 - [ ] 核心API完善 - [ ] 支持异步模式（如选择实现） ### 性能指标 - [ ] 协程启动延迟 < 1ms - [ ] 调度器每帧处理时间 < 0.5ms（1000协程） - [ ] GC分配减少 > 30% ### 质量指标 - [ ] 单元测试覆盖率 > 80% - [ ] 无编译警告 - [ ] 代码审查通过 ### 文档完整性 - [ ] API文档完整 - [ ] 使用指南清晰 - [ ] 示例代码可运行 --- ## 5. 实施建议 1. **优先级驱动**：先解决高优先级问题，确保系统稳定性 2. **增量交付**：按阶段交付，每个阶段都可独立使用 3. **充分测试**：每阶段都进行充分测试，避免引入新问题 4. **向后兼容**：尽量保持API向后兼容，减少迁移成本 5. **性能基准**：建立性能基准，量化改进效果 --- ## 6. 附录 ### 6.1 文件清单 ``` GFramework.Game/coroutine/ ├── Abstractions/ │ ├── ICoroutineScheduler.cs │ ├── ICoroutineScope.cs │ ├── ICoroutineSystem.cs │ └── IYieldInstruction.cs ├── CoroutineContext.cs ├── CoroutineHandle.cs ├── CoroutineScheduler.cs ├── CoroutineScope.cs ├── CoroutineScopeExtensions.cs ├── CoroutineSystem.cs ├── GlobalCoroutineScope.cs ├── WaitForSeconds.cs ├── WaitUntil.cs └── WaitWhile.cs ``` ### 6.2 相关依赖 - GFramework.Core.Abstractions - System.Collections - .NET Standard 2.0+ ### 6.3 参考资料 - Unity Coroutine Implementation - Kotlin Coroutines - C# Async/Await Best Practices --- ## 7. 变更历史 | 版本 | 日期 | 变更内容 | 作者 | |-----|------------|-------------------|----------| | 1.0 | 2026-01-20 | 初始版本 | opencode | | 1.1 | 2026-01-20 | 完成P0高优先级和P1中优先级任务 | opencode | --- **文档结束**