uniapp-request-sdk 1.7.0 → 1.7.1

package/README.md

@@ -109,27 +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);
-    },
-  );
+  return request.downloadFile(`/documents/${documentId}/download`, undefined, undefined, (progress) => {
+    console.log('下载进度:', progress.progress);
+  });
 }
 ```
 
@@ -180,14 +168,9 @@ const uploadResult = await request.uploadFile(
 );
 
 // 7. 下载文件
-const downloadPath = await request.downloadFile(
-  '/download/document.pdf',
-  undefined,
-  undefined,
-  (progress) => {
-    console.log('当前下载进度:', progress.progress);
-  },
-);
+const downloadPath = await request.downloadFile('/download/document.pdf', undefined, undefined, (progress) => {
+  console.log('当前下载进度:', progress.progress);
+});
 ```
 
 ## 工程接入建议
@@ -224,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 {
@@ -273,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',
     };
@@ -303,7 +291,7 @@ const data = await request.get<ResponseType>(
   {},
   {
     'X-Custom-Header': 'custom-value',
-  }
+  },
 );
 ```
 
@@ -322,7 +310,7 @@ const result = await request.post<ResponseType>(
   { name: 'John' },
   {
     'X-Custom-Header': 'custom-value',
-  }
+  },
 );
 ```
 
@@ -345,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',
-  }
+  },
 );
 
 // 监听上传进度
@@ -381,7 +367,7 @@ const result = await request.uploadFile<ResponseType>(
     console.log('上传进度百分比:', progress.progress);
     console.log('已上传字节数:', progress.totalBytesSent);
     console.log('总字节数:', progress.totalBytesExpectedToSend);
-  }
+  },
 );
 ```
 
@@ -394,29 +380,25 @@ const tempFilePath = await request.downloadFile('/download/file.pdf');
 // 带自定义保存路径的下载（仅小程序有效）
 const filePath = await request.downloadFile(
   '/download/file.pdf',
-  'user_documents/file.pdf'               // 本地保存路径（仅小程序平台支持）
+  'user_documents/file.pdf', // 本地保存路径（仅小程序平台支持）
 );
 
 // 自定义请求头的下载
 const filePath = await request.downloadFile(
   '/download/file.pdf',
-  undefined,                              // 保存路径
-  {                                       // 自定义请求头
+  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);
-  }
-);
+const filePath = await request.downloadFile('/download/large-file.zip', undefined, undefined, (progress) => {
+  console.log('下载进度百分比:', progress.progress);
+  console.log('已下载字节数:', progress.totalBytesWritten);
+  console.log('总字节数:', progress.totalBytesExpectedToWrite);
+});
 ```
 
 ## 文件上传
