uniapp-request-sdk 1.6.1 → 1.7.1

package/README.md

@@ -16,6 +16,7 @@
 - [详细配置](#详细配置)
 - [API 文档](#api-文档)
 - [文件上传](#文件上传)
+- [文件下载](#文件下载)
 - [使用示例](#使用示例)
 - [响应格式](#响应格式)
 - [错误处理](#错误处理)
@@ -31,11 +32,12 @@
 
 这个 SDK 适合以下场景：
 
-- uni-app 项目中统一封装 `GET`、`POST`、`PUT`、`DELETE`、`uploadFile`
+- uni-app 项目中统一封装 `GET`、`POST`、`PUT`、`DELETE`、`uploadFile`、`downloadFile`
 - 需要自动处理 `403` 后重新获取 token 再重试的业务场景
 - 需要为所有请求统一追加公共请求头、日志字段、签名字段
 - 需要在 App、小程序、H5 等多端尽量复用一套网络层逻辑
 - 需要在上传文件时监听进度并驱动页面上的进度条展示
+- 需要在下载文件时监听进度并驱动页面上的下载进度条展示
 
 如果你的服务端返回结构不是本文档中的默认格式，也可以基于当前 SDK 继续二次封装。
 
@@ -46,6 +48,7 @@
 - 支持同步或异步的请求头预处理器 `headerProcessor`
 - 支持 `401`、`403`、网络异常、超时等通用场景处理
 - 支持文件上传、上传超时控制和上传进度监听
+- 支持文件下载、下载超时控制和下载进度监听
 - 默认兼容相对路径与完整 URL 两种调用方式
 
 ## 特性
@@ -54,9 +57,10 @@
 - ✅ **动态 Token 管理** - 支持自动获取和更新 token，兼容 APP 原生交互
 - ✅ **请求头预处理** - 支持同步/异步预处理器，动态生成或修改请求头
 - ✅ **完整的异常处理** - 统一的错误处理、HTTP 状态码处理、权限管理
-- ✅ **文件上传支持** - 专门优化的文件上传接口，独立超时控制
+- ✅ **文件上传支持** - 专门优化的文件上传接口，独立超时控制，进度监听
+- ✅ **文件下载支持** - 专门优化的文件下载接口，独立超时控制，进度监听
 - ✅ **平台兼容** - 支持 iOS App、Android App、H5 等多平台
-- ✅ **TypeScript 支持** - 完整的类型定义，更好的开发体验
+- ✅ **TypeScript 支持** - 完整的类型定义和 JSDoc 注释，更好的开发体验
 - ✅ **完全向后兼容** - 不破坏现有代码，渐进式增强
 
 ## 安装
@@ -82,6 +86,7 @@ const request = new UniRequest({
   baseUrl: 'https://api.example.com',
   timeout: 10000,
   uploadTimeout: 30000,
+  downloadTimeout: 30000,
   tokenHeader: 'Authorization',
   tokenPrefix: 'Bearer ',
   onErrorHandler: (error) => {
@@ -104,16 +109,15 @@ export function updateUserProfile(data: Record<string, any>) {
 }
 
 export function uploadAvatar(filePath: string) {
-  return request.uploadFile(
-    '/user/avatar/upload',
-    filePath,
-    undefined,
-    'file',
-    undefined,
-    (progress) => {
-      console.log('上传进度:', progress.progress);
-    },
-  );
+  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);
+  });
 }
 ```
 
@@ -123,6 +127,8 @@ export function uploadAvatar(filePath: string) {
 - 统一错误处理能力
 - 文件上传能力
 - 上传进度监听能力
+- 文件下载能力
+- 下载进度监听能力
 
 ## 快速开始
 
@@ -160,6 +166,11 @@ const uploadResult = await request.uploadFile(
     console.log('当前上传进度:', progress.progress);
   },
 );
+
+// 7. 下载文件
+const downloadPath = await request.downloadFile('/download/document.pdf', undefined, undefined, (progress) => {
+  console.log('当前下载进度:', progress.progress);
+});
 ```
 
 ## 工程接入建议
@@ -196,40 +207,44 @@ src/
 ```typescript
 const request = new UniRequest({
   // 基础配置
-  baseUrl: 'https://api.example.com',           // API 基础地址（必须）
-  username: 'john_doe',                           // 用户名（用于日志）
+  baseUrl: 'https://api.example.com', // API 基础地址（必须）
+  username: 'john_doe', // 用户名（用于日志）
 
   // 超时设置
-  timeout: 10000,                                 // 普通请求超时（毫秒，默认 10s）
-  uploadTimeout: 5000,                            // 文件上传超时（毫秒，默认 5s）
+  timeout: 10000, // 普通请求超时（毫秒，默认 10s）
+  uploadTimeout: 5000, // 文件上传超时（毫秒，默认 5s）
 
   // 重试配置
-  maxRetryCount: 3,                               // 最大重试次数（默认 3）
-  retryDelay: 3000,                               // 重试延迟时间（毫秒，默认 3s）
+  maxRetryCount: 3, // 最大重试次数（默认 3）
+  retryDelay: 3000, // 重试延迟时间（毫秒，默认 3s）
 
   // 请求头配置
-  header: {                                       // 全局请求头
+  header: {
+    // 全局请求头
     'Content-Type': 'application/json',
     'X-Custom-Header': 'value',
   },
 
   // Token 配置
-  token: 'initial-token',                         // 初始 token
-  tokenHeader: 'Authorization',                   // token 所在的 header 字段名（默认）
-  tokenPrefix: 'Bearer ',                         // token 前缀（默认带空格）
-  tokenEventName: 'getToken',                     // 向 APP 获取 token 的事件名
-  getTokenFun: async () => {                      // 自定义获取 token 函数
+  token: 'initial-token', // 初始 token
+  tokenHeader: 'Authorization', // token 所在的 header 字段名（默认）
+  tokenPrefix: 'Bearer ', // token 前缀（默认带空格）
+  tokenEventName: 'getToken', // 向 APP 获取 token 的事件名
+  getTokenFun: async () => {
+    // 自定义获取 token 函数
     return await fetchTokenFromStorage();
   },
 
   // 错误处理
-  onErrorHandler: (error) => {                    // 统一错误处理函数
+  onErrorHandler: (error) => {
+    // 统一错误处理函数
     console.error('请求错误:', error);
     // 可以在这里上报错误日志
   },
 
   // 新增：请求头预处理
-  headerProcessor: async (header) => {            // 动态处理请求头（异步）
+  headerProcessor: async (header) => {
+    // 动态处理请求头（异步）
     const timestamp = Date.now();
     const signature = await generateSignature(timestamp);
     return {
@@ -245,9 +260,10 @@ const request = new UniRequest({
 ```typescript
 // 使用 setParams 方法动态更新配置
 request.setParams({
-  token: 'new-token',                             // 更新 token
-  baseUrl: 'https://new-api.example.com',         // 更新 API 地址
-  headerProcessor: (header) => {                  // 更新头处理器
+  token: 'new-token', // 更新 token
+  baseUrl: 'https://new-api.example.com', // 更新 API 地址
+  headerProcessor: (header) => {
+    // 更新头处理器
     return {
       'X-New-Header': 'new-value',
     };
@@ -275,7 +291,7 @@ const data = await request.get<ResponseType>(
   {},
   {
     'X-Custom-Header': 'custom-value',
-  }
+  },
 );
 ```
 
@@ -294,7 +310,7 @@ const result = await request.post<ResponseType>(
   { name: 'John' },
   {
     'X-Custom-Header': 'custom-value',
-  }
+  },
 );
 ```
 
@@ -317,29 +333,27 @@ const result = await request.put<ResponseType>('/users/1', {
 ```typescript
 // 基础文件上传
 const result = await request.uploadFile<ResponseType>(
-  '/upload',                              // 上传 URL
-  '/path/to/file.jpg'                    // 文件路径
+  '/upload', // 上传 URL
+  '/path/to/file.jpg', // 文件路径
 );
 
 // 带 FormData 的文件上传
-const result = await request.uploadFile<ResponseType>(
-  '/upload',
-  '/path/to/file.jpg',
-  {                                       // FormData 字段
-    description: 'My upload',
-    category: 'profile',
-  }
-);
+const result = await request.uploadFile<ResponseType>('/upload', '/path/to/file.jpg', {
+  // FormData 字段
+  description: 'My upload',
+  category: 'profile',
+});
 
 // 自定义文件字段名和请求头
 const result = await request.uploadFile<ResponseType>(
   '/upload',
   '/path/to/file.jpg',
   { description: 'My upload' },
-  'avatar',                               // 文件字段名（默认 'file'）
-  {                                       // 自定义请求头
+  'avatar', // 文件字段名（默认 'file'）
+  {
+    // 自定义请求头
     'X-Upload-Token': 'upload-token',
-  }
+  },
 );
 
 // 监听上传进度
@@ -353,10 +367,40 @@ const result = await request.uploadFile<ResponseType>(
     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);
+});
+```
+
 ## 文件上传
 
 ### 方法签名
@@ -374,14 +418,14 @@ uploadFile<T>(
 
 ### 参数说明
 
-| 参数 | 类型 | 是否必填 | 说明 |
-|------|------|----------|------|
-| `url` | `string` | 是 | 上传接口地址，支持相对路径和完整 URL |
-| `filePath` | `string` | 是 | 待上传文件的本地临时路径 |
-| `formData` | `Record<string, any>` | 否 | 附加的表单字段 |
-| `name` | `string` | 否 | 文件字段名，默认是 `file` |
-| `header` | `Record<string, string>` | 否 | 当前上传请求的自定义请求头 |
-| `onProgressUpdateCallback` | `(result) => void` | 否 | 上传进度回调 |
+| 参数                       | 类型                     | 是否必填 | 说明                                 |
+| -------------------------- | ------------------------ | -------- | ------------------------------------ |
+| `url`                      | `string`                 | 是       | 上传接口地址，支持相对路径和完整 URL |
+| `filePath`                 | `string`                 | 是       | 待上传文件的本地临时路径             |
+| `formData`                 | `Record<string, any>`    | 否       | 附加的表单字段                       |
+| `name`                     | `string`                 | 否       | 文件字段名，默认是 `file`            |
+| `header`                   | `Record<string, string>` | 否       | 当前上传请求的自定义请求头           |
+| `onProgressUpdateCallback` | `(result) => void`       | 否       | 上传进度回调                         |
 
 ### 上传进度回调说明
 
@@ -402,9 +446,96 @@ type OnProgressUpdateResult = {
 - `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：基础请求
@@ -436,7 +567,7 @@ import UniRequest from 'uniapp-request-sdk';
 
 const request = new UniRequest({
   baseUrl: 'https://api.example.com',
-  tokenEventName: 'getToken',  // APP 端事件名
+  tokenEventName: 'getToken', // APP 端事件名
   onErrorHandler: (error) => {
     if (error.statusCode === 401) {
       console.log('用户已登出');
@@ -489,7 +620,7 @@ import UniRequest from 'uniapp-request-sdk';
 
 const request = new UniRequest({
   baseUrl: 'https://api.example.com',
-  uploadTimeout: 30000,  // 文件上传超时 30 秒
+  uploadTimeout: 30000, // 文件上传超时 30 秒
 });
 
 // 选择文件并上传
@@ -498,15 +629,11 @@ async function selectAndUploadFile() {
     count: 1,
     success: async (res) => {
       try {
-        const result = await request.uploadFile(
-          '/upload',
-          res.tempFilePaths[0],
-          {
-            // 附加信息
-            description: '头像',
-            category: 'avatar',
-          }
-        );
+        const result = await request.uploadFile('/upload', res.tempFilePaths[0], {
+          // 附加信息
+          description: '头像',
+          category: 'avatar',
+        });
         console.log('上传成功:', result);
       } catch (error) {
         console.error('上传失败:', error);
@@ -557,6 +684,226 @@ async function selectAndUploadFile() {
 }
 ```
 
+### 示例 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
@@ -596,6 +943,7 @@ const request = new UniRequest({
 ```
 
 其中：
+
 - `errno === 0` 表示请求成功
 - `errno !== 0` 表示业务错误，会触发 reject
 
@@ -603,13 +951,13 @@ const request = new UniRequest({
 
 ### 自动处理的错误
 
-| 错误类型 | 处理方式 |
-|---------|---------|
-| HTTP 403 | 自动获取新 token 并重试 |
+| 错误类型 | 处理方式                              |
+| -------- | ------------------------------------- |
+| HTTP 403 | 自动获取新 token 并重试               |
 | HTTP 401 | 触发 logout 事件，通知 APP 返回登录页 |
-| 网络错误 | 自动重试（最多 maxRetryCount 次） |
-| 超时错误 | 自动重试（最多 maxRetryCount 次） |
-| 业务错误 | 直接 reject，业务处理 |
+| 网络错误 | 自动重试（最多 maxRetryCount 次）     |
+| 超时错误 | 自动重试（最多 maxRetryCount 次）     |
+| 业务错误 | 直接 reject，业务处理                 |
 
 ### 全局错误处理
 
@@ -667,28 +1015,28 @@ const request = new UniRequest({
 
 ```typescript
 const request = new UniRequest({
-  tokenEventName: 'getToken',  // APP 端对应事件名
+  tokenEventName: 'getToken', // APP 端对应事件名
 });
 ```
 
 ## 配置参数详解
 
-| 参数 | 类型 | 默认值 | 必填 | 说明 |
-|-----|------|-------|------|------|
-| baseUrl | string | - | ✅ | API 基础地址，支持代理路径 |
-| timeout | number | 10000 | - | 普通请求超时（毫秒） |
-| uploadTimeout | number | 5000 | - | 文件上传超时（毫秒） |
-| maxRetryCount | number | 3 | - | 失败重试次数 |
-| retryDelay | number | 3000 | - | 重试延迟时间（毫秒） |
-| header | object | - | - | 全局请求头 |
-| headerProcessor | function | - | - | 请求头预处理函数（新增） |
-| token | string | - | - | 初始 token |
-| tokenHeader | string | Authorization | - | token 所在 header 字段 |
-| tokenPrefix | string | 'Bearer ' | - | token 前缀 |
-| tokenEventName | string | getToken | - | APP 获取 token 的事件名 |
-| getTokenFun | function | - | - | 自定义 token 获取函数 |
-| username | string | - | - | 用户名（用于日志） |
-| onErrorHandler | function | console.error | - | 全局错误处理函数 |
+| 参数            | 类型     | 默认值        | 必填 | 说明                       |
+| --------------- | -------- | ------------- | ---- | -------------------------- |
+| baseUrl         | string   | -             | ✅   | API 基础地址，支持代理路径 |
+| timeout         | number   | 10000         | -    | 普通请求超时（毫秒）       |
+| uploadTimeout   | number   | 5000          | -    | 文件上传超时（毫秒）       |
+| maxRetryCount   | number   | 3             | -    | 失败重试次数               |
+| retryDelay      | number   | 3000          | -    | 重试延迟时间（毫秒）       |
+| header          | object   | -             | -    | 全局请求头                 |
+| headerProcessor | function | -             | -    | 请求头预处理函数（新增）   |
+| token           | string   | -             | -    | 初始 token                 |
+| tokenHeader     | string   | Authorization | -    | token 所在 header 字段     |
+| tokenPrefix     | string   | 'Bearer '     | -    | token 前缀                 |
+| tokenEventName  | string   | getToken      | -    | APP 获取 token 的事件名    |
+| getTokenFun     | function | -             | -    | 自定义 token 获取函数      |
+| username        | string   | -             | -    | 用户名（用于日志）         |
+| onErrorHandler  | function | console.error | -    | 全局错误处理函数           |
 
 ## 请求头预处理器（新增功能）
 
@@ -757,7 +1105,7 @@ const request = new UniRequest({
 ### 预处理器的执行时机
 
 - **执行点**：在设置 token 后、发送请求前
-- **执行频率**：每次请求都执行（包括重试）
+- **执行频率**：每次业务请求执行一次，自动重试时复用第一次处理后的 header；若中途刷新 token，则会基于新 token 重新执行一次
 - **异常处理**：如果预处理器异常，请求会直接 reject，不会发送
 
 ### 预处理器的签名
@@ -838,15 +1186,15 @@ async function getUsers() {
 ```typescript
 // ❌ 错误：每次请求都会等待 5 秒
 headerProcessor: async () => {
-  await sleep(5000);  // 不必要的延迟
+  await sleep(5000); // 不必要的延迟
   return {};
-}
+};
 
 // ✅ 正确：提前准备数据
 headerProcessor: async () => {
   const cachedData = await cache.get('businessData');
   return { 'X-Business-Id': cachedData.id };
-}
+};
 ```
 
 3. **不要在头预处理器中设置 cookie（H5 平台）**
@@ -854,13 +1202,13 @@ headerProcessor: async () => {
 ```typescript
 // ❌ 错误：H5 中不生效
 headerProcessor: async () => {
-  return { 'cookie': 'sessionid=xxx' };
-}
+  return { cookie: 'sessionid=xxx' };
+};
 
 // ✅ 正确：使用其他方式
 headerProcessor: async () => {
   return { 'X-Session-Id': 'xxx' };
-}
+};
 ```
 
 ## 企业级实战案例
@@ -917,16 +1265,16 @@ function onErrorHandler(resData: any) {
 
 // 主请求实例（用于常规业务请求）
 export const requestInstance = new UniRequest({
-  timeout: 4000,                    // 请求超时 4 秒
-  maxRetryCount: 2,                 // 重试 2 次
-  uploadTimeout: 1000 * 60 * 2,     // 文件上传超时 2 分钟
-  onErrorHandler,                   // 使用统一错误处理
+  timeout: 4000, // 请求超时 4 秒
+  maxRetryCount: 2, // 重试 2 次
+  uploadTimeout: 1000 * 60 * 2, // 文件上传超时 2 分钟
+  onErrorHandler, // 使用统一错误处理
 });
 
 // AI 请求实例（用于 AI 接口请求）
 export const aiRequestInstance = new UniRequest({
-  uploadTimeout: 1000 * 20,         // 上传超时 20 秒
-  maxRetryCount: 0,                 // 不重试（AI 接口可能耗时较长）
+  uploadTimeout: 1000 * 20, // 上传超时 20 秒
+  maxRetryCount: 0, // 不重试（AI 接口可能耗时较长）
   onErrorHandler,
 });
 ```
@@ -947,8 +1295,7 @@ export const ProcessServes = {
     requestInstance.post<{ data: any }>('/process/application/business/readProcessMessage', payload),
 
   // 查询申请人职位
-  getById: (payload: { id: string }) =>
-    requestInstance.post('/usercenter/oaUser/getById', payload),
+  getById: (payload: { id: string }) => requestInstance.post('/usercenter/oaUser/getById', payload),
 
   // 撤回流程
   processRecall: (payload: { businessId: string; processCategory: string; comment: string }) =>
@@ -959,8 +1306,7 @@ export const ProcessServes = {
     requestInstance.post<{ data: any[] }>('/process/application/matter/list', payload),
 
   // 获取事项信息
-  getMatterInfo: (payload: any) =>
-    requestInstance.post('/process/application/matter/matterInfo', payload),
+  getMatterInfo: (payload: any) => requestInstance.post('/process/application/matter/matterInfo', payload),
 
   // 流程审批
   processApprove: (payload: {
@@ -970,12 +1316,10 @@ export const ProcessServes = {
     comment: string;
     pass: boolean;
     attachment: Array<{ name: string; url: string }>;
-  }) =>
-    requestInstance.post('/process/application/process/approve', payload),
+  }) => requestInstance.post('/process/application/process/approve', payload),
 
   // 保存并审批
-  processSaveAndApprove: (payload: any) =>
-    requestInstance.post('/process/application/process/saveAndApprove', payload),
+  processSaveAndApprove: (payload: any) => requestInstance.post('/process/application/process/saveAndApprove', payload),
 
   // 保存流程
   processSave: (payload: {
@@ -988,8 +1332,7 @@ export const ProcessServes = {
     sponsorDepartmentId: string;
     processCategory: string;
     businessId?: string;
-  }) =>
-    requestInstance.post('/process/application/business/save', payload),
+  }) => requestInstance.post('/process/application/business/save', payload),
 
   // 申请流程
   processApply: (payload: { businessId: string; ccUser: any[]; processCategory: string }) =>
@@ -1020,12 +1363,10 @@ export const ProcessServes = {
     departmentId: string;
     subjects: string[];
     businessLineUuids: string[];
-  }) =>
-    requestInstance.post('/financial/budgetInventory/budgetInventoryProgress', payload),
+  }) => requestInstance.post('/financial/budgetInventory/budgetInventoryProgress', payload),
 
   // 获取业务线列表
-  getBusinessLineList: () =>
-    requestInstance.post('financial/businessLine/businessLineList'),
+  getBusinessLineList: () => requestInstance.post('financial/businessLine/businessLineList'),
 
   // 获取合同详情
   getContractDetail: (payload: { contractNumber: string; businessId: string }) =>
@@ -1167,6 +1508,7 @@ export default {
 项目使用两个不同的请求实例：
 
 - **requestInstance**: 用于常规业务请求
+
   - 超时时间：4 秒
   - 重试次数：2 次
   - 适合快速响应的 API
@@ -1179,6 +1521,7 @@ export default {
 ##### 统一错误处理
 
 所有错误都通过 `onErrorHandler` 函数处理：
+
 - 业务错误（errno = 2002）：显示错误信息，关闭小程序
 - 权限错误（statusCode = 403）：引导用户重新登录
 - 其他错误：显示通用错误信息
@@ -1186,6 +1529,7 @@ export default {
 ##### API 层封装
 
 将所有 API 调用封装在专门的服务文件中：
+
 - 统一的错误处理
 - 类型安全的请求和响应
 - 易于测试和维护
@@ -1201,8 +1545,6 @@ export default {
 ✅ **类型安全** - 充分利用 TypeScript 的泛型机制
 ✅ **易于扩展** - 新 API 添加无需修改现有代码
 
-
-
 ## 常见问题
 
 ### Q: 如何处理跨域问题？
@@ -1211,7 +1553,7 @@ A: 在 `baseUrl` 中包含代理路径，让后端或开发服务器代理请求
 
 ```typescript
 const request = new UniRequest({
-  baseUrl: 'https://localhost:8080/api/proxy/',  // 包含代理路径
+  baseUrl: 'https://localhost:8080/api/proxy/', // 包含代理路径
 });
 ```
 
@@ -1226,11 +1568,93 @@ for (const filePath of filePaths) {
 }
 
 // 方式 2：并行上传（不推荐，可能导致超时）
-await Promise.all(
-  filePaths.map(filePath => request.uploadFile('/upload', filePath))
-);
+await Promise.all(filePaths.map((filePath) => request.uploadFile('/upload', filePath)));
 ```
 
+### 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 并重试。如需自定义逻辑：
@@ -1255,16 +1679,45 @@ A: 设置 `maxRetryCount` 为 0。
 
 ```typescript
 const request = new UniRequest({
-  maxRetryCount: 0,  // 禁用重试
+  maxRetryCount: 0, // 禁用重试
 });
 ```
 
 ### Q: headerProcessor 每次都会执行吗？
 
-A: 是的，包括重试时都会执行。这是为了确保每次请求都获得最新的 header 值（如动态生成的签名）。
+A: 每次调用 `request` / `get` / `post` 等接口时都会执行一次；如果该次请求触发自动重试，会复用第一次处理后的 header，不会重复执行。这可以保证同一次业务请求在重试时复用同一个幂等 header。唯一例外是 `403` 刷新 token 成功后，SDK 会基于新 token 重新生成一次 header，再立即重试。
 
 ## 版本历史
 
+### v1.6.2（最新）
+
+- ✨ **新增** 文件下载功能 (`downloadFile` 方法)
+
+  - 支持下载文件到本地目录或临时目录
+  - 支持实时下载进度监听
+  - 支持自定义请求头
+  - 自动继承 token、重试等企业级特性
+  - 默认超时时间 30 秒（可配置）
+
+- 📝 **文档改进** 完整的 JSDoc 注释
+
+  - 所有公开/私有方法添加详细 JSDoc
+  - 所有参数和返回值有清晰说明
+  - 关键方法包含使用示例
+  - 100% 注释覆盖率
+
+- 📚 **README 更新**
+
+  - 新增《文件下载》文档章节
+  - 新增文件下载的详细使用示例（示例 4-2、4-3）
+  - 更新目录索引
+  - 完善参数和平台兼容性说明
+
+- 🔧 **技术改进**
+  - 优化 TypeScript 类型定义
+  - 完善错误处理机制
+  - 增强跨平台兼容性检查
+
 ### v1.4.11
 
 - ✨ **新增** 请求头预处理器功能 (`headerProcessor`)