uniapp-request-sdk 1.5.1 → 1.6.1

package/README.md

@@ -5,6 +5,49 @@
 [![npm version](https://img.shields.io/npm/v/uniapp-request-sdk.svg)](https://www.npmjs.com/package/uniapp-request-sdk)
 [![license](https://img.shields.io/npm/l/uniapp-request-sdk.svg)](https://github.com/yourusername/uniapp-request-sdk)
 
+## 目录
+
+- [适用场景](#适用场景)
+- [核心能力](#核心能力)
+- [安装](#安装)
+- [5 分钟接入](#5-分钟接入)
+- [快速开始](#快速开始)
+- [工程接入建议](#工程接入建议)
+- [详细配置](#详细配置)
+- [API 文档](#api-文档)
+- [文件上传](#文件上传)
+- [使用示例](#使用示例)
+- [响应格式](#响应格式)
+- [错误处理](#错误处理)
+- [平台差异处理](#平台差异处理)
+- [配置参数详解](#配置参数详解)
+- [请求头预处理器（新增功能）](#请求头预处理器新增功能)
+- [最佳实践](#最佳实践)
+- [企业级实战案例](#企业级实战案例)
+- [常见问题](#常见问题)
+- [版本历史](#版本历史)
+
+## 适用场景
+
+这个 SDK 适合以下场景：
+
+- uni-app 项目中统一封装 `GET`、`POST`、`PUT`、`DELETE`、`uploadFile`
+- 需要自动处理 `403` 后重新获取 token 再重试的业务场景
+- 需要为所有请求统一追加公共请求头、日志字段、签名字段
+- 需要在 App、小程序、H5 等多端尽量复用一套网络层逻辑
+- 需要在上传文件时监听进度并驱动页面上的进度条展示
+
+如果你的服务端返回结构不是本文档中的默认格式，也可以基于当前 SDK 继续二次封装。
+
+## 核心能力
+
+- 统一的请求实例管理，支持运行时动态更新参数
+- 支持全局公共请求头与单次请求头合并
+- 支持同步或异步的请求头预处理器 `headerProcessor`
+- 支持 `401`、`403`、网络异常、超时等通用场景处理
+- 支持文件上传、上传超时控制和上传进度监听
+- 默认兼容相对路径与完整 URL 两种调用方式
+
 ## 特性
 
 - ✅ **自动重试机制** - 请求失败自动重试，可配置重试次数和延迟
@@ -30,6 +73,57 @@ npm install uniapp-request-sdk
 yarn add uniapp-request-sdk
 ```
 
+## 5 分钟接入
+
+```typescript
+import UniRequest from 'uniapp-request-sdk';
+
+const request = new UniRequest({
+  baseUrl: 'https://api.example.com',
+  timeout: 10000,
+  uploadTimeout: 30000,
+  tokenHeader: 'Authorization',
+  tokenPrefix: 'Bearer ',
+  onErrorHandler: (error) => {
+    console.error('请求失败:', error);
+  },
+});
+
+export default request;
+```
+
+```typescript
+import request from '@/utils/request';
+
+export function getUserProfile() {
+  return request.get('/user/profile');
+}
+
+export function updateUserProfile(data: Record<string, any>) {
+  return request.post('/user/profile/update', data);
+}
+
+export function uploadAvatar(filePath: string) {
+  return request.uploadFile(
+    '/user/avatar/upload',
+    filePath,
+    undefined,
+    'file',
+    undefined,
+    (progress) => {
+      console.log('上传进度:', progress.progress);
+    },
+  );
+}
+```
+
+完成以上两步后，你的工程已经具备：
+
+- 统一请求入口
+- 统一错误处理能力
+- 文件上传能力
+- 上传进度监听能力
+
 ## 快速开始
 
 ### 基础使用
@@ -58,10 +152,43 @@ await request.put('/users/1', { name: 'Jane' });
 // 6. 上传文件
 const uploadResult = await request.uploadFile(
   '/upload',
-  '/path/to/file.jpg'
+  '/path/to/file.jpg',
+  undefined,
+  'file',
+  undefined,
+  (progress) => {
+    console.log('当前上传进度:', progress.progress);
+  },
 );
 ```
 
+## 工程接入建议
+
+推荐在业务工程中按下面的方式组织网络层：
+
+```text
+src/
+├── api/                  # 按业务域拆分接口
+│   ├── user.ts
+│   ├── auth.ts
+│   └── workflow.ts
+├── utils/
+│   └── request.ts        # SDK 实例初始化
+└── pages/                # 页面中只调用 api 层
+```
+
+推荐职责划分如下：
+
+- `utils/request.ts`：只负责创建 `UniRequest` 实例和放置全局配置
+- `api/*.ts`：只负责定义接口函数，不写 UI 逻辑
+- `pages/*` 或 `components/*`：只消费 `api` 层返回的数据
+
+推荐这样做的原因：
+
+- 请求配置只有一份，便于统一维护
+- token、签名、超时、日志字段不会散落在页面中
+- 后续替换域名、调整 header、增加埋点时改动范围最小
+
 ## 详细配置
 
 ### 初始化配置
@@ -214,8 +341,70 @@ const result = await request.uploadFile<ResponseType>(
     'X-Upload-Token': 'upload-token',
   }
 );
+
+// 监听上传进度
+const result = await request.uploadFile<ResponseType>(
+  '/upload',
+  '/path/to/file.jpg',
+  { description: 'My upload' },
+  'file',
+  undefined,
+  (progress) => {
+    console.log('上传进度百分比:', progress.progress);
+    console.log('已上传字节数:', progress.totalBytesSent);
+    console.log('总字节数:', progress.totalBytesExpectedToSend);
+  }
+);
+```
+
+## 文件上传
+
+### 方法签名
+
+```typescript
+uploadFile<T>(
+  url: string,
+  filePath: string,
+  formData?: Record<string, any>,
+  name = 'file',
+  header?: Record<string, string>,
+  onProgressUpdateCallback?: (result: OnProgressUpdateResult) => void,
+): Promise<T>
 ```
 
+### 参数说明
+
+| 参数 | 类型 | 是否必填 | 说明 |
+|------|------|----------|------|
+| `url` | `string` | 是 | 上传接口地址，支持相对路径和完整 URL |
+| `filePath` | `string` | 是 | 待上传文件的本地临时路径 |
+| `formData` | `Record<string, any>` | 否 | 附加的表单字段 |
+| `name` | `string` | 否 | 文件字段名，默认是 `file` |
+| `header` | `Record<string, string>` | 否 | 当前上传请求的自定义请求头 |
+| `onProgressUpdateCallback` | `(result) => void` | 否 | 上传进度回调 |
+
+### 上传进度回调说明
+
+当传入 `onProgressUpdateCallback` 后，SDK 会在内部调用 `uni.uploadFile()` 返回的 `UploadTask.onProgressUpdate()` 进行绑定。
+
+回调参数结构如下：
+
+```typescript
+type OnProgressUpdateResult = {
+  progress?: number;
+  totalBytesSent?: number;
+  totalBytesExpectedToSend?: number;
+};
+```
+
+### 使用注意事项
+
+- `onProgressUpdateCallback` 是可选参数，不传时上传行为与旧版本保持一致
+- 如果只想传进度回调、不需要自定义 `header`，第 5 个参数需要显式传 `undefined`
+- 上传接口底层仍然返回 Promise，适合继续用 `await` 或 `.then()`
+- 如果上传过程中发生失败并触发重试，进度回调会按“当前这次上传尝试”的进度继续上报
+- 如果服务端返回的是字符串 JSON，SDK 会自动尝试解析后再取其中的 `data`
+
 ## 使用示例
 
 ### 示例 1：基础请求
@@ -327,6 +516,47 @@ async function selectAndUploadFile() {
 }
 ```
 
+### 示例 4-1：带上传进度的文件上传
+
+```typescript
+import UniRequest from 'uniapp-request-sdk';
+
+const request = new UniRequest({
+  baseUrl: 'https://api.example.com',
+  uploadTimeout: 30000,
+});
+
+async function selectAndUploadFile() {
+  uni.chooseImage({
+    count: 1,
+    success: async (res) => {
+      const filePath = res.tempFilePaths[0];
+      let currentProgress = 0;
+
+      try {
+        const result = await request.uploadFile(
+          '/upload',
+          filePath,
+          {
+            category: 'avatar',
+          },
+          'file',
+          undefined,
+          (progress) => {
+            currentProgress = progress.progress || 0;
+            console.log('上传中:', currentProgress);
+          },
+        );
+
+        console.log('上传完成:', result);
+      } catch (error) {
+        console.error('上传失败:', error, currentProgress);
+      }
+    },
+  });
+}
+```
+
 ### 示例 5：实时生成签名
 
 ```typescript
@@ -973,6 +1203,8 @@ export default {
 
 
 
+## 常见问题
+
 ### Q: 如何处理跨域问题？
 
 A: 在 `baseUrl` 中包含代理路径，让后端或开发服务器代理请求。

package/dist/index.d.ts

@@ -30,6 +30,9 @@ interface IParams {
     /** 用户名，用于日志排查使用 */
     username?: string;
 }
+type UploadFileWithProgressOption = UploadFileOption & {
+    onProgressUpdateCallback?: (result: OnProgressUpdateResult) => void;
+};
 declare function requestPromise(options?: RequestOptions & {
     timeout: number;
 }): Promise<RequestSuccessCallbackResult>;
@@ -68,7 +71,7 @@ declare class UniRequest {
         header?: RequestOptions['header'];
         /** 超时时间 */
         timeout?: number;
-    } & RequestOptions & UploadFileOption, callbackPromise?: typeof requestPromise): Promise<T>;
+    } & RequestOptions & UploadFileWithProgressOption, callbackPromise?: typeof requestPromise): Promise<T>;
     /**
      * post请求
      * @param url
@@ -82,14 +85,15 @@ declare class UniRequest {
     put<T>(url: string, data?: {}, header?: Record<string, string>): Promise<T>;
     /**
      * 文件上传
-     * @param url 上传的url
-     * @param filePath 文件路径
-     * @param formData HTTP 请求中其他额外的 form data
-     * @param name 文件对应的 key , 开发者在服务器端通过这个 key 可以获取到文件二进制内容,默认key为file
-     * @param header
-     * @returns
+     * @param url 上传接口地址；支持相对路径和完整的 http/https 地址
+     * @param filePath 待上传文件的本地临时路径
+     * @param formData 额外的表单字段，会与文件一起作为 multipart/form-data 提交
+     * @param name 文件字段名；服务端通过该字段读取文件内容，默认值为 file
+     * @param header 当前上传请求的自定义请求头；会与实例级公共请求头合并
+     * @param onProgressUpdateCallback 上传进度回调；传入后会绑定到 uni.uploadFile 返回的 UploadTask.onProgressUpdate
+     * @returns 返回一个 Promise；成功时解析服务端响应中的 data 字段，失败时抛出错误信息
      */
-    uploadFile<T>(url: string, filePath: string, formData?: Record<string, any>, name?: string, header?: Record<string, string>): Promise<T>;
+    uploadFile<T>(url: string, filePath: string, formData?: Record<string, any>, name?: string, header?: Record<string, string>, onProgressUpdateCallback?: (result: OnProgressUpdateResult) => void): Promise<T>;
 }
 
 export { IParams, UniRequest as default };

package/dist/index.esm.js

@@ -366,6 +366,33 @@ function _toPropertyKey(arg) {
   return typeof key === "symbol" ? key : String(key);
 }
 
+/*! *****************************************************************************
+Copyright (c) Microsoft Corporation.
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.
+***************************************************************************** */
+
+function __rest(s, e) {
+    var t = {};
+    for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p) && e.indexOf(p) < 0)
+        t[p] = s[p];
+    if (s != null && typeof Object.getOwnPropertySymbols === "function")
+        for (var i = 0, p = Object.getOwnPropertySymbols(s); i < p.length; i++) {
+            if (e.indexOf(p[i]) < 0 && Object.prototype.propertyIsEnumerable.call(s, p[i]))
+                t[p[i]] = s[p[i]];
+        }
+    return t;
+}
+
 /** 客户端交互内置事件名称 */
 var EVENT_NAME = {
   /** 通知APP退出到登录页面 */
@@ -381,10 +408,16 @@ function requestPromise(options) {
 }
 function uploadFilePromise(options) {
   return new Promise(function (res, rej) {
-    uni.uploadFile(Object.assign(Object.assign({}, options), {
+    var _a = options || {},
+      onProgressUpdateCallback = _a.onProgressUpdateCallback,
+      uploadOptions = __rest(_a, ["onProgressUpdateCallback"]);
+    var uploadTask = uni.uploadFile(Object.assign(Object.assign({}, uploadOptions), {
       success: res,
       fail: rej
     }));
+    if (onProgressUpdateCallback) {
+      uploadTask.onProgressUpdate(onProgressUpdateCallback);
+    }
   });
 }
 /** 得到小程序的token */
@@ -642,18 +675,20 @@ var UniRequest = /*#__PURE__*/function () {
     }
     /**
      * 文件上传
-     * @param url 上传的url
-     * @param filePath 文件路径
-     * @param formData HTTP 请求中其他额外的 form data
-     * @param name 文件对应的 key , 开发者在服务器端通过这个 key 可以获取到文件二进制内容,默认key为file
-     * @param header
-     * @returns
+     * @param url 上传接口地址；支持相对路径和完整的 http/https 地址
+     * @param filePath 待上传文件的本地临时路径
+     * @param formData 额外的表单字段，会与文件一起作为 multipart/form-data 提交
+     * @param name 文件字段名；服务端通过该字段读取文件内容，默认值为 file
+     * @param header 当前上传请求的自定义请求头；会与实例级公共请求头合并
+     * @param onProgressUpdateCallback 上传进度回调；传入后会绑定到 uni.uploadFile 返回的 UploadTask.onProgressUpdate
+     * @returns 返回一个 Promise；成功时解析服务端响应中的 data 字段，失败时抛出错误信息
      */
   }, {
     key: "uploadFile",
     value: function uploadFile(url, filePath, formData) {
       var name = arguments.length > 3 && arguments[3] !== undefined ? arguments[3] : 'file';
       var header = arguments.length > 4 ? arguments[4] : undefined;
+      var onProgressUpdateCallback = arguments.length > 5 ? arguments[5] : undefined;
       return this.request({
         url: url,
         filePath: filePath,
@@ -661,7 +696,8 @@ var UniRequest = /*#__PURE__*/function () {
         name: name,
         header: header,
         timeout: this.uploadTimeout,
-        method: 'POST'
+        method: 'POST',
+        onProgressUpdateCallback: onProgressUpdateCallback
       }, uploadFilePromise);
     }
   }]);

package/dist/index.umd.js

@@ -372,6 +372,33 @@
     return typeof key === "symbol" ? key : String(key);
   }
 
+  /*! *****************************************************************************
+  Copyright (c) Microsoft Corporation.
+
+  Permission to use, copy, modify, and/or distribute this software for any
+  purpose with or without fee is hereby granted.
+
+  THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+  REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+  AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+  INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+  LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+  OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+  PERFORMANCE OF THIS SOFTWARE.
+  ***************************************************************************** */
+
+  function __rest(s, e) {
+      var t = {};
+      for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p) && e.indexOf(p) < 0)
+          t[p] = s[p];
+      if (s != null && typeof Object.getOwnPropertySymbols === "function")
+          for (var i = 0, p = Object.getOwnPropertySymbols(s); i < p.length; i++) {
+              if (e.indexOf(p[i]) < 0 && Object.prototype.propertyIsEnumerable.call(s, p[i]))
+                  t[p[i]] = s[p[i]];
+          }
+      return t;
+  }
+
   /** 客户端交互内置事件名称 */
   var EVENT_NAME = {
     /** 通知APP退出到登录页面 */
@@ -387,10 +414,16 @@
   }
   function uploadFilePromise(options) {
     return new Promise(function (res, rej) {
-      uni.uploadFile(Object.assign(Object.assign({}, options), {
+      var _a = options || {},
+        onProgressUpdateCallback = _a.onProgressUpdateCallback,
+        uploadOptions = __rest(_a, ["onProgressUpdateCallback"]);
+      var uploadTask = uni.uploadFile(Object.assign(Object.assign({}, uploadOptions), {
         success: res,
         fail: rej
       }));
+      if (onProgressUpdateCallback) {
+        uploadTask.onProgressUpdate(onProgressUpdateCallback);
+      }
     });
   }
   /** 得到小程序的token */
@@ -648,18 +681,20 @@
       }
       /**
        * 文件上传
-       * @param url 上传的url
-       * @param filePath 文件路径
-       * @param formData HTTP 请求中其他额外的 form data
-       * @param name 文件对应的 key , 开发者在服务器端通过这个 key 可以获取到文件二进制内容,默认key为file
-       * @param header
-       * @returns
+       * @param url 上传接口地址；支持相对路径和完整的 http/https 地址
+       * @param filePath 待上传文件的本地临时路径
+       * @param formData 额外的表单字段，会与文件一起作为 multipart/form-data 提交
+       * @param name 文件字段名；服务端通过该字段读取文件内容，默认值为 file
+       * @param header 当前上传请求的自定义请求头；会与实例级公共请求头合并
+       * @param onProgressUpdateCallback 上传进度回调；传入后会绑定到 uni.uploadFile 返回的 UploadTask.onProgressUpdate
+       * @returns 返回一个 Promise；成功时解析服务端响应中的 data 字段，失败时抛出错误信息
        */
     }, {
       key: "uploadFile",
       value: function uploadFile(url, filePath, formData) {
         var name = arguments.length > 3 && arguments[3] !== undefined ? arguments[3] : 'file';
         var header = arguments.length > 4 ? arguments[4] : undefined;
+        var onProgressUpdateCallback = arguments.length > 5 ? arguments[5] : undefined;
         return this.request({
           url: url,
           filePath: filePath,
@@ -667,7 +702,8 @@
           name: name,
           header: header,
           timeout: this.uploadTimeout,
-          method: 'POST'
+          method: 'POST',
+          onProgressUpdateCallback: onProgressUpdateCallback
         }, uploadFilePromise);
       }
     }]);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "uniapp-request-sdk",
-  "version": "1.5.1",
+  "version": "1.6.1",
   "description": "用于uniapp小程序的请求库的sdk",
   "main": "dist/index.umd.js",
   "module": " dist/index.esm.js",