@@ -436,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`       | 否       | 上传进度回调                         |
 
 ### 上传进度回调说明
 
@@ -492,12 +474,12 @@ downloadFile<T extends string = string>(
 
 ### 参数说明
 
-| 参数 | 类型 | 是否必填 | 说明 |
-|------|------|----------|------|
-| `url` | `string` | 是 | 下载资源的 URL，支持相对路径和完整 URL |
-| `filePath` | `string` | 否 | 文件保存路径（本地路径），仅小程序平台支持；如不指定则保存到临时目录 |
-| `header` | `Record<string, string>` | 否 | 当前下载请求的自定义请求头 |
-| `onProgressUpdateCallback` | `(result) => void` | 否 | 下载进度回调 |
+| 参数                       | 类型                     | 是否必填 | 说明                                                                 |
+| -------------------------- | ------------------------ | -------- | -------------------------------------------------------------------- |
+| `url`                      | `string`                 | 是       | 下载资源的 URL，支持相对路径和完整 URL                               |
+| `filePath`                 | `string`                 | 否       | 文件保存路径（本地路径），仅小程序平台支持；如不指定则保存到临时目录 |
+| `header`                   | `Record<string, string>` | 否       | 当前下载请求的自定义请求头                                           |
+| `onProgressUpdateCallback` | `(result) => void`       | 否       | 下载进度回调                                                         |
 
 ### 返回值说明
 
@@ -520,30 +502,30 @@ const filePath: string = await request.downloadFile<string>('/files/document.pdf
 
 ```typescript
 type DownloadFileProgressUpdateResult = {
-  progress?: number;                      // 下载进度百分比 (0-100)
-  totalBytesWritten?: number;             // 已下载字节数
-  totalBytesExpectedToWrite?: number;     // 总字节数
+  progress?: number; // 下载进度百分比 (0-100)
+  totalBytesWritten?: number; // 已下载字节数
+  totalBytesExpectedToWrite?: number; // 总字节数
 };
 ```
 
 ### 与上传的区别
 
-| 特性 | uploadFile | downloadFile |
-|------|-----------|--------------|
-| 超时默认值 | 5 秒 | 30 秒 |
-| 文件来源 | 本地文件 | 远程 URL |
-| 附加参数 | formData（表单字段） | filePath（保存路径） |
-| 进度类型 | `totalBytesSent` | `totalBytesWritten` |
-| 返回值 | 服务端响应的 data 字段 | 文件临时路径 |
+| 特性       | uploadFile             | downloadFile         |
+| ---------- | ---------------------- | -------------------- |
+| 超时默认值 | 5 秒                   | 30 秒                |
+| 文件来源   | 本地文件               | 远程 URL             |
+| 附加参数   | formData（表单字段）   | filePath（保存路径） |
+| 进度类型   | `totalBytesSent`       | `totalBytesWritten`  |
+| 返回值     | 服务端响应的 data 字段 | 文件临时路径         |
 
 ### 平台兼容性
 
-| 特性 | iOS App | Android App | 小程序 | H5 |
-|------|---------|-----------|--------|-----|
-| 基础下载 | ✅ | ✅ | ✅ | ✅ |
-| 进度监听 | ✅ | ✅ | ✅ | 部分 |
-| 自定义保存路径 | ❌ | ❌ | ✅ | ❌ |
-| 文件 URI | ✅ | ✅ | ✅ | 部分 |
+| 特性           | iOS App | Android App | 小程序 | H5   |
+| -------------- | ------- | ----------- | ------ | ---- |
+| 基础下载       | ✅      | ✅          | ✅     | ✅   |
+| 进度监听       | ✅      | ✅          | ✅     | 部分 |
+| 自定义保存路径 | ❌      | ❌          | ✅     | ❌   |
+| 文件 URI       | ✅      | ✅          | ✅     | 部分 |
 
 ### 使用注意事项
 
@@ -585,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('用户已登出');
@@ -638,7 +620,7 @@ import UniRequest from 'uniapp-request-sdk';
 
 const request = new UniRequest({
   baseUrl: 'https://api.example.com',
-  uploadTimeout: 30000,  // 文件上传超时 30 秒
+  uploadTimeout: 30000, // 文件上传超时 30 秒
 });
 
 // 选择文件并上传
@@ -647,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);
@@ -713,7 +691,7 @@ import UniRequest from 'uniapp-request-sdk';
 
 const request = new UniRequest({
   baseUrl: 'https://api.example.com',
-  downloadTimeout: 30000,  // 文件下载超时 30 秒
+  downloadTimeout: 30000, // 文件下载超时 30 秒
 });
 
 // 简单下载
@@ -737,19 +715,14 @@ 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} 字节`);
+    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);
-      }
-    );
+      // 更新 UI 进度条
+      // updateProgressBar(downloadProgress);
+    });
 
     console.log('下载完成:', filePath);
   } catch (error) {
@@ -762,7 +735,7 @@ async function downloadFileToPath() {
   try {
     const filePath = await request.downloadFile(
       '/files/contract.pdf',
-      'user_documents/contract.pdf'  // 保存到应用沙箱
+      'user_documents/contract.pdf', // 保存到应用沙箱
     );
 
     console.log('文件已保存:', filePath);
@@ -783,7 +756,7 @@ async function downloadSecureFile() {
       },
       (progress) => {
         console.log(`下载进度: ${progress.progress}%`);
-      }
+      },
     );
 
     console.log('下载完成:', filePath);
@@ -817,7 +790,7 @@ export const FileService = {
         undefined,
         (progress) => {
           console.log(`上传进度: ${progress.progress}%`);
-        }
+        },
       );
       return result;
     } catch (error) {
@@ -835,7 +808,7 @@ export const FileService = {
         { 'X-Document-Id': documentId },
         (progress) => {
           console.log(`下载进度: ${progress.progress}%`);
-        }
+        },
       );
       return filePath;
     } catch (error) {
@@ -874,13 +847,10 @@ export default {
           count: 1,
         });
 
