进度函数接口规范指南.docxVIP

进度函数接口规范指南

进度函数接口规范指南

进度函数接口规范指南

一、进度函数接口的基础建模与核心语义定义

（1）进度函数的本质不是单纯返回一个数字，而是把异步任务的执行过程转化为可观测、可查询、可恢复的状态流。任何耗时超过单次请求容忍阈值的操作，都不应让调用方在同步连接上盲等，而应先返回一个任务标识与状态查询入口，再由进度函数持续暴露当前阶段、完成比例、已处理量、剩余估算与异常信息。进度值在语义上必须是一个归一化指标，通常约定为百分之零到百分之百之间的闭区间数值，其中零代表尚未开始实质性处理，一百代表终态完成；但进度本身不等于业务结果，调用方不能仅凭进度等于一百就认定成功，必须结合状态字段判断是否处于完成、失败、取消等终态。进度函数内部应维护任务上下文，包括任务标识、所属业务域、发起方、创建时间、最近更新时间、各子阶段权重与已完成的子阶段列表，使得每一次查询都能在分布式多实例环境下返回一致快照，而不是依赖调用方本地记忆拼接状态。

（2）进度模型的第一个核心对象是任务句柄。任务句柄在任务创建时由服务端生成，具备全局唯一性、不可预测性与可追溯性，通常可采用带业务前缀的雪花标识或_uuid组合。句柄一旦下发，就作为后续所有进度查询、取消、重试、结果获取的锚点。句柄本身不应携带敏感参数明文，也不应可被遍历猜测；即便两个请求参数完全一致，只要不是显式幂等复用，就应生成不同句柄以区分