为异步操作实现统一进度反馈机制，关键在于解耦任务执行与进度通知，通过IProgress<T>契约抽象数据流，支持百分比、阶段码等格式，内置防抖限频，并桥接跨平台线程上下文，严格区分进度与状态语义。
为异步操作实现统一的进度反馈机制，关键在于解耦“任务执行”与“进度通知”，并建立一套可复用、低开销、跨平台适配的中间层。不需要为每个异步逻辑重复写回调或轮询，而是通过标准化接口把进度数据流抽象出来。
定义统一的进度契约（IProgress<T>）
所有异步方法都接受一个 IProgress<T> 参数（如 IProgress<float> 或 IProgress<int>），这是 .NET 生态及多数现代框架（Unity/ASP.NET/Java 封装层）广泛采用的约定。它只暴露一个 Report(T value) 方法，不绑定具体实现，让调用方自由决定如何消费进度——打印日志、更新 UI 进度条、广播 WebSocket 事件等。
- 避免直接传入 UI 控件或事件委托，防止内存泄漏和线程上下文依赖
- 在 Unity 中优先使用
UniTask.Progress工厂创建结构体实例，规避 GC 压力 - Java 场景可用自定义
ProgressCallback<Integer>接口 + Lambda 实现类似语义
封装进度驱动型异步任务模板
把“分段执行 + 定期上报”逻辑提取成通用模式。例如一个文件加载任务，不应在业务代码里手动写 10 次 progress.Report(10)，而应由模板自动按步骤或字节比例计算并触发。
- 支持百分比（0–100）、阶段码（"init→fetch→parse→done"）、或原始数值（"已处理 237/1024 条记录"）三种常用格式
- 内置防抖：如 Unity 的
Progress.CreateOnlyValueChanged，仅当值真正变化时才通知，跳过连续相同的 0.999 → 0.9995 - 可选限频：对高频上报（如每毫秒更新）做时间窗口合并，避免 UI 频繁重绘
桥接前后端与跨线程上下文
进度需穿透异步边界和线程边界，尤其在 Web 或混合架构中：
- 后端（如 ASP.NET）用 SignalR Hub 主动推送进度到指定客户端连接，而非轮询 API
- HarmonyOS / Android 等平台通过
RestoreCallback.onProcess()或Handler.post()确保回调回到主线程更新 UI - 前端监听时，用单个 WebSocket 连接接收多种任务的进度事件，靠
task_id字段路由到对应组件
状态与进度分离，避免语义混淆
进度（progress）≠ 状态（status）。用户需要知道“做到哪了”，而不是“现在是什么状态”。因此设计时要明确区分：
- 进度值只反映当前完成比例或阶段性进展（如 65%、"第3步/共5步"）
- 独立的状态机管理整体生命周期：
Pending → Running → Completed / Failed / Canceled - 失败时仍应报告最终进度（如“已下载 82MB，剩余 18MB 时网络中断”），比单纯显示 “Error” 更具信息量