-        const result = await FileService.uploadDocument(
-          res.tempFilePaths[0],
-          {
-            description: '重要文档',
-            category: 'reports',
-          }
-        );
+        const result = await FileService.uploadDocument(res.tempFilePaths[0], {
+          description: '重要文档',
+          category: 'reports',
+        });
 
         uni.showToast({
           title: '上传成功',
@@ -973,6 +943,7 @@ const request = new UniRequest({
 ```
 
 其中：
+
 - `errno === 0` 表示请求成功
 - `errno !== 0` 表示业务错误，会触发 reject
 
@@ -980,13 +951,13 @@ const request = new UniRequest({
 
 ### 自动处理的错误
 
-| 错误类型 | 处理方式 |
-|---------|---------|
-| HTTP 403 | 自动获取新 token 并重试 |
+| 错误类型 | 处理方式                              |
+| -------- | ------------------------------------- |
+| HTTP 403 | 自动获取新 token 并重试               |
 | HTTP 401 | 触发 logout 事件，通知 APP 返回登录页 |
-| 网络错误 | 自动重试（最多 maxRetryCount 次） |
-| 超时错误 | 自动重试（最多 maxRetryCount 次） |
-| 业务错误 | 直接 reject，业务处理 |
+| 网络错误 | 自动重试（最多 maxRetryCount 次）     |
+| 超时错误 | 自动重试（最多 maxRetryCount 次）     |
+| 业务错误 | 直接 reject，业务处理                 |
 
 ### 全局错误处理
 
@@ -1044,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 | -    | 全局错误处理函数           |
 
 ## 请求头预处理器（新增功能）
 
@@ -1134,7 +1105,7 @@ const request = new UniRequest({
 ### 预处理器的执行时机
 
 - **执行点**：在设置 token 后、发送请求前
-- **执行频率**：每次请求都执行（包括重试）
+- **执行频率**：每次业务请求执行一次，自动重试时复用第一次处理后的 header；若中途刷新 token，则会基于新 token 重新执行一次
 - **异常处理**：如果预处理器异常，请求会直接 reject，不会发送
 
 ### 预处理器的签名
@@ -1215,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 平台）**
@@ -1231,13 +1202,13 @@ headerProcessor: async () => {
 ```typescript
 // ❌ 错误：H5 中不生效
 headerProcessor: async () => {
-  return { 'cookie': 'sessionid=xxx' };
-}
+  return { cookie: 'sessionid=xxx' };
+};
 
 // ✅ 正确：使用其他方式
 headerProcessor: async () => {
   return { 'X-Session-Id': 'xxx' };
-}
+};
 ```
 
 ## 企业级实战案例
@@ -1294,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,
 });
 ```
@@ -1324,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 }) =>
@@ -1336,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: {
@@ -1347,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: {
@@ -1365,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 }) =>
@@ -1397,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 }) =>
@@ -1544,6 +1508,7 @@ export default {
 项目使用两个不同的请求实例：
 
 - **requestInstance**: 用于常规业务请求
+
   - 超时时间：4 秒
   - 重试次数：2 次
   - 适合快速响应的 API
@@ -1556,6 +1521,7 @@ export default {
 ##### 统一错误处理
 
 所有错误都通过 `onErrorHandler` 函数处理：
+
 - 业务错误（errno = 2002）：显示错误信息，关闭小程序
 - 权限错误（statusCode = 403）：引导用户重新登录
 - 其他错误：显示通用错误信息
@@ -1563,6 +1529,7 @@ export default {
 ##### API 层封装
 
 将所有 API 调用封装在专门的服务文件中：
+
 - 统一的错误处理
 - 类型安全的请求和响应
 - 易于测试和维护
@@ -1578,8 +1545,6 @@ export default {
 ✅ **类型安全** - 充分利用 TypeScript 的泛型机制
 ✅ **易于扩展** - 新 API 添加无需修改现有代码
 
-
-
 ## 常见问题
 
 ### Q: 如何处理跨域问题？
@@ -1588,7 +1553,7 @@ A: 在 `baseUrl` 中包含代理路径，让后端或开发服务器代理请求
 
 ```typescript
 const request = new UniRequest({
-  baseUrl: 'https://localhost:8080/api/proxy/',  // 包含代理路径
+  baseUrl: 'https://localhost:8080/api/proxy/', // 包含代理路径
 });
 ```
 
@@ -1603,9 +1568,7 @@ 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: 如何下载多个文件？
@@ -1621,9 +1584,7 @@ for (const fileUrl of fileUrls) {
 }
 
 // 方式 2：并行下载（需谨慎，可能导致超时）
-const filePaths = await Promise.all(
-  fileUrls.map(fileUrl => request.downloadFile(fileUrl))
-);
+const filePaths = await Promise.all(fileUrls.map((fileUrl) => request.downloadFile(fileUrl)));
 ```
 
 ### Q: 下载的文件如何持久化？
@@ -1649,12 +1610,12 @@ A: 增加 `downloadTimeout` 的值：
 ```typescript
 const request = new UniRequest({
   baseUrl: 'https://api.example.com',
-  downloadTimeout: 60000,  // 60 秒，适合大文件
+  downloadTimeout: 60000, // 60 秒，适合大文件
 });
 
 // 或在运行时修改
 request.setParams({
-  downloadTimeout: 120000,  // 120 秒
+  downloadTimeout: 120000, // 120 秒
 });
 ```
 
@@ -1670,18 +1631,13 @@ A: 目前库返回的是 Promise，无法直接获取 DownloadTask 来调用 abo
 // 推荐：在进度回调中检查状态
 let shouldCancel = false;
 
-await request.downloadFile(
-  '/file.zip',
-  undefined,
-  undefined,
-  (progress) => {
-    if (shouldCancel) {
-      // 无法直接中止，但可以停止处理
-      return;
-    }
-    console.log(`下载进度: ${progress.progress}%`);
+await request.downloadFile('/file.zip', undefined, undefined, (progress) => {
+  if (shouldCancel) {
+    // 无法直接中止，但可以停止处理
+    return;
   }
-);
+  console.log(`下载进度: ${progress.progress}%`);
+});
 
 // 用户点击取消按钮时
 function cancelDownload() {
@@ -1723,19 +1679,20 @@ 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` 方法)
+
   - 支持下载文件到本地目录或临时目录
   - 支持实时下载进度监听
   - 支持自定义请求头
@@ -1743,12 +1700,14 @@ A: 是的，包括重试时都会执行。这是为了确保每次请求都获
   - 默认超时时间 30 秒（可配置）
 
 - 📝 **文档改进** 完整的 JSDoc 注释
+
   - 所有公开/私有方法添加详细 JSDoc
   - 所有参数和返回值有清晰说明
   - 关键方法包含使用示例
   - 100% 注释覆盖率
 
 - 📚 **README 更新**
+
   - 新增《文件下载》文档章节
   - 新增文件下载的详细使用示例（示例 4-2、4-3）
   - 更新目录索引

package/dist/index.esm.js

@@ -588,43 +588,49 @@ var UniRequest = /*#__PURE__*/function () {
         /** 添加日志上报的小程序username */
         'X-Request-Username': this.username
       });
+      var finalHeader;
       var requestedToken = false;
       var retryCount = 0;
       return new Promise(function (res, rej) {
         var retryFucntion = /*#__PURE__*/function () {
           var _ref = _asyncToGenerator( /*#__PURE__*/_regeneratorRuntime().mark(function _callee() {
-            var finalHeader, processedHeader;
+            var requestHeader, processedHeader;
             return _regeneratorRuntime().wrap(function _callee$(_context) {
               while (1) switch (_context.prev = _context.next) {
                 case 0:
+                  if (finalHeader) {
+                    _context.next = 17;
+                    break;
+                  }
+                  requestHeader = Object.assign({}, header);
                   /** 因为token需要动态获取，因此放入这里 */
-                  header[_this3.tokenHeader] = "".concat(_this3.tokenPrefix).concat(_this3.token);
+                  requestHeader[_this3.tokenHeader] = "".concat(_this3.tokenPrefix).concat(_this3.token);
                   /** 针对h5调试的时候，因为塞入cookie是不安全的，因此无需塞入cookie，使用登录页后，后端塞入的cookie */
                   // #ifdef H5
                   if (_this3.tokenHeader === 'cookie') {
-                    delete header[_this3.tokenHeader];
+                    delete requestHeader[_this3.tokenHeader];
                   }
                   // #endif
-                  /** 执行请求头预处理 */
-                  finalHeader = header;
+                  /** 单次请求生命周期内只执行一次请求头预处理，重试复用同一份结果 */
+                  finalHeader = requestHeader;
                   if (!_this3.headerProcessor) {
-                    _context.next = 15;
+                    _context.next = 17;
                     break;
                   }
-                  _context.prev = 4;
-                  _context.next = 7;
-                  return _this3.headerProcessor(header);
-                case 7:
+                  _context.prev = 6;
+                  _context.next = 9;
+                  return _this3.headerProcessor(requestHeader);
+                case 9:
                   processedHeader = _context.sent;
-                  finalHeader = Object.assign(Object.assign({}, header), processedHeader);
-                  _context.next = 15;
+                  finalHeader = Object.assign(Object.assign({}, requestHeader), processedHeader);
+                  _context.next = 17;
                   break;
-                case 11:
-                  _context.prev = 11;
-                  _context.t0 = _context["catch"](4);
+                case 13:
+                  _context.prev = 13;
+                  _context.t0 = _context["catch"](6);
                   _this3.rejectHandler(rej, _context.t0);
                   return _context.abrupt("return");
-                case 15:
+                case 17:
                   callbackPromise(Object.assign(Object.assign({}, params), {
                     header: finalHeader,
                     url: url,
@@ -657,6 +663,7 @@ var UniRequest = /*#__PURE__*/function () {
                       (_this3.getTokenFun ? _this3.getTokenFun() : getToken(_this3.tokenEventName)).then(function (token) {
                         _this3.token = token;
                         requestedToken = true;
+                        finalHeader = void 0;
                         /** 获取token应该立马请求,不需要延迟 */
                         retryFucntion();
                       })["catch"](function () {
@@ -690,11 +697,11 @@ var UniRequest = /*#__PURE__*/function () {
                       _this3.rejectHandler(rej, rejData);
                     }
                   });
-                case 16:
+                case 18:
                 case "end":
                   return _context.stop();
               }
-            }, _callee, null, [[4, 11]]);
+            }, _callee, null, [[6, 13]]);
           }));
           return function retryFucntion() {
             return _ref.apply(this, arguments);

package/dist/index.umd.js

@@ -594,43 +594,49 @@
           /** 添加日志上报的小程序username */
           'X-Request-Username': this.username
         });
+        var finalHeader;
         var requestedToken = false;
         var retryCount = 0;
         return new Promise(function (res, rej) {
           var retryFucntion = /*#__PURE__*/function () {
             var _ref = _asyncToGenerator( /*#__PURE__*/_regeneratorRuntime().mark(function _callee() {
-              var finalHeader, processedHeader;
+              var requestHeader, processedHeader;
               return _regeneratorRuntime().wrap(function _callee$(_context) {
                 while (1) switch (_context.prev = _context.next) {
                   case 0:
+                    if (finalHeader) {
+                      _context.next = 17;
+                      break;
+                    }
+                    requestHeader = Object.assign({}, header);
                     /** 因为token需要动态获取，因此放入这里 */
-                    header[_this3.tokenHeader] = "".concat(_this3.tokenPrefix).concat(_this3.token);
+                    requestHeader[_this3.tokenHeader] = "".concat(_this3.tokenPrefix).concat(_this3.token);
                     /** 针对h5调试的时候，因为塞入cookie是不安全的，因此无需塞入cookie，使用登录页后，后端塞入的cookie */
                     // #ifdef H5
                     if (_this3.tokenHeader === 'cookie') {
-                      delete header[_this3.tokenHeader];
+                      delete requestHeader[_this3.tokenHeader];
                     }
                     // #endif
-                    /** 执行请求头预处理 */
-                    finalHeader = header;
+                    /** 单次请求生命周期内只执行一次请求头预处理，重试复用同一份结果 */
+                    finalHeader = requestHeader;
                     if (!_this3.headerProcessor) {
-                      _context.next = 15;
+                      _context.next = 17;
                       break;
                     }
-                    _context.prev = 4;
-                    _context.next = 7;
-                    return _this3.headerProcessor(header);
-                  case 7:
+                    _context.prev = 6;
+                    _context.next = 9;
+                    return _this3.headerProcessor(requestHeader);
+                  case 9:
                     processedHeader = _context.sent;
-                    finalHeader = Object.assign(Object.assign({}, header), processedHeader);
-                    _context.next = 15;
+                    finalHeader = Object.assign(Object.assign({}, requestHeader), processedHeader);
+                    _context.next = 17;
                     break;
-                  case 11:
-                    _context.prev = 11;
-                    _context.t0 = _context["catch"](4);
+                  case 13:
+                    _context.prev = 13;
+                    _context.t0 = _context["catch"](6);
                     _this3.rejectHandler(rej, _context.t0);
                     return _context.abrupt("return");
-                  case 15:
+                  case 17:
                     callbackPromise(Object.assign(Object.assign({}, params), {
                       header: finalHeader,
                       url: url,
@@ -663,6 +669,7 @@
                         (_this3.getTokenFun ? _this3.getTokenFun() : getToken(_this3.tokenEventName)).then(function (token) {
                           _this3.token = token;
                           requestedToken = true;
+                          finalHeader = void 0;
                           /** 获取token应该立马请求,不需要延迟 */
                           retryFucntion();
                         })["catch"](function () {
@@ -696,11 +703,11 @@
                         _this3.rejectHandler(rej, rejData);
                       }
                     });
-                  case 16:
+                  case 18:
                   case "end":
                     return _context.stop();
                 }
-              }, _callee, null, [[4, 11]]);
+              }, _callee, null, [[6, 13]]);
             }));
             return function retryFucntion() {
               return _ref.apply(this, arguments);

package/package.json

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