use_request library

Flutter 的 useRequest 风格异步请求管理库。

统一从该入口引入： import 'package:use_request/use_request.dart';

Classes

AppFocusManager

聚焦事件管理器（应用生命周期） 使用 WidgetsBindingObserver 监听应用进入前台与后台

CacheCoordinator<T>

简单的缓存策略辅助：基于 cacheKey 进行去重和 SWR 再验证。

Debouncer<T>

防抖工具类

DioHttpAdapter

Dio HTTP 适配器

HttpRequestConfig

HTTP 请求配置

LoadingDelayController

loading 延迟控制器 用于避免非常快速的请求出现闪烁式的 loading

OfflineDetector

占位的离线检测接口，可由外部接入 Connectivity 等实现。

PaginationHelpers

提供基于 page/pageSize 的辅助生成器

PendingRequestEntry<T>

进行中的请求条目（用于请求去重）

PollingController<T>

轮询控制器

RequestCache

请求缓存管理器（静态单例）

RequestCacheEntry<T>

请求缓存条目

RetryConfig

重试配置类

RetryExecutor<T>

失败自动重试执行器

Throttler<T>

节流工具类

UseRequestBuilder<TData, TParams>

提供 useRequest 能力的组件

UseRequestNotifier<TData, TParams>

请求状态管理的 StateNotifier 实现

UseRequestObserver

全局请求观察者接口

UseRequestOptions<TData, TParams>

useRequest 的配置项

UseRequestResult<TData, TParams>

useRequest 的返回结果对象

UseRequestState<TData, TParams>

useRequest 内部状态

Enums

HttpMethod

HTTP 请求方法枚举

Mixins

UseRequestMixin<TData, TParams>

在 ConsumerStatefulWidget 中以 Hook 风格使用的 Mixin

Extensions

UseRequestResultExtension on UseRequestState<TData, TParams>

便捷状态判断扩展

Functions

clearAllCache() → void

清空所有缓存（便捷函数）

clearCacheEntry(String key) → void

清除指定键的缓存（便捷函数）

createDebouncer<T>(Duration duration, {bool leading = false, bool trailing = true, Duration? maxWait}) → Debouncer<T>

创建防抖器（工厂函数）

createDioService<T>(DioHttpAdapter adapter, {T transformer(Response response)?}) → Future<T> Function(HttpRequestConfig config)

创建与 useRequest 集成的 Service 函数

createFocusManager({required VoidCallback onFocus, VoidCallback? onBlur}) → AppFocusManager

创建聚焦管理器的函数式辅助

createLinkedCancelToken([CancelToken? external]) → CancelToken

创建一个与外部 CancelToken 关联的内部 CancelToken。 内部 token 会在外部被取消时同步取消，但不会反向取消外部 token， 避免复用外部 token 被频繁 cancel 后失效的问题。

createPolling<T>({required Duration interval, required Future<T> action(), bool shouldPoll()?, void onSuccess(T result)?, void onError(dynamic error)?}) → PollingController<T>

创建轮询控制器（工厂函数）

createThrottler<T>(Duration duration, {bool leading = true, bool trailing = true, Duration? maxWait}) → Throttler<T>

创建节流器（工厂函数）

createUseRequestProvider<TData, TParams>({required Service<TData, TParams> service, UseRequestOptions<TData, TParams>? options}) → StateNotifierProvider<UseRequestNotifier<TData, TParams>, UseRequestState<TData, TParams>>

useRequest 的 Provider 工厂 用法示例：

executeWithLoadingDelay<T>({required Future<T> action(), required Duration delay, required void onLoadingChange(bool loading)}) → Future<T>

包装一个异步操作，自动处理 loading 延迟

executeWithRetry<T>(Future<T> action(), {int maxRetries = 3, Duration retryInterval = const Duration(seconds: 1), bool shouldRetry(dynamic error)?, CancelToken? cancelToken, void onRetry(int attempt, dynamic error)?, bool exponential = false}) → Future<T>

执行带重试逻辑的异步函数（函数式 API）

getCache<T>(String key, {Duration? cacheTime}) → RequestCacheEntry<T>?

获取缓存数据（便捷函数）

getPendingCache<T>(String key) → Future<T>?

获取进行中的请求（便捷函数）

notifyRequestObserverCacheHit(String cacheKey, bool isStale) → void

notifyRequestObserverCancel(String key) → void

notifyRequestObserverError(String key, Object error, Object? params) → void

notifyRequestObserverFinally(String key, Object? params) → void

notifyRequestObserverMutate(String key, Object? oldData, Object? newData) → void

notifyRequestObserverRequest(String key, Object? params) → void

notifyRequestObserverSuccess(String key, Object? data, Object? params) → void

setCache<T>(String key, T data) → void

设置缓存数据（便捷函数）

setPendingCache<T>(String key, Future<T> future) → void

存储进行中的请求（便捷函数）

useRequest<TData, TParams>(Service<TData, TParams> service, {UseRequestOptions<TData, TParams>? options}) → UseRequestResult<TData, TParams>

useRequest Hook 实现 借鉴 ahooks 的数据请求能力并结合 Dart/Flutter 特性

Typedefs

OnBefore<TParams> = void Function(TParams params)

请求开始前的回调

OnError<TParams> = void Function(dynamic error, TParams params)

请求失败回调

OnFinally<TData, TParams> = void Function(TParams params, TData? data, dynamic error)

请求完成回调（无论成功或失败都会触发）

OnRetryAttempt<TParams> = void Function(int attempt, dynamic error)

重试尝试回调

OnSuccess<TData, TParams> = void Function(TData data, TParams params)

请求成功回调

PageDataMerger<TData> = TData Function(TData? previous, TData next)

PageHasMore<TData> = bool Function(TData? data)

PageParamBuilder<TParams, TData> = TParams Function(int page, int pageSize, TParams? origin)

Service<TData, TParams> = Future<TData> Function(TParams params)

Service 函数类型，负责实际的异步操作（通常是网络请求）

Exceptions / Errors

DebounceCancelledException

防抖取消异常

RequestCancelledException

当请求被取消时抛出

RequestSupersededException

当请求被更新的请求覆盖时抛出

RetryCancelledException

重试取消异常

ThrottleCancelledException

节流取消异常