@bubblesjs/request

@bubblesjs/request 是一个基于 Alova 的请求封装。它把公共请求头、响应转换、业务码判断、消息提示、缓存适配器和单次请求覆盖配置集中到一处管理。

安装

pnpm

npm

yarn

bun

pnpm add @bubblesjs/request alova

快速开始

import { createInstance } from '@bubblesjs/request'

const request = createInstance({
  baseUrl: '/api',
  commonHeaders: {
    'Content-Type': 'application/json',
    Authorization: async () => `Bearer ${await getToken()}`
  },
  successMessageFunc: (message) => toast.success(message),
  errorMessageFunc: (message) => toast.error(message),
  unAuthorizedResponseFunc: () => router.push('/login')
})

const user = await request.Get('/user/info')
const result = await request.Post('/user/update', {
  body: { name: '张三' }
})

默认情况下，成功的包裹响应形如：

{
  code: 200,
  data: { id: 1 },
  message: 'ok'
}

最终返回值是 responseDataKey 配置的字段，所以上面的响应会解析成 { id: 1 }。

双重调用实例

createDualCallInstance 会返回一个默认 Alova 实例，同时这个实例也可以作为函数调用，用临时配置创建新的请求实例。

import { createDualCallInstance } from '@bubblesjs/request'

const request = createDualCallInstance({
  baseUrl: '/api',
  isShowSuccessMessage: false,
  errorMessageFunc: (message) => toast.error(message)
})

await request.Get('/user/profile')

await request({
  isShowSuccessMessage: true,
  successMessageFunc: (message) => toast.success(message)
}).Post('/user/create', {
  body: { name: '李四' }
})

配置项

参数	类型	默认值	说明
`baseUrl`	`string`	`'/'`	传给 Alova 的 `baseURL`。
`timeout`	`number`	`undefined`	请求超时时间。
`commonHeaders`	`Record<string, HeaderValue>`	`{}`	公共请求头，值可以是静态值或异步函数。
`statusMap`	`StatusMap`	`{ success: 200, unAuthorized: 401 }`	HTTP 状态匹配规则。
`codeMap`	`CodeMap`	`{ success: [200], unAuthorized: [401] }`	业务状态码匹配规则。
`responseCodeKey`	`string`	`'code'`	包裹响应里的业务码字段名。
`responseDataKey`	`string`	`'data'`	包裹响应里的数据字段名。
`responseMessageKey`	`string`	`'message'`	包裹响应里的消息字段名。
`isWrapped`	`boolean`	`true`	响应是否是 `{ code, data, message }` 这类包裹结构。
`isTransformResponse`	`boolean`	`true`	是否在 `responded.onSuccess` 中转换响应。
`isShowSuccessMessage`	`boolean`	`false`	业务成功后是否调用 `successMessageFunc`。
`successDefaultMessage`	`string`	`'操作成功'`	默认成功消息。
`isShowErrorMessage`	`boolean`	`true`	HTTP、业务或网络错误时是否调用 `errorMessageFunc`。
`errorDefaultMessage`	`string`	`'服务异常'`	默认错误消息。
`successMessageFunc`	`(message: string) => void`	`undefined`	成功消息处理函数。
`errorMessageFunc`	`(message: string) => void`	`undefined`	错误消息处理函数。
`unAuthorizedResponseFunc`	`() => void`	`undefined`	HTTP 状态或业务码命中未授权时调用。
`statesHook`	`StatesHook`	`undefined`	Alova 的状态钩子，用于 React、Vue 等框架集成。
`requestAdapter`	`AlovaRequestAdapter`	`adapterFetch()`	Alova 请求适配器。
`cacheFor`	`GlobalCacheConfig \| null`	`null`	Alova 全局缓存配置。
`cacheLogger`	`boolean`	`true`	Alova 缓存日志开关。
`l1Cache`	`AlovaGlobalCacheAdapter`	`undefined`	Alova 一级缓存适配器。
`l2Cache`	`AlovaGlobalCacheAdapter`	`undefined`	Alova 二级缓存适配器。
`storageAdapter`	`AlovaGlobalCacheAdapter`	`undefined`	`l2Cache` 的兼容别名。

匹配规则

statusMap.success 和 statusMap.unAuthorized 支持数字、数字数组或函数：

const request = createInstance({
  statusMap: {
    success: [200, 201, 204],
    unAuthorized: (status) => status === 401 || status === 419
  }
})

codeMap.success 和 codeMap.unAuthorized 支持数字或字符串数组：

const request = createInstance({
  responseCodeKey: 'status',
  responseMessageKey: 'msg',
  codeMap: {
    success: [0, 'OK'],
    unAuthorized: [401, 'TOKEN_EXPIRED']
  }
})

单次请求 meta 覆盖

以下配置可以通过单个请求的 meta 覆盖：

isWrapped
isTransformResponse
isShowSuccessMessage
isShowErrorMessage

const rawResponse = await request.Get('/download/file', {
  meta: {
    isTransformResponse: false,
    isShowErrorMessage: false
  }
})

const rawUploadData = await request.Post('/upload', {
  body: formData,
  meta: {
    isWrapped: false
  }
})

响应结构

默认 fetch 适配器会返回 Response，内部会根据 content-type 解析。JSON 响应使用 json()，文本响应使用 text()，可解析的 JSON 字符串会自动转换。

同时也支持 Axios 风格和 Taro 风格的响应：

// Axios 风格
{
  status: 200,
  data: { code: 200, data: [], message: 'loaded' }
}

// Taro 风格
{
  statusCode: 200,
  data: { code: 200, data: { ok: true }, msg: 'done' }
}

对于 Taro 上传接口这类把 data 返回为 JSON 字符串的场景，会先解析字符串，再应用 codeMap 和 responseDataKey。

自定义适配器

可以传入任意 Alova 请求适配器。如果适配器同时暴露缓存适配器，可以通过 l2Cache 或 storageAdapter 传入。

import { createInstance } from '@bubblesjs/request'
import { adapterTaro } from '@alova/adapter-taro'

const taroAdapter = adapterTaro()

const request = createInstance({
  baseUrl: '/api',
  requestAdapter: taroAdapter.requestAdapter,
  storageAdapter: taroAdapter.storageAdapter,
  responseMessageKey: 'msg'
})

类型定义

type MaybePromise<T> = T | Promise<T>

type HeaderValue =
  | string
  | number
  | boolean
  | null
  | undefined
  | (() => MaybePromise<string | number | boolean | null | undefined>)

type StatusMatcher<RE> =
  | number
  | number[]
  | ((status: number, response: RE) => boolean)

type CodeMatcher = Array<number | string>

interface StatusMap<RE = unknown> {
  success?: StatusMatcher<RE>
  unAuthorized?: StatusMatcher<RE>
}

interface CodeMap {
  success?: CodeMatcher
  unAuthorized?: CodeMatcher
}

interface RequestMeta {
  isWrapped?: boolean
  isTransformResponse?: boolean
  isShowSuccessMessage?: boolean
  isShowErrorMessage?: boolean
}

#@bubblesjs/request

#安装

#快速开始

#双重调用实例

#配置项

#匹配规则

#单次请求 meta 覆盖

#响应结构

#自定义适配器

#类型定义