更新记录

1.0.0（2026-07-20）

• HTTP：OPTIONS / GET / HEAD / POST / PUT / DELETE
• 上传、下载与进度回调
• WebSocket：XViewSocketClient（Web / 微信小程序）；App 未声明 SocketTask 时返回 9001003
• 网络状态查询与监听；无网 / 断网统一错误码
• 请求、响应、调试拦截器
• 修复 App(JS) 普通对象 toMap() 报错、Android 响应字段丢失、网络 API 缺失时的降级

平台兼容性

uni-app(4.87)

uni-app x(5.0)

xview-request

面向 uni-app 与 uni-app x 的跨端网络请求插件。统一包装官方 uni.request、uni.uploadFile、uni.downloadFile、SocketTask 与网络状态 API，对外提供 HTTP、文件传输、WebSocket、网络监听与拦截器能力。

安装与引入

将 uni_modules/xview-request 放入项目后，在 HBuilderX 中重新编译。

// uni-app（Vue / TS）
import { Request, createRequest, getRequestFail } from '@/uni_modules/xview-request'

// uni-app x（UTS）
import { Request } from '@/uni_modules/xview-request'

快速开始

const request = new Request({
  baseURL: 'https://api.example.com',
  timeout: 15000
})

// 请求拦截器：追加 Token
request.onRequestInterceptor((config) => {
  const header = config.header || {}
  header.Authorization = 'Bearer token'
  config.header = header
  return config
})

// 响应拦截器：处理状态码并返回业务 data
request.onResponseInterceptor((response) => {
  if (response.statusCode === 401) {
    uni.showToast({ title: '登录状态已失效', icon: 'none' })
  }
  return response.data
})

// 调试拦截器：打印请求摘要（成功/失败均触发）
request.onDebuggerInterceptor((debug) => {
  console.log(debug.statusCode, debug.duration, debug.error)
})

await request.get('/users', null, { params: { page: 1 } })

也可使用工厂函数：const request = createRequest({ baseURL: '...' })

API

Request 实例

XViewSocketClient

错误处理

Promise reject 值为 IRequestError。页面 catch 时可使用：

import { getRequestFail } from '@/uni_modules/xview-request'

request.get('/users').catch((err) => {
  const error = getRequestFail(err)
  console.log(error.errCode, error.errMsg)
})

拦截器

拦截器按注册顺序执行。

请求拦截器：插件会先复制 config、header、params、formData，再执行拦截器。App(JS) 桥接可能把返回值转为 kotlin.Unit，推荐就地修改 config 后返回。

响应拦截器：入参为统一 IRequestResponse，返回值作为 Promise 最终 resolve 值。常见写法是直接返回 response.data；下载场景可返回 response.tempFilePath。

调试拦截器：每次请求结束触发，包含 config、response、error、statusCode、duration、networkStatus。

HTTP 与文件

request.get('/users', { id: 1 })                    // query 也可写在 config.params
request.post('/users', { name: 'Ada' })
request.formPost('/token', { username: 'demo', password: 'secret' })
request.deleteRequest('/users/1')

request.upload('/files', {
  filePath: localPath,
  name: 'file',
  formData: { category: 'avatar' },
  Update: (p) => console.log(p.progress)
})

request.download('/files/logo.png', {
  filePath: targetPath,  // 可选；不传则返回临时路径
  Update: (p) => console.log(p.progress)
})

• 上传必须提供 filePath 或 files，否则 reject 9001004。
• 下载成功响应含 tempFilePath、filePath；配合响应拦截器可直接 resolve 文件路径。

Socket 与网络

const socket = request.connectSocket({
  url: 'wss://echo.example.com',
  header: { token: 'xxx' },
  onOpen: () => {},
  onMessage: (msg) => console.log(msg.data),
  onError: (err) => console.error(err.errMsg),
  onClose: (res) => console.log(res.code)
})

await socket.send({ data: 'hello' })
await socket.close({ code: 1000 })

const status = await request.getNetworkStatus()
const id = request.watchNetworkStatus((s) => console.log(s.networkType, s.isConnected))
request.stopNetworkStatus(id)

• 每个连接独立 SocketTask，勿混用全局 Socket API。
• 请求下发前检查网络，无网 reject 9001001；请求期间断网时，底层失败也会归类为 9001001。

错误码

运行前配置

插件不替代应用侧安全配置：

• Web：需服务端 CORS
• 小程序：需配置合法 request / upload / download / socket 域名
• App：需网络权限；HTTPS/WSS 推荐用于生产环境