更新记录

0.1.0（2026-10-13） 下载此版本

首个可用版本。

新增

• 请求主入口 + 七种快捷方法：request 主入口 + get / post / put / patch / del / head / options 快捷方法（method 由方法名固定注入，delete 为 UTS 保留字故命名 del）；泛型 request<T> 静态标注 res.data 类型，UTS / TypeScript 提示全量到位
• 默认实例 + 多实例：默认实例开箱即用，configureRequest 配置全局默认；createRequest(defaults) 创建隔离实例（defaults 与拦截器注册表互不影响），心智对标 axios.create
• 请求 / 响应拦截器：多枚有序注册、可 ejectInterceptor(id) 移除；响应错误链支持恢复（返回响应）/ 换错（返回新错误）/ 放行（返回 null）三条路径，语义对标 axios
• 统一可预测的错误结构：RequestError 收敛 8 类错误码（ERR_PARAM / ERR_CONFIG / ERR_CANCELED / ERR_TIMEOUT / ERR_NETWORK / ERR_BAD_REQUEST / ERR_BAD_RESPONSE / ERR_NATIVE），原生 errCode 经 nativeErrCode 原值透传不翻译，config 与 response 原文挂载——4xx/5xx 响应体不丢失
• 确定性 URL 与参数处理：baseURL 自动拼接（http(s) 开头原样使用）、params 与 url 既有 query 合并后由库内统一编码（encodeURIComponent + JSON 序列化兜底）、GET/HEAD 的 UTSJSONObject 请求体自动并入 query、header 三级浅合并（内置默认 → 实例默认 → 请求级）
• transform / validateStatus / timeout：transformRequest / transformResponse 请求与响应数据变换（GET/HEAD 场景 transformRequest 收到 null，需判空）、validateStatus 自定义状态码校验（默认 2xx，传 null 沿用内置默认）、timeout 超时控制
• 请求取消：createCancelSource() 创建取消源，离开页面等场景确定性 abort 关联的全部进行中请求，以 ERR_CANCELED 可辨识地 reject（reason 在 errMsg 中）
• 逃生舱：onTask 透出原生 RequestTask（chunked 分块监听等高级场景）；enableQuic / sslVerify / withCredentials / enableChunked 等原生能力参数全量透传不抹平
• 平台支持：Web / 微信小程序 / Android 三端编译验证通过，Web 端 15 项真实网络测试矩阵全部通过（iOS / 鸿蒙代码已适配，受环境限制暂未实测）

平台兼容性

uni-app x(3.8.5)

其他

中文 | English

@meng-xi/unix-request

为 uni-app x 提供功能完善的网络请求库（UTS 编写，一套 API 多端覆盖）

