（star超过50加快更新英文文档🎉）
（star超过200将解锁官方文档（网站）🎉）
dustbin-react是一个简单，快速的react网络请求库。
数据及垃圾，特别是我这种写后端写的烂的，所以这个项目就叫dustbin-react吧。
本来想把这个项目叫做dustbin(垃圾桶)的，可惜npm名字被dust-bin占用了😮💨。
使用Typescript开发，类型支持友好，能自动映射入参和请求结果类型。
86% 测试覆盖率。核心逻辑 100% 测试覆盖率。
简单的代码就能提供如数据缓存，手动回滚，快速重试等功能。
指定缓存字段后，使用同一个缓存字段的请求可以共享最新的返回数据（目前缓存字段只支持String类型）
react 版本 大于等于 16.8
pnpm add dustbin-react
yarn add dustbin-react
npm install dustbin-reactimport useSimpleQuery from 'dustbin-react';
const result = useSimpleQuery((params:T) => Promise<D>, options);(params:T) => Promise<D>params: 请求入参 T为入参类型
请指明入参类型 确保后续result对象返回的 request requestAsync方法在调用时提示友好
Promise: 返回的Promise对象
请指明Promise对象类型 确保后续result对象返回的 data 数据在使用时提示友好
optionsoptions: 单次请求设置
类型展示
type optiosn = {
loop ? : boolean;
loopInterval ? : number;
cacheKey ? : string;
freshTime ? : number;
retry ? : boolean;
retryCount ? : number;
retryInterval ? : number;
params ? : T;
initializeData ? : CD;
auto: boolean;
use ? : Array<UseItem<T, D>>;
handle ? : {
onSuccess? : (params: T, data: D) => void;
onFail? : (params: T, data: D) => void;
onRetryComplete? : (cacheKey: string, time: number) => void;
onRetry? : (
cacheKey: string,
params: any,
time: number,
counter: number
) => void;
};
}- auto（必填）: 是否在hook挂载时自动请求数据,false的情况下请求将永远不会自动发出（可手动请求）。
- use: 单次请求中间件（可全局设置，后面介绍）。
- cacheKey: 缓存键值（注意: 设置了这个值后自动重试，状态共享等功能才能生效）。
- loop: 启用轮询（启用后将丢弃之前的重试请求）不可同时使用retry和loop。
- loopInterval: 轮询间隔（预估的大体时间，轮询总会在上一次轮询请求完成后才继续。
与数据返回间隔时间一致，将获得最好体验）。 - retry: 是否开启重试（开启后默认请求 1 次）。
- retryInterval: 重试间隔（不会等待上一次请求是否完成）。
- retryCount: 重试次数，到达次数后，停止相同cacheKey下的所有重试请求。
- freshTime: 数据新鲜值，默认30秒，auto 为true的情况下开启。 相同参数的请求，将会使用之前请求成功返回的数据。
- params: 请求需要使用的参数。改变时，将会重新发起请求。
- initializeData: 默认的返回值。
- handle: 事件回调
type handle ={
//请求成功返回数据时
onSuccess ? : (params: T, data: D) => void;
//请求失败返回数据时
onFail ? : (params: T, data: D) => void;
//重试完成时
onRetryComplete ? : (cacheKey: string, time: number) => void;
//每次调用
onRetry ? : (
cacheKey: string,
params: any,
time: number,
counter: number
) => void;
}result返回值result是一个包含下面7个字段的对象。
| 字段名 | 类型 | 介绍 |
|---|---|---|
| data | D | 请求获取到的成功结果，promise.resolve。 |
| error | E | 请求获取到的失败结果，promise.reject （失败并不会覆盖data的内容，并且总是在请求成功后清空） |
| hasRequest | Boolean | 是否进行了第一次请求（无视请求结果） |
| loading | Boolean | 是否正在请求中 |
| rollback | () => void | 手动进行数据回滚 （回滚至上一次请求成功的数据，未设置cacheKey时不会返回） |
| request | (p?:T) => D | 手动同步请求数据，同步更改[data]数据 （传入空值总是会使用 options设置的params对象） |
| requestAsync | (p?:T) => D | 异步请求数据，[data]数据。 (传入空值不会使用options params对象) |
除了上文提到的为每个hook单独设置options参数外
还额外支持全局的请求设置
使用 SimpleQueryConfigProvider在
App.tsx 或其他入口（只能包裹在最外层，全局只能使用一次，在其他组件包裹会产生异常）
import { SimpleQueryConfigProvider } from 'dustbin-react';
export default (params: { cache?: ContextCache; config?: ContextConfig }) => {
return (
<SimpleQueryConfigProvider {...(params || {})}>
<HashRouter>
<Router />
</HashRouter>
</SimpleQueryConfigProvider>
);
};类型展示
export type ContextConfig = {
freshTime?: number;
retry?: boolean;
retryCount?: number;
retryInterval?: number;
loopInterval?: number;
use?: QueryOptions<any, ChildrenPartial<any>, any>['use'];
handle?: {
onSuccess?: (params: any, data: any) => void;
onFail?: (params: any, data: any) => void;
onRetryComplete?: (cacheKey: string, time: number) => void;
};
};
export type ContextCache = {
onCacheDataChange?: (
toLocalStorageObject: [string, RequestParamsCacheType][]
) => void;
setCacheDataWithLocalStorage?: () => [
string,
Record<'pre' | 'last', Record<string, any>>
][];
store?: SimpleQueryStore;
};
说明
SimpleQueryConfigProvider 属性 config
| 字段名 | 类型 | 介绍 |
|---|---|---|
| freshTime | Number | 同单次请求设置，会被单次请求设置覆盖 |
| retry | Boolean | 同单次请求设置，会被单次请求设置覆盖 |
| retryCount | Boolean | 同单次请求设置，会被单次请求设置覆盖 |
| retryInterval | Number | 同单次请求设置，会被单次请求设置覆盖 |
| loopInterval | Number | 同单次请求设置，会被单次请求设置覆盖 |
| use | ((params) => params)[] | 下文介绍 |
| handle | {onSuccess,onFail,onRetryComplete} | 不会被单次设置覆盖， 总是会和单次设置的回调一起执行 |
SimpleQueryConfigProvider 属性 cache
| 字段名 | 类型 | 介绍 |
|---|---|---|
| onCacheDataChange | (cache) => void | 回调，会在每次请求并返回成功数据时执行 |
| setCacheDataWithLocalStorage | () => cache | 初始挂载时执行， 请确保数据结构与 onCacheDataChange 返回的结构一致 |
| store | SimpleQueryStore | 方便测试使用，自定义缓存对象，项目慎用 |
为什么会叫半中间件呢，是因为和普通中间件的执行顺序不同，更符合平日开发的习惯。
你可以简单的认为是一种流程控制的手段。
假如SimpleQueryConfigProvider 的 config 长这样，单次请求设置的options同理。
（注意：单次请求的use字段总是会覆盖全局的use设置）
config={{
freshTime: 30 * 1000,
retryCount: 3,
use: [
(params) => {
return { ...params, stop: false };
},
(params) => {
return { ...params, stop: true };
},
],
}}
程序会依次按use数据内的方法依次按顺序执行。
（上一次的执行结果会当作params传入下一个方法）
// 假如中间件有两个方法
use: [func1，func2]
//那么 在请求前会按顺序执行 func2（func1（params）），请求结果会带入下一个方法充当params，阶段为：before
//请求到成功的数据后， 请求结果依旧会按顺序执行 func2（func1（params）），请求结果会带入下一个方法充当params，阶段为after
//使用时请务必注意阶段是什么 并按阶段进行逻辑拆分
中间件方法会在请求过程中执行两次。
数据请求前，数据请求成功后（注意，请求失败并不会执行）。
你可以通过，返回的stop字段控制是否进行请求，和是否设置最新的data值。
下面是params参数的类型，你可以通过这些参数，或者外置的参数进行流程控制。
| 字段名 | 类型 | 介绍 |
|---|---|---|
| type | 'before' or 'after' | 控制的阶段 before代表数据请求前 |
| stop | Boolean | 是否停止执行下面的流程，true为停止 |
| cacheKey | String | 本次请求使用的缓存字段 |
| params | T | 本次请求使用的请求参数 |
| stage | 'normal' or 'retry' | 请求类型，是重试中的请求，还是普通请求 |
| requestTime | Number | 请求发起的时间 |
| result | D | 请求成功的结果（before阶段始终为undefined） |
下面介绍下内置的优化手段。
- 请求总是按顺序执行的，先请求的数据但是返回的滞后数据会被丢弃，只会保留最后一次请求的数据。
- 相同的参数，在设置auto为true的情况下。会默认有30s的缓存击中。30s内不会发起同样的请求，你可以设置 freshTime 进行覆盖。
- result未使用的字段不会被更新（data，loading，error）减少更新次数
- 全局的状态更新，同一个cacheKey 数据会保持一致，如果需要不一致，你可以更换另一个cacheKey，或者不设置cacheKey。