v3 升级指南

以下是从 alova v2 到 v3 的迁移指南。

1. fetch 适配器导入路径变更:

// v2
import GlobalFetch from 'alova/GlobalFetch';

// v3
import adapterFetch from 'alova/fetch';

2. useRequest/useWatcher/useFetcher 等 hook 导入路径变更:

// v2
import { useRequest } from 'alova';
import { usePagination, useForm } from '@alova/scene-[vue/react/svelte]';

// v3
import { useRequest, usePagination, useForm } from 'alova/client';

3. 缓存模式重新设计，placeholder 模式被移除，可使用 initialData 函数实现相同效果:

// v2
const { data } = useRequest(Getter, {
  placeholder: true
});

// v3
const { data } = useRequest(Getter, {
  initialData() {
    // 设置上一次的响应数据
    const storedData = localStorage.getItem('placeholder-data');
    return JSON.parse(storedData || '{}');

    // 也使用alova的存储适配器
    // return alovaInst.l2cache.get('placeholder-data');
  }
}).onSuccess(({ data, method }) => {
  // 保存响应数据
  localStorage.setItem('placeholder-data', JSON.stringify(data));

  // 也使用alova的存储适配器
  alovaInst.l2cache.set('placeholder-data', data);
});

4. 缓存操作函数变为异步,并支持指定缓存级别:

// v2
setCache(methodInstance, data);
const cache = queryCache(methodInstance);
invalidateCache();

// v3
await setCache(methodInstance, data, { policy: 'all' });
const cache = queryCache(methodInstance);
await invalidateCache(methodInstance);

5. method 快照匹配器使用方式变更:

// v2
invalidateCache('method-name');

// v3
const methodSnapshots = alovaInst.snapshots.match('method-name');
invalidateCache(methodSnapshots);

6. useWatcher 的 sendable 选项被移除,使用 middleware 替代:

// v2
useWatcher(() => method, [xxx], { sendable: () => sendable });

// v3
useWatcher(() => method, [xxx], {
  async middleware(_, next) {
    if (sendable) {
      return next();
    }
  }
});

7. method 的 enableDownload/enableUpload 选项被移除,改为自动判断:

// v2
alova.Get('/api/file', {
  enableDownload: true
});

// v3
alova.Get('/api/file');

8. createAlova 中 responsed 替代 responded:

// v2
createAlova({
  responsed() {
    // ...
  }
});

// v3
createAlova({
  responded() {
    // ...
  }
});

9. errorLogger 参数被移除,错误处理逻辑变更:

// v2
createAlova({
  errorLogger: true
});

// v3
// 不再需要设置,自动处理错误日志

10. updateState 不再支持 method 匹配器，onMatch 钩子被移除:

// v2
updateState('method-name', newState, {
  onMatch: () => {}
});

// v3
const methodSnapshots = alovaInst.snapshots.match('method-name');
updateState(methodSnapshots, newState);

11. getMethodKey 函数导入方式变更:

// v2
import { getMethodKey } from 'alova';

// v3
import { key } from '@alova/shared/function';

12. middleware 中 context.update 函数和装饰函数被移除:

// v2
middleware(({ update }) => {
  update({ loading: true });
});

// v3
middleware(({ proxyStates }) => {
  proxyStates.loading.v = true;
});

13. @alova/vue-options 中 mapWatcher 被移除:

// v2
export default {
  watch: mapWatcher({
    'testRequest.data'() {
      // ...
    }
  })
}

// v3
export default {
  watch: {
    'testRequest.data'() {
      // ...
    }
  }
}

14. usePagination 在 React 中使用方式变更:

// v2
const {
  page: [page, setPage],
  pageSize: [pageSize, setPageSize]
} = usePagination(/*...*/);
setPage(page + 1);

// v3
const { page, pageSize, update } = usePagination(/*...*/);
update({ page: page + 1 });

15. useForm 不再支持直接传入 id 返回缓存的 hookReturns:

// v2
const states = useForm('form-id');

// v3
const { states } = useForm(formData => methodHandler(formData), {
  id: 'form-id'
});

16. SilentMethod 相关方法变为异步:

// v2
silentMethod.replace(newSilentMethod);

// v3
await silentMethod.replace(newSilentMethod);

17. accessAction 新增 silent 参数，没有匹配到时不再抛出错误。

// v2
accessAction('method-name', ({ send }) => {
  send();
});

// v3
accessAction(
  'method-name',
  ({ send }) => {
    send();
  },
  true
);

18. method.__key__ 简化为 method.key:

// v2
method.__key__ = 'custom-key';

// v3
method.key = 'custom-key';

19. method.transformData 简化为 method.transform:

// v2
alova.Get('/api/profile', {
  transformData(data) {
    return data.detail;
  }
});

// v3
alova.Get('/api/profile', {
  transform(data) {
    return data.detail;
  }
});

20. method.localCache 更改为 method.cacheFor:

// v2
alova.Get('/api/profile', {
  localCache: 1000 * 60 * 60
});

// v3
alova.Get('/api/profile', {
  cacheFor: 1000 * 60 * 60
});

21. 所有的 sendArgs 更改为 args:

// v2
onSuccess(({ sendArgs }) => {
  // ...
});

// v3
onSuccess(({ args }) => {
  // ...
});

22. @alova/adapter-uniapp 导出名称修改:

// v2
import { uniappStorageAdapter } from '@alova/adapter-uniapp';

// v3
import { uniappL2CacheAdapter } from '@alova/adapter-uniapp';

23. middleware 中使用 proxyState 访问和修改状态:

// v2
middleware(({ states, update }) => {
  const loading = states.loading;
  update({
    loading: true
  });
});

// v3
middleware(({ proxyStates }) => {
  proxyStates.loading.v = true;
});

24. 事件绑定函数返回自身对象,支持链式调用:

// v2
const { onSuccess, loading, data } = useRequest(method);
onSuccess(() => {
  /*...*/
});

// v3
const { loading, data } = useRequest(method).onSuccess(() => {
  /*...*/
});

25. 使用alova.snapshots.match获取已访问过的 method 实例快照：

// v2
const methodSnapshots = matchSnapshotMethod('method-name');

// V3
const methodSnapshots = alova.snapshots.match('method-name');