alova-client-usage

Alova 客户端用法

关于服务端（Node/Bun/Deno），请参阅 alova-server skill。 关于 alova openapi 的用法，请参阅 alova-openapi skill。

如何使用此 Skill

此 skill 分为两个层次：

1. 此文件 — 快速参考索引：介绍每个 API 的作用及其适用场景。请先阅读此文件。
2. 官方文档（按需获取） — 如需了解完整选项、边缘情况或不熟悉的 API，请获取各章节列出的 URL，以查阅最新且准确的信息。

在回答有关特定 API 选项或行为的问题前，务必先获取官方文档 — alova 正在积极开发中，在线文档比训练数据更可靠。

---

安装与设置

请参阅 references/SETUP.md，了解：

• 安装
• 创建 Alova 实例
• 特定框架的 StatesHook
• 请求适配器
• 全局请求共享与超时
• 创建有关基于 Token 的登录、登出和 Token 刷新的拦截器
• 缓存日志记录器
• 限制方法快照数量

创建方法实例

alova 总共提供 7 种请求类型。

实例创建函数	参数
GET	alovaInstance.Get(url[, config])
POST	alovaInstance.Post(url[, data[, config]])
PUT	alovaInstance.Put(url[, data[, config]])
DELETE	alovaInstance.Delete(url[, data[, config]])
HEAD	alovaInstance.Head(url[, config])
OPTIONS	alovaInstance.Options(url[, config])
PATCH	alovaInstance.Patch(url[, data[, config]])

参数说明：

• url 是请求路径；
• data 是请求体数据；
• config 是请求配置对象，包含请求头、params 参数、请求行为参数等配置；

实际上，调用上述函数并不会发送请求，而是创建一个方法实例，它是一个 PromiseLike 实例。你可以像使用 Promise 对象一样，使用 then、catch、finally 方法或 await 来发送请求。

alovaInstance
  .Get('/api/user')
  .then((response) => {
    // ...
  })
  .catch((error) => {
    // ...
  })
  .finally(() => {
    // ...
  });

// or
try {
  await userMethodInstance;
} catch (error) {
  // ...
} finally {
  // ...
}

如需了解完整的方法实例 API，请参阅方法文档。

方法元数据

为特定方法实例添加额外信息，以便在全局拦截器中识别它们或提供额外信息，例如返回不同的响应、避免显示全局 toast。请设置方法元数据。参见 → 方法元数据。

核心 Hooks

在组件中使用这些 hooks，而不是手动实现常见的请求模式。

从 alova/client 导入。

Hook	使用场景	文档
useRequest	在挂载时获取数据，或在用户操作（点击按钮、提交表单）时触发一次	文档
useWatcher	在响应式状态变化时自动重新获取数据（搜索输入、筛选器、标签页、页面）	文档
useFetcher	在后台静默预加载数据，或从拥有该数据的组件外部刷新数据	文档

业务策略钩子

从 alova/client 导入。

场景	钩子	主要能力	文档
分页列表 / 无限滚动	usePagination	自动管理分页、预加载下一页 / 上一页、乐观插入 / 移除 / 替换	文档
表单提交（任意复杂度）	useForm	草稿持久化、多步骤状态共享、自动重置	文档
轮询 / 焦点切换 / 重新连接时刷新	useAutoRequest	可配置触发条件、节流	文档
发送短信、邮件验证码 + 倒计时	useCaptcha	内置冷却计时器	文档
跨组件请求触发	actionDelegationMiddleware + accessAction	无需逐层传递 props 或使用全局状态	文档
链式依赖请求	useSerialRequest / useSerialWatcher	每一步都会接收上一步的结果	文档
指数退避重试	useRetriableRequest	可配置重试次数 + 随机抖动	文档
带进度显示的文件上传	useUploader	并发限制、进度事件	文档
服务器发送事件	useSSE	响应式 data + readyState	文档
无缝数据交互	useSQRequest	与 UI 交互时可立即响应，无需等待	文档

缓存策略

Alova 具有 L1（内存）和 L2（持久化 / 恢复）层，并支持自动请求共享（去重）。

全局和指定范围内设置缓存

• 页面内快速访问，刷新后重置；刷新页面后仍可用／离线优先；禁用缓存 -> 参见 缓存模式。
• 变更后自动失效：在 GET 请求上设置 hitSource，在变更 Method 上设置 name -> 参见 自动使缓存失效。
• 手动使缓存失效 -> 参见 手动使缓存失效。
• 设置和查询缓存 -> 参见 操作缓存。

关键规则：优先使用 hitSource 自动使缓存失效——无需编写命令式代码，还能解耦组件。

Hooks 中间件

中间件允许你拦截并控制 useHooks 中的请求行为。常见场景包括：

• 在特定条件下忽略请求
• 转换响应数据
• 更改请求方法或强制绕过缓存
• 错误处理（捕获或抛出自定义错误）
• 控制响应延迟
• 修改响应式状态（loading、data 等）
• 实现请求重试逻辑
• 完全控制 loading 状态

完整的中间件 API 和示例，请参见 请求中间件。

模拟请求

为特定请求设置模拟数据。参见 模拟请求。

最佳实践

• 为不同的域、API 或环境创建多个 alova 实例。
• 提供一个用于统一存放请求函数的文件夹，让代码井然有序。
• 优先在组件中使用 hooks，在其他地方直接调用 method 实例。
• 优先使用链式调用来绑定 hooks 事件，例如 useRequest(method).onSuccess(...).onError(...)。

常见问题

问题	解决方法
useWatcher 的第一个参数是 Method 实例	始终用以下方式包装：() => method(state.value)
updateState 不起作用且没有提示	仅当所属组件已挂载时才有效；否则使用 setCache
在 v3 中同步调用缓存操作	await invalidateCache / setCache / queryCache
useWatcher 挂载时不发起请求	设置 immediate: true

TypeScript

在 Method 实例上标注响应数据结构——hooks 会自动推断：

const getUser = (id: number) => alovaInstance.Get<User>(`/users/${id}`);
// or need to transform data.
const getUser = (id: number) =>
  alovaInstance.Get(`/users/${id}`, {
    transform(user: User) {
      return {
        ...user,
        name: user.lastName + ' ' + user.firstName,
      };
    },
  });

const { data } = useRequest(getUser(1)); // data: Ref<User>

📄 TypeScript 文档

SSR 组件示例

alova 可以在服务端和客户端管理 API，而不是分别在服务端和客户端使用不同的请求方案。

CSR

通常，alova 的 hooks 仅在客户端生效。

// won't send request in server side.
useRequest(getUser(1));

Nextjs

直接在服务端组件中 await method 实例。

const App = async () => {
  const data = await alovaInstance.Get('/todo/list');
  // then ... code
  return <div>{...}</div>;
};
export default App;

Nuxt

在 alova 的 hooks 前使用 await，可以让两端的状态保持同步，效果与 useFetch 相同。

const { data } = await useRequest(getUser(1));

Sveltekit

直接在 +page.server.[j|ts] 中 await method 实例。

/** @type {import('./$types').PageServerLoad} */
export async function load({ params }) {
  return {
    list: alovaInstance.Get('/todo/list'),
  };
}

自定义适配器

如果所有预设适配器都无法满足需求，可以自定义适配器。

• 自定义请求适配器
• 自定义存储适配器
• 自定义客户端策略 Hook

自定义 Method Key

通过设置 key 更改缓存、请求共享和状态更新的匹配策略。参见 自定义 Method Key。