更新记录

2.2.1（2026-08-21） 下载此版本

• 代码结构拆分（无行为变更）：
  • types.ts 类型定义 / error.ts 错误对象 / error-bus.ts 错误订阅与默认 toast / config.ts baseURL / interceptors.ts 业务插槽（token 供应器/守卫/401 重试）/ dedupe.ts 在飞请求合并 / request.ts 核心请求管线
  • 新增 index.ts 统一出口（推荐 import 路径）
  • 旧路径 .../commons/request 保持兼容（再导出），存量调用零改动

平台兼容性

uni-app(5.24)

uni-app x(5.24)

# wc-request

基于 uni.request 的基础接口请求封装。

使用

1. 初始化（App 启动时，可选）

// main.ts
import { setBaseURL } from "@/uni_modules/wc-request/commons"

setBaseURL("https://api.example.com")

2. 发起请求

import { request } from "@/uni_modules/wc-request/commons"

// GET（默认方法）—— 出错时自动 toast 错误信息
// 包裹响应（{ code, message, data }）：resolve 的直接就是 data 部分
const user = await request<UserInfo>({ url: "/user/1" })
console.log(user.name)        // 直接用，不用 .data.data

// POST
const login = await request<{ token: string }>({
  url: "/login",
  method: "POST",
  data: { username: "admin", password: "123456" },
})

// 静默接口：出错不 toast，由调用方自行处理
// （适用于轮询、静默预加载、有专属错误 UI 的接口）
try {
  await request({ url: "/stats/heartbeat", silent: true })
} catch (error) {
  // 自己处理，比如什么都不做
}

非包裹响应（响应体无 code 字段，如第三方接口、文件流）：resolve 完整响应 { statusCode, header, data }，需要状态码/响应头时从这里取。

行为约定

默认 toast 参数：{ title: error.message, duration: 2000, icon: "none" }。

业务包裹结构约定：

interface ApiBody<T = any> {
  code: number
  message?: string
  data?: T
}

响应体不含 code 字段时（如第三方接口、文件流）且 HTTP 为 2xx，不做业务判断，直接 resolve。

RequestError

class RequestError extends Error {
  type: "business" | "network"  // 错误来源
  code?: number                 // 业务码（business 时有值）
  raw?: any                     // 网络层原始错误（network 时有值）
}

// 创建（一般在插件内部，调用方只读）
RequestError.business("用户名不存在", 1001)
RequestError.network(rawErr)

额外处理（可选）

需要埋点、日志、监控上报等额外处理时，订阅错误事件：

import { onRequestError } from "@/uni_modules/wc-request/commons"

const off = onRequestError((error) => {
  console.log("上报：", error.type, error.message)
})
// 不需要时调用 off() 取消订阅

相同在飞请求合并（可选）

dedupe: true：method + url + data 完全一致且仍在飞的请求，后来者不再发起新请求，直接等待复用第一个请求的结果（成功共享、失败共享）。请求 settle 后即解除登记，后续调用重新发起。

// 三个组件同时执行下面这句 → 只发 1 次请求，三方拿到同一结果
const res = await request({
  url: "/core/mobile/system/dict",
  data: { codes: "gender" },
  dedupe: true,
})

适用：多组件同时拉同一份字典、配置等幂等 GET。 注意：POST 等非幂等请求请勿开启（后到的提交会被合并掉）。

范围说明

刻意不包含以下能力（防止过早耦合业务）：

• 请求/响应拦截器链
• token 注入与自动刷新、401 特殊处理（重定向登录）