配置选项

AsyncLoaderOptions 的所有选项如下。

选项总览

选项	类型	默认值	说明
autostart	boolean	true	是否构造时自动加载；设为 false 改为首次 get() 懒触发
cache	number	0	缓存有效期（毫秒）。=0 不缓存，>0 为有效期
hash	string	自动生成	加载任务的唯一标识（hash），兼作缓存键；cache>0 但未提供时自动生成实例级 hash
abortSignal	AbortSignal	—	外部中止信号，触发时联动中止加载（且不会触发重试）
timeout	number	—	每次尝试的超时（毫秒），>0 生效；超时视为一次可重试的失败
retry	number	0	失败后的最大重试次数。主动 abort 不重试，超时与业务错误会重试
retryDelay	number	0	每次重试前的等待毫秒数
multiplex	"off" | "restart" | "share"	"off"	按 hash 复用加载器实例（见下）
multiLoaderStrategy	"fallback" | "combine"	"fallback"	多加载器协同策略（loader 为数组且长度 > 1 时生效，见下）
onResults	(results: (T | Error)[], defaultValue: T | undefined) => T	—	combine 策略的结果合并 hook（见下）
defaultValue	T	—	最终失败时 resolve 的兜底值（见下）
storage	IStorage	MapStorage	缓存项的存储后端
onPending	(() => void) | (() => void)[]	—	加载开始时调用（仅实际加载时，缓存命中不触发）
onFulfilled	((result: T) => void) | ((result: T) => void)[]	—	加载成功时调用（缓存命中不触发），result 为加载结果（含 defaultValue 兜底）
onRejected	((error: Error) => void) | ((error: Error) => void)[]	—	加载失败/中止时调用（重试耗尽或主动 abort，缓存命中不触发）

multiplex 取值

• "off"（默认）：各实例独立。
• "restart"：命中同 hash 且正在进行中的加载时，中止该加载并以首个实例的 loader 重新加载（后续 loader 被忽略）。
• "share"：命中同 hash 时完全共享首个实例进行中的加载与结果。

非 off 且未提供 hash 时，基于 loaders 自动生成 hash。详见 实例复用。

multiLoaderStrategy 取值

构造参数 loader 支持传入单个或数组（IAsyncLoader | IAsyncLoader[]）。当为数组且长度 > 1 时，由 multiLoaderStrategy 决定如何编排多个 loader：

• "fallback"（默认）：备用容灾。顺序尝试 loaders，首个成功即停止后续；某 loader 失败则尝试下一个；全部失败才算本次加载失败（可触发 retry 重试整个序列）。
• "combine"：多源合并。所有 loader 并发执行，结果（成功项为 T，失败项为 Error）收集后交给 onResults 合并。

单 loader 时本选项无效（保持原行为）。详见 多加载器。

onResults 要点

• 仅 multiLoaderStrategy="combine" 时调用；fallback 不会调用（即使提供也忽略）。
• results：全部 loader 的结果数组（顺序与 loaders 对应），成功项为 T，失败项为 Error 对象。
• defaultValue：options.defaultValue 配置的兜底值（可能 undefined），供 hook 决定是否兜底。
• 返回合并后的最终结果 T；同步抛错则视为本次加载失败（走 retry / onRejected / defaultValue 终态逻辑）。
• 这是有返回值的转换函数（非事件回调），错误必须传播，不走 onFulfilled/onRejected 的吞错机制。

defaultValue 要点

• 最终失败（业务错误 / 重试耗尽后的超时）时 resolve 该兜底值。
• 显式提供时 falsy 值（0 / "" / null / false）同样生效。
• 对主动 abort() 无效（仍 reject AbortError）。
• 兜底值不写入缓存。详见 错误兜底。

回调说明

onPending / onFulfilled / onRejected 均支持单个函数或函数数组；数组形式会并发调用，回调内部抛出的错误会被忽略。

timeout 的两层语义

options.timeout 是每次尝试的加载超时（可重试）；而 get(args) 透传的 args.timeout 是等待超时，两者语义不同。