[](LICENSE) [](https://www.npmjs.com/package/@meng-xi/unix-request) 

为什么是 unix-request

直接用 uni.request 写业务，URL 拼接、header 合并、超时与取消、五花八门的失败形态……每一项都要自己封装，换个项目再封装一遍。unix-request 把这些重复劳动收敛成一套库：

• 写过 axios？ 拦截器、transform、取消、错误码心智完全对齐，看一眼 API 就能上手；
• 多端发布？ Web / 微信小程序 / Android 一套代码，URL 编码与错误分类由库内确定性实现，不用逐端排查差异；
• 在意类型？ request<T> 泛型响应、字面量联合错误码，UTS / TypeScript 提示全量到位。

底层唯一依赖 uni.request，不重造网络栈；UTS 源码分发（Web / 小程序 → JS，Android → Kotlin，iOS → Swift），由 uni-app x 编译链现场编译。

特性

• axios 心智，开箱即用 - request 主入口 + get / post / put / patch / del / head / options 七种快捷方法（method 由方法名固定注入），默认实例即用，createRequest 多实例隔离
• 统一可预测的错误体系 - RequestError 收敛 8 类错误码（参数 / 配置 / 取消 / 超时 / 网络 / 4xx / 5xx / 原生失败），原生 errCode 原值透传，config 与 response 原文挂载
• 泛型静态标注 - request<T> 返回 Promise<ResponseResult<T>>，res.data 类型直达，UTS / TS 双端友好
• 确定性 URL 与参数处理 - baseURL 自动拼接、params 与 url 既有 query 合并统一编码、GET/HEAD 请求体自动并入 query、header 三级浅合并（内置默认 → 实例默认 → 请求级）
• 请求拦截器与响应拦截器 - 多枚有序注册、可 eject；响应错误链支持恢复 / 换错 / 放行三条路径
• 请求取消 - createCancelSource() 创建取消源，确定性 abort 关联的全部进行中请求，以 ERR_CANCELED 可辨识地 reject
• 强类型 UTS - 除 url 外全部可选字段 + 空安全兜底，method / 错误码为字面量联合类型；onTask 逃生舱透出原生 RequestTask，原生能力参数全量透传不抹平

安装

npm——安装后将包内容同步到工程 uni_modules/mx-request/（编译器不扫描 node_modules）：

pnpm add @meng-xi/unix-request
mkdir -p uni_modules && cp -R node_modules/@meng-xi/unix-request uni_modules/mx-request

packages/core 为标准 uni_modules UTS 插件（utssdk/ 官方目录结构 + interface.uts 对外声明），业务侧从 @/uni_modules/mx-request 导入。

快速开始

1. 发出第一个请求

import { request, configureRequest } from '@/uni_modules/mx-request'
import type { RequestError } from '@/uni_modules/mx-request'

// 项目启动时配置一次全局默认（如 App.uvue onLaunch；null 表示沿用内置默认）
configureRequest({
    baseURL: 'https://your.api',
    timeout: 10000,
    header: null,
    validateStatus: null
})

// 发请求：泛型标注 res.data 类型
request<UTSJSONObject>({
    url: '/api/http/method/get', // 相对路径自动拼接 baseURL
    method: 'GET',
    params: { page: 1 } as UTSJSONObject // 库内确定性编码拼入 query
}).then((res) => {
    console.log('statusCode=' + res.statusCode.toString()) // 200
    console.log(res.data)
}).catch((err) => {
    const e = err as RequestError
    console.log(e.code, e.errMsg)
})

2. 七种快捷方法

import { get, post } from '@/uni_modules/mx-request'

// GET：method 由方法名固定注入，快捷配置不含 url 字段
get<UTSJSONObject>('/api/http/method/get', {
    params: { page: 1 } as UTSJSONObject
}).then((res) => {
    console.log(res.statusCode)
})

// POST：data 支持对象自动序列化
post<UTSJSONObject>('/login', { user: 'demo' } as UTSJSONObject, null).then((res) => {
    console.log(res.data)
})

3. 统一错误处理

import { request } from '@/uni_modules/mx-request'
import type { RequestError } from '@/uni_modules/mx-request'

request<UTSJSONObject>({ url: '/may-fail' }).catch((err) => {
    const e = err as RequestError
    if (e.code == 'ERR_CANCELED') {
        // 主动取消（createCancelSource 的 reason 在 e.errMsg 中）
    } else if (e.code == 'ERR_TIMEOUT') {
        // 超时（原生 errCode 5 经 e.nativeErrCode 原值透传）
    } else if (e.code == 'ERR_BAD_REQUEST') {
        // HTTP 4xx：e.statusCode + e.response 携带响应原文
    } else {
        // 其余：ERR_PARAM / ERR_CONFIG / ERR_NETWORK / ERR_BAD_RESPONSE / ERR_NATIVE
    }
})

运行效果

截图来自仓库自带的示例工程 packages/playground（11 个功能页覆盖全部特性的可运行验证矩阵，H5 / 小程序 / Android 三端可跑）：

Android 真机体验：下载体验 App（APK）——上述示例工程的云打包产物，安装后即可在真机运行全部用例。

交流与支持

想了解设计思路与实现原理（UTS 泛型跨端、错误体系收敛、取消的确定性 abort 等）？公众号「梦曦工作室」有系列解析，***：

• 📖 完整文档（指南 + API 参考 + 更新日志，中英双语）
• 🐛 Issues / 💬 Discussions

导出

• API：request / get / post / put / patch / del / head / options / getUri / useRequestInterceptor / useResponseInterceptor / ejectInterceptor / configureRequest / createRequest / createCancelSource
• 常量：DEFAULT_TIMEOUT / DEFAULT_METHOD / REQUEST_ERR_SUBJECT
• 类型：RequestConfig / RequestQuickConfig / RequestDefaults / ResponseResult / ResponseAny / RequestError / RequestErrorCode / RequestInstance / RequestMethod / CancelToken / CancelSource

文档

📖 从入门到精通的完整文档（指南 + API 参考 + 更新日志）：

https://mengxi-studio.github.io/unix-request/

阅读建议：先看介绍与快速开始，再按 发起请求 → 拦截器 → 错误处理 深入核心链路，API 细节查 API 参考。

更新日志

📝 https://github.com/MengXi-Studio/unix-request/blob/master/packages/docs/src/changelog.md

License

MIT