uniapp-request-sdk 1.6.0 → 1.7.0

package/README.md

@@ -5,15 +5,62 @@
 [![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`、`downloadFile`
+- 需要自动处理 `403` 后重新获取 token 再重试的业务场景
+- 需要为所有请求统一追加公共请求头、日志字段、签名字段
+- 需要在 App、小程序、H5 等多端尽量复用一套网络层逻辑
+- 需要在上传文件时监听进度并驱动页面上的进度条展示
+- 需要在下载文件时监听进度并驱动页面上的下载进度条展示
+
+如果你的服务端返回结构不是本文档中的默认格式，也可以基于当前 SDK 继续二次封装。
+
+## 核心能力
+
+- 统一的请求实例管理，支持运行时动态更新参数
+- 支持全局公共请求头与单次请求头合并
+- 支持同步或异步的请求头预处理器 `headerProcessor`
+- 支持 `401`、`403`、网络异常、超时等通用场景处理
+- 支持文件上传、上传超时控制和上传进度监听
+- 支持文件下载、下载超时控制和下载进度监听
+- 默认兼容相对路径与完整 URL 两种调用方式
+
 ## 特性
 
 - ✅ **自动重试机制** - 请求失败自动重试，可配置重试次数和延迟
 - ✅ **动态 Token 管理** - 支持自动获取和更新 token，兼容 APP 原生交互
 - ✅ **请求头预处理** - 支持同步/异步预处理器，动态生成或修改请求头
 - ✅ **完整的异常处理** - 统一的错误处理、HTTP 状态码处理、权限管理
-- ✅ **文件上传支持** - 专门优化的文件上传接口，独立超时控制
+- ✅ **文件上传支持** - 专门优化的文件上传接口，独立超时控制，进度监听
+- ✅ **文件下载支持** - 专门优化的文件下载接口，独立超时控制，进度监听
 - ✅ **平台兼容** - 支持 iOS App、Android App、H5 等多平台
-- ✅ **TypeScript 支持** - 完整的类型定义，更好的开发体验
+- ✅ **TypeScript 支持** - 完整的类型定义和 JSDoc 注释，更好的开发体验
 - ✅ **完全向后兼容** - 不破坏现有代码，渐进式增强
 
 ## 安装
@@ -30,6 +77,71 @@ 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,
+  downloadTimeout: 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);
+    },
+  );
+}
+
+export function downloadDocument(documentId: string) {
+  return request.downloadFile(
+    `/documents/${documentId}/download`,
+    undefined,
+    undefined,
+    (progress) => {
+      console.log('下载进度:', progress.progress);
+    },
+  );
+}
+```
+
+完成以上两步后，你的工程已经具备：
+
+- 统一请求入口
+- 统一错误处理能力
+- 文件上传能力
+- 上传进度监听能力
+- 文件下载能力
+- 下载进度监听能力
+
 ## 快速开始
 
 ### 基础使用
@@ -58,10 +170,53 @@ 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);
+  },
+);
+
+// 7. 下载文件
+const downloadPath = await request.downloadFile(
+  '/download/document.pdf',
+  undefined,
+  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 +369,191 @@ 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
+// 基础文件下载
+const tempFilePath = await request.downloadFile('/download/file.pdf');
+
+// 带自定义保存路径的下载（仅小程序有效）
+const filePath = await request.downloadFile(
+  '/download/file.pdf',
+  'user_documents/file.pdf'               // 本地保存路径（仅小程序平台支持）
+);
+
+// 自定义请求头的下载
+const filePath = await request.downloadFile(
+  '/download/file.pdf',
+  undefined,                              // 保存路径
+  {                                       // 自定义请求头
+    'X-Download-Token': 'download-token',
+  }
+);
+
+// 监听下载进度
+const filePath = await request.downloadFile(
+  '/download/large-file.zip',
+  undefined,
+  undefined,
+  (progress) => {
+    console.log('下载进度百分比:', progress.progress);
+    console.log('已下载字节数:', progress.totalBytesWritten);
+    console.log('总字节数:', progress.totalBytesExpectedToWrite);
+  }
+);
+```
+
+## 文件上传
+
+### 方法签名
+
+```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`
+
+## 文件下载
+
+### 新增功能说明
+
+从 v1.6.2 版本开始，SDK 新增了 `downloadFile` 方法，提供与 `uploadFile` 对称的文件下载功能。支持：
+
+- ✅ 下载文件到本地临时目录或指定路径
+- ✅ 自定义请求头
+- ✅ 实时下载进度监听
+- ✅ 自动重试、Token 管理等企业级特性
+- ✅ 跨平台兼容（App、小程序、H5）
+
+### 方法签名
+
+```typescript
+downloadFile<T extends string = string>(
+  url: string,
+  filePath?: string,
+  header?: Record<string, string>,
+  onProgressUpdateCallback?: (result: DownloadFileProgressUpdateResult) => void,
+): Promise<T>
+```
+
+### 参数说明
+
+| 参数 | 类型 | 是否必填 | 说明 |
+|------|------|----------|------|
+| `url` | `string` | 是 | 下载资源的 URL，支持相对路径和完整 URL |
+| `filePath` | `string` | 否 | 文件保存路径（本地路径），仅小程序平台支持；如不指定则保存到临时目录 |
+| `header` | `Record<string, string>` | 否 | 当前下载请求的自定义请求头 |
+| `onProgressUpdateCallback` | `(result) => void` | 否 | 下载进度回调 |
+
+### 返回值说明
+
+方法返回 Promise，解析为下载文件的临时路径（`tempFilePath`）：
+
+```typescript
+// 基础用法
+const filePath = await request.downloadFile('/files/document.pdf');
+// filePath 是文件的临时路径，如 '/tmp/file_20240314.pdf'
+
+// 支持泛型约束
+const filePath: string = await request.downloadFile<string>('/files/document.pdf');
+```
+
+### 下载进度回调说明
+
+当传入 `onProgressUpdateCallback` 后，SDK 会在内部调用 `uni.downloadFile()` 返回的 `DownloadTask.onProgressUpdate()` 进行绑定。
+
+回调参数结构如下：
+
+```typescript
+type DownloadFileProgressUpdateResult = {
+  progress?: number;                      // 下载进度百分比 (0-100)
+  totalBytesWritten?: number;             // 已下载字节数
+  totalBytesExpectedToWrite?: number;     // 总字节数
+};
+```
+
+### 与上传的区别
+
+| 特性 | uploadFile | downloadFile |
+|------|-----------|--------------|
+| 超时默认值 | 5 秒 | 30 秒 |
+| 文件来源 | 本地文件 | 远程 URL |
+| 附加参数 | formData（表单字段） | filePath（保存路径） |
+| 进度类型 | `totalBytesSent` | `totalBytesWritten` |
+| 返回值 | 服务端响应的 data 字段 | 文件临时路径 |
+
+### 平台兼容性
+
+| 特性 | iOS App | Android App | 小程序 | H5 |
+|------|---------|-----------|--------|-----|
+| 基础下载 | ✅ | ✅ | ✅ | ✅ |
+| 进度监听 | ✅ | ✅ | ✅ | 部分 |
+| 自定义保存路径 | ❌ | ❌ | ✅ | ❌ |
+| 文件 URI | ✅ | ✅ | ✅ | 部分 |
+
+### 使用注意事项
+
+- 下载的文件保存在临时目录，应用关闭后会被清理，需要持久化时调用 `uni.saveFile()`
+- 小程序平台支持指定 `filePath` 保存到指定目录，其他平台会忽略此参数
+- 下载超时时间默认为 30 秒，可通过 `downloadTimeout` 配置修改
+- 下载过程中如果失败，SDK 会自动重试（最多 `maxRetryCount` 次）
+- 下载大文件时建议增加 `downloadTimeout` 的值
+- 下载过程中用户可以通过返回的 Promise 的 abort 功能中止下载（需要获取 DownloadTask）
+
 ## 使用示例
 
 ### 示例 1：基础请求
@@ -327,6 +665,275 @@ 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);
+      }
+    },
+  });
+}
+```
+
+### 示例 4-2：文件下载（新增）
+
+```typescript
+import UniRequest from 'uniapp-request-sdk';
+
+const request = new UniRequest({
+  baseUrl: 'https://api.example.com',
+  downloadTimeout: 30000,  // 文件下载超时 30 秒
+});
+
+// 简单下载
+async function downloadFile() {
+  try {
+    const filePath = await request.downloadFile('/files/document.pdf');
+    console.log('下载完成，文件路径:', filePath);
+
+    // 显示文件
+    uni.openDocument({
+      filePath: filePath,
+      showMenu: true,
+    });
+  } catch (error) {
+    console.error('下载失败:', error);
+  }
+}
+
+// 带进度监听的下载
+async function downloadFileWithProgress() {
+  try {
+    let downloadProgress = 0;
+
+    const filePath = await request.downloadFile(
+      '/files/large-file.zip',
+      undefined,
+      undefined,
+      (progress) => {
+        downloadProgress = progress.progress || 0;
+        console.log(`下载进度: ${downloadProgress}%`);
+        console.log(`已下载: ${progress.totalBytesWritten} / ${progress.totalBytesExpectedToWrite} 字节`);
+
+        // 更新 UI 进度条
+        // updateProgressBar(downloadProgress);
+      }
+    );
+
+    console.log('下载完成:', filePath);
+  } catch (error) {
+    console.error('下载失败:', error, downloadProgress);
+  }
+}
+
+// 小程序中下载到指定路径
+async function downloadFileToPath() {
+  try {
+    const filePath = await request.downloadFile(
+      '/files/contract.pdf',
+      'user_documents/contract.pdf'  // 保存到应用沙箱
+    );
+
+    console.log('文件已保存:', filePath);
+  } catch (error) {
+    console.error('下载失败:', error);
+  }
+}
+
+// 带自定义 header 的下载（如需要鉴权）
+async function downloadSecureFile() {
+  try {
+    const filePath = await request.downloadFile(
+      '/files/secure-document.pdf',
+      undefined,
+      {
+        'X-Download-Token': 'secure-token-xxx',
+        'X-User-Id': 'user-123',
+      },
+      (progress) => {
+        console.log(`下载进度: ${progress.progress}%`);
+      }
+    );
+
+    console.log('下载完成:', filePath);
+  } catch (error) {
+    console.error('下载失败:', error);
+  }
+}
+```
+
+### 示例 4-3：综合文件管理（上传和下载）
+
+```typescript
+import UniRequest from 'uniapp-request-sdk';
+
+const request = new UniRequest({
+  baseUrl: 'https://api.example.com',
+  uploadTimeout: 30000,
+  downloadTimeout: 30000,
+});
+
+// 文件管理服务
+export const FileService = {
+  // 上传文件
+  uploadDocument: async (filePath: string, metadata: Record<string, any>) => {
+    try {
+      const result = await request.uploadFile(
+        '/documents/upload',
+        filePath,
+        metadata,
+        'file',
+        undefined,
+        (progress) => {
+          console.log(`上传进度: ${progress.progress}%`);
+        }
+      );
+      return result;
+    } catch (error) {
+      console.error('上传失败:', error);
+      throw error;
+    }
+  },
+
+  // 下载文件
+  downloadDocument: async (documentId: string, fileName: string) => {
+    try {
+      const filePath = await request.downloadFile(
+        `/documents/download/${documentId}`,
+        `downloads/${fileName}`,
+        { 'X-Document-Id': documentId },
+        (progress) => {
+          console.log(`下载进度: ${progress.progress}%`);
+        }
+      );
+      return filePath;
+    } catch (error) {
+      console.error('下载失败:', error);
+      throw error;
+    }
+  },
+
+  // 列出文档
+  listDocuments: async (payload: Record<string, any>) => {
+    return request.post('/documents/list', payload);
+  },
+
+  // 删除文档
+  deleteDocument: async (documentId: string) => {
+    return request.delete(`/documents/${documentId}`);
+  },
+};
+
+// 在组件中使用
+export default {
+  data() {
+    return {
+      uploadProgress: 0,
+      downloadProgress: 0,
+      documents: [],
+    };
+  },
+
+  methods: {
+    // 选择并上传文件
+    async selectAndUpload() {
+      try {
+        const res = await uni.chooseFile({
+          type: 'file',
+          count: 1,
+        });
+
+        const result = await FileService.uploadDocument(
+          res.tempFilePaths[0],
+          {
+            description: '重要文档',
+            category: 'reports',
+          }
+        );
+
+        uni.showToast({
+          title: '上传成功',
+          icon: 'success',
+        });
+
+        // 刷新列表
+        await this.loadDocuments();
+      } catch (error) {
+        uni.showToast({
+          title: '上传失败',
+          icon: 'error',
+        });
+      }
+    },
+
+    // 下载文件
+    async downloadDocument(documentId: string, fileName: string) {
+      try {
+        const filePath = await FileService.downloadDocument(documentId, fileName);
+
+        // 打开文件
+        uni.openDocument({
+          filePath: filePath,
+          showMenu: true,
+        });
+      } catch (error) {
+        uni.showToast({
+          title: '下载失败',
+          icon: 'error',
+        });
+      }
+    },
+
+    // 加载文档列表
+    async loadDocuments() {
+      try {
+        this.documents = await FileService.listDocuments({
+          page: 1,
+          limit: 20,
+        });
+      } catch (error) {
+        console.error('加载失败:', error);
+      }
+    },
+  },
+
+  mounted() {
+    this.loadDocuments();
+  },
+};
+```
+
 ### 示例 5：实时生成签名
 
 ```typescript
@@ -973,6 +1580,8 @@ export default {
 
 
 
+## 常见问题
+
 ### Q: 如何处理跨域问题？
 
 A: 在 `baseUrl` 中包含代理路径，让后端或开发服务器代理请求。
@@ -999,6 +1608,97 @@ await Promise.all(
 );
 ```
 
+### Q: 如何下载多个文件？
+
+A: 需要多次调用 `downloadFile`，建议使用串行下载避免超时：
+
+```typescript
+// 方式 1：顺序下载（推荐）
+const filePaths = [];
+for (const fileUrl of fileUrls) {
+  const path = await request.downloadFile(fileUrl);
+  filePaths.push(path);
+}
+
+// 方式 2：并行下载（需谨慎，可能导致超时）
+const filePaths = await Promise.all(
+  fileUrls.map(fileUrl => request.downloadFile(fileUrl))
+);
+```
+
+### Q: 下载的文件如何持久化？
+
+A: 使用 `uni.saveFile()` 将临时文件保存到永久目录：
+
+```typescript
+const tempFilePath = await request.downloadFile('/file.pdf');
+
+// 保存到永久位置
+uni.saveFile({
+  tempFilePath: tempFilePath,
+  success: (res) => {
+    console.log('文件已保存:', res.savedFilePath);
+  },
+});
+```
+
+### Q: 下载大文件时超时怎么办？
+
+A: 增加 `downloadTimeout` 的值：
+
+```typescript
+const request = new UniRequest({
+  baseUrl: 'https://api.example.com',
+  downloadTimeout: 60000,  // 60 秒，适合大文件
+});
+
+// 或在运行时修改
+request.setParams({
+  downloadTimeout: 120000,  // 120 秒
+});
+```
+
+### Q: 如何取消正在进行的下载？
+
+A: 目前库返回的是 Promise，无法直接获取 DownloadTask 来调用 abort。建议通过以下方式实现：
+
+```typescript
+// 方式 1：修改库的源码返回 DownloadTask（高级用法）
+// 方式 2：使用超时机制让请求自动中止
+// 方式 3：在下载进度回调中检查用户是否点击了取消
+
+// 推荐：在进度回调中检查状态
+let shouldCancel = false;
+
+await request.downloadFile(
+  '/file.zip',
+  undefined,
+  undefined,
+  (progress) => {
+    if (shouldCancel) {
+      // 无法直接中止，但可以停止处理
+      return;
+    }
+    console.log(`下载进度: ${progress.progress}%`);
+  }
+);
+
+// 用户点击取消按钮时
+function cancelDownload() {
+  shouldCancel = true;
+}
+```
+
+### Q: 下载的文件在哪里？
+
+A: 下载的文件保存在以下位置：
+
+- **H5**: 浏览器默认下载目录
+- **小程序**: 临时目录（`wx.env.USER_DATA_PATH` 下），或指定的 `filePath`
+- **App**: 应用的缓存目录
+
+建议下载后立即使用或保存，避免应用被清理时文件丢失。
+
 ### Q: 如何处理 token 过期？
 
 A: 库会自动在收到 403 状态码时获取新 token 并重试。如需自定义逻辑：
@@ -1033,6 +1733,32 @@ A: 是的，包括重试时都会执行。这是为了确保每次请求都获
 
 ## 版本历史
 
+### v1.6.2（最新）
+
+- ✨ **新增** 文件下载功能 (`downloadFile` 方法)
+  - 支持下载文件到本地目录或临时目录
+  - 支持实时下载进度监听
+  - 支持自定义请求头
+  - 自动继承 token、重试等企业级特性
+  - 默认超时时间 30 秒（可配置）
+
+- 📝 **文档改进** 完整的 JSDoc 注释
+  - 所有公开/私有方法添加详细 JSDoc
+  - 所有参数和返回值有清晰说明
+  - 关键方法包含使用示例
+  - 100% 注释覆盖率
+
+- 📚 **README 更新**
+  - 新增《文件下载》文档章节
+  - 新增文件下载的详细使用示例（示例 4-2、4-3）
+  - 更新目录索引
+  - 完善参数和平台兼容性说明
+
+- 🔧 **技术改进**
+  - 优化 TypeScript 类型定义
+  - 完善错误处理机制
+  - 增强跨平台兼容性检查
+
 ### v1.4.11
 
 - ✨ **新增** 请求头预处理器功能 (`headerProcessor`)