【Alpha 体验邀请】luch-request v4：面向 uni-app 重新设计的 TypeScript 请求库

大家好，我是 luch-request 的维护者。

luch-request v4 Alpha 现已发布到 npm，想邀请正在使用 uni-app 的开发者参与体验，帮助验证不同平台下的请求、上传下载、取消和原生 Task 行为。

npm install luch-request@alpha

v4 不是对 v3 的内部重构，而是一个 breaking version。它围绕 uni API、原生 Task、TypeScript 类型边界和多平台行为重新设计，希望在保留 uni 原生能力的同时，让请求配置、错误处理和取消行为更加明确。

当前版本为 4.0.0-alpha.1，公共 API 在稳定版前仍可能调整。建议先在测试项目或非核心业务中体验，并在自己的目标平台完成验证。

为什么重新设计 v4

uni-app 可以运行在 H5、App 和不同小程序平台，但各平台支持的请求参数、原生 Task、错误对象和取消能力并不完全一致。

如果直接套用浏览器 HTTP client 的设计，会遇到一些实际问题：

• 浏览器的 API 和类型不能代表所有 uni-app 平台；
• request、uploadFile、downloadFile 拥有不同的原生参数和 Task；
• 平台新增参数的速度可能快于请求库和类型声明的更新；
• 网络失败、HTTP 状态码失败、取消和 JSON 解析失败需要不同的判断依据；
• TypeScript 类型过于宽松会失去约束，过于严格又可能阻碍平台新增能力。

因此，v4 没有把 v3 的内部结构继续扩展，而是重新确定了公共 API、配置合并、Interceptor、错误、取消和跨平台边界。

v4 带来了什么

1. TypeScript-first

请求响应、请求体和查询参数可以分别建模，常见调用保持直接：

import { createLuchRequest } from 'luch-request'  

const http = createLuchRequest({  
  baseURL: 'https://api.example.com',  
  timeout: 10_000  
})  

interface User {  
  id: number  
  name: string  
}  

interface UserListParams {  
  page: number  
  keyword?: string  
}  

const response = await http.get<User[], UserListParams>('/users', {  
  params: {  
    page: 1  
  }  
})  

console.log(response.data)

JavaScript 项目仍然可以使用 v4；TypeScript 项目则能获得更完整的配置、响应、错误和公共导出类型。

2. 保留 uni 原生能力

v4 分别支持：

• request
• upload
• download

三类操作共用实例配置、Interceptor 和错误契约，但在派发边界保留各自的原生参数，不使用 UPLOAD、DOWNLOAD 这样的伪 HTTP method。

3. 可以访问原生 Task

请求 Promise 提供 abort()、task 和 onTask()，单次请求配置也可以使用 onTask：

const request = http.get('/users', {  
  onTask(task) {  
    console.log('原生 Task：', task)  
  }  
})  

// 需要取消时  
request.abort()

如果取消能力需要跨 service 层传递，可以使用 createCancelSource()，不必把请求 Promise 暴露给每一层调用方。

4. 明确的配置边界与 nativeOptions

v4 将配置分成不同职责：

• 常用 uni 请求参数可以直接配置；
• luch-request 自身行为放在 luchOptions；
• 平台新增参数或插件尚未声明的参数通过 nativeOptions 透传。

nativeOptions 是面向平台新能力的逃生窗口。当比较新的 uni API、某个平台参数或第三方插件参数还没有进入请求库类型时，使用方仍然可以显式透传，而不需要等待库发布新版本。

5. Interceptor 区分操作类型

v4 提供 request/response interceptor，支持同步和异步处理。Interceptor 上下文可以使用 LuchOperation 判断当前执行的是 request、upload 还是 download，避免依赖字符串或伪 method。

6. 统一错误与 JSON 解析策略

请求失败时统一抛出 LuchRequestError，并保留可用于判断的上下文，例如：

• code
• config
• response
• task
• cause
• raw
• cancelMode

网络失败、HTTP 状态码失败、取消和 JSON 解析失败可以分别判断。对于 JSON 解析失败，还可以通过 JSONParsingMode 选择抛出错误、保留文本等处理方式。

Alpha 阶段暂不包含什么

为了先稳定核心请求契约，首个版本不会内置以下能力：

• 自动重试
• 请求缓存
• 请求去重
• 并发控制
• Token 自动刷新
• WebSocket
• uni_modules
• uni-app x

这些能力并不是简单地全部塞进核心库。后续会根据真实使用场景，判断应该由 Interceptor、独立扩展还是核心能力提供。

v3 用户需要立即升级吗

不需要。

v3 稳定项目可以继续使用现有版本。v4 是 breaking version，适合以下开发者优先体验：

• 正在开发新项目；
• 希望获得更完整的 TypeScript 类型；
• 需要统一错误和取消行为；
• 需要访问原生 Task 或进度事件；
• 希望分别处理 request、upload 和 download；
• 愿意在自己的目标平台验证 Alpha 行为。

正式迁移前，请先阅读 v3 到 v4 的迁移文档，并在实际运行平台完成 smoke test。

希望大家重点帮助验证

自动化测试能够验证请求库逻辑，但不能代替所有真实设备、运行平台和 uni-app 版本。特别希望大家帮助验证：

1. H5、App、微信小程序及其他小程序中的基础请求；
2. upload、download 及进度事件；
3. abort() 是否触发平台原生中断；
4. onTask() 是否能取得预期的原生 Task；
5. 不同平台返回的错误结构是否存在差异；
6. nativeOptions 是否能正确传递平台新增参数；
7. TypeScript 类型是否存在过严、过松或无法表达的场景；
8. JavaScript 项目中的配置和错误行为是否足够清晰。

如何反馈

提交问题时，如果方便，请尽量提供以下信息：

运行平台：  
HBuilderX / uni-app 版本：  
luch-request 版本：  
使用 TypeScript 还是 JavaScript：  
最小复现代码：  
预期结果：  
实际结果：  
错误对象或控制台日志：

如果问题与取消、上传下载或原生 Task 有关，也请说明实际运行平台，以及是否能取得对应 Task。

相关链接

• v4 文档：https://luch-request.quanzhan.co/
• GitHub：https://github.com/lei-mu/luch-request
• 问题反馈：https://github.com/lei-mu/luch-request/issues
• npm：https://www.npmjs.com/package/luch-request
• v3 稳定文档：https://v3.luch-request.quanzhan.co/

写在最后

v4 的核心设计和自动化测试已经完成，但 uni-app 请求库真正困难的部分始终是多平台运行差异。

希望正在使用 uni-app 的开发者帮助验证 request、upload、download、取消和原生 Task 等能力。无论是兼容性问题、类型设计建议，还是某个平台特有的行为差异，都欢迎在 GitHub Issue 或本帖中反馈。

感谢每一位愿意安装、运行和提供反馈的开发者。