@okcy/alova

基于 alova 的 Vue 3 增强 HTTP 请求层。

封装了请求/响应拦截、全局 loading、401/400/403 错误处理、分页、表单、串行请求等通用逻辑。

安装

pnpm add @okcy/alova

快速开始

import { createAlova, alovaDefaultOptions } from "@okcy/alova";
import { createHookHandler, createMethodHandler } from "@okcy/alova";

// 1. 创建 alova 实例
const alova = createAlova({
  baseURL: "https://api.example.com",
  ...alovaDefaultOptions,
});

// 2. 配置请求/响应/错误处理
const methodHandler = createMethodHandler({
  onAuth: () => router.push("/login"),
  onE400: (res) => /* 处理参数校验错误 */ res,
  onE403: () => /* 无权限处理 */,
  onError: (res) => /* 通用错误处理 */,
  onRequest: (method) => /* 请求前处理（如加 token） */,
  onResponse: (data) => data,
});

// 3. 绑定到 alova
alova.beforeRequest(methodHandler.beforeRequest);
alova.response.onSuccess(methodHandler.responseHandler);
alova.response.onError(methodHandler.errorHandler);

// 4. 创建 hook 处理器
const hooks = createHookHandler({
  onLoading: (loading, instance, msg) => /* 全局 loading 控制 */,
  onPagination: (ctx) => /* 分页状态同步 */,
});

export const useList = hooks.usePagination;
export const useDetail = hooks.useRequest;
export const useFormData = hooks.useForm;

API

createAlova(alovaOptions)

创建 alova 实例。alovaDefaultOptions 提供默认配置：

• statesHook: VueHook
• timeout: 30000ms
• cacheFor: GET 500ms

createMethodHandler(options)

创建请求/响应/错误统一处理器：

| 选项 | 说明 | | -------------------------- | --------------------------------------------------- | | onAuth() | 401 时触发（如跳转登录页） | | onE400(res, method) | 400 参数校验失败回调，返回值会合并到 reject 的 data | | onE403(res, method) | 403 无权限回调 | | onError(res, method) | 其他错误回调 | | onRequest(method) | 请求前置处理（如添加 token） | | onResponse(data, method) | 响应数据预处理 |

createHookHandler(options)

创建增强版的 alova hooks，自动处理 loading 状态：

| 选项 | 说明 | | ------------------------------------ | ------------------------------ | | onLoading(loading, instance, msg?) | loading 状态变化回调 | | onPagination?(ctx) | 分页状态同步（如更新 UI 组件） | | paginationConfig?() | 分页默认配置 | | paginationRouter?(params) | 分页参数路由同步 |

返回 hooks：

• usePagination — 增强分页，自动管理 params、路由同步、重置
• useRequest — 增强请求，支持 force() 强制刷新
• useForm — 增强表单，支持 400 错误回显
• useSerialRequest — 串行请求

工具函数

import { excludeNull, invalidateCache } from "@okcy/alova";

excludeNull({ a: "  ", b: "hello", c: NaN });
// => { b: "hello" }

缓存辅助

import { cacheForSec, cacheForMin, cacheForHour, cacheForDay } from "@okcy/alova";

类型

import type { ResponseData, ResponseList, ResponsePage, ResponseError } from "@okcy/alova";
import type { UsePaginationResult, UseRequestResult, UseFormResult } from "@okcy/alova";

依赖

• Vue 3、alova
• @okcy/core（emittery）
• query-string