更新记录

1.0.0（2026-07-19）

新增

• 自动重试能力：请求失败时根据配置自动重试
• 指数退避策略：支持固定延迟和指数退避两种重试间隔
• 灵活重试条件：通过 shouldRetry 自定义重试条件，支持基于 error 和 options 灵活判断
• 全方法支持：request / get / post / upload / download 全部支持重试
• 可配置参数：支持自定义最大重试次数、基础延迟时间

平台兼容性

uni-app(3.8.0)

uni-app x(3.8.0)

mh-request-retry

请求重试插件，网络请求失败时自动重试，支持指数退避、自定义重试条件，灵活控制。

本插件是 mh-request 的配套插件，需配合使用。

特性

• 🔄 自动重试：请求失败时根据配置自动重试，无需额外编码
• 📈 指数退避：支持固定延迟和指数退避两种策略，避免瞬时高并发冲击服务端
• 🎯 灵活控制：通过 shouldRetry 函数传入 options，可根据 URL、Method 等任意条件决定是否重试
• 📦 全方法支持：request / get / post / upload / download 全部支持重试

快速开始

import { Request } from '@/uni_modules/mh-request'
import { retryPlugin } from '@/uni_modules/mh-request-retry'

const request = new Request({
  baseURL: 'https://api.example.com',
  plugins: [
    {
      plugin: retryPlugin,
      config: {
        maxRetries: 3,
        retryDelay: 1000,
        backoff: true
      }
    }
  ]
})

// 请求失败时会自动重试
const data = await request.get('/user/info')

配置项

默认重试条件

(error) => {
  if (error?.errMsg?.includes('timeout')) return true  // 超时
  if (error?.statusCode && error.statusCode >= 500) return true  // 5xx 服务端错误
  return false
}

工作原理

重试流程

发起请求 → 请求失败 → 判断是否满足重试条件
                         ↓
                    满足 → 延迟后重试（重复直到成功或达到最大次数）
                         ↓
                    不满足 → 直接抛出错误

指数退避示例

maxRetries: 3, retryDelay: 1000, backoff: true

高级用法

排除特定 URL 不重试

const request = new Request({
  plugins: [{
    plugin: retryPlugin,
    config: {
      shouldRetry: (error, options) => {
        // 不重试 /no-retry 路径的请求
        if (options.url?.includes('/no-retry')) return false
        // 只对超时和 5xx 重试
        if (error?.errMsg?.includes('timeout')) return true
        if (error?.statusCode >= 500) return true
        return false
      }
    }
  }]
})

仅对特定请求方法启用重试

const request = new Request({
  plugins: [{
    plugin: retryPlugin,
    config: {
      shouldRetry: (error, options) => {
        // 只对 GET 请求重试
        if (options.method !== 'GET') return false
        if (error?.errMsg?.includes('timeout')) return true
        if (error?.statusCode >= 500) return true
        return false
      }
    }
  }]
})

对业务错误码重试

const request = new Request({
  plugins: [{
    plugin: retryPlugin,
    config: {
      shouldRetry: (error, options) => {
        // 业务错误码 10001 触发重试
        if (error?.code === 10001) return true
        // HTTP 429 限流重试
        if (error?.statusCode === 429) return true
        if (error?.errMsg?.includes('timeout')) return true
        if (error?.statusCode >= 500) return true
        return false
      }
    }
  }]
})

调整重试间隔

// 固定间隔 3 秒
const request = new Request({
  plugins: [{
    plugin: retryPlugin,
    config: {
      maxRetries: 5,
      retryDelay: 3000,
      backoff: false  // 禁用指数退避，固定间隔
    }
  }]
})

// 短间隔 + 指数退避（适合快速恢复场景）
const request = new Request({
  plugins: [{
    plugin: retryPlugin,
    config: {
      maxRetries: 3,
      retryDelay: 500,
      backoff: true   // 500ms → 1000ms → 2000ms
    }
  }]
})

注意事项

重试条件区分网络错误和业务错误

error 对象来源：

• 网络错误（超时、断网等）：来自 uni.request 的 fail 回调，通常包含 errMsg 字段
• 业务错误（code 非成功码）：来自 mh-request 的 reject，包含 code、msg 等业务字段

shouldRetry 函数同时支持两种错误类型，可根据实际情况灵活判断。

避免重试幂等性问题

对于非幂等请求（如支付、下单），建议通过 shouldRetry 排除：

shouldRetry: (error, options) => {
  // POST /order 不重试，避免重复下单
  if (options.url === '/order' && options.method === 'POST') return false
  // 其他请求正常判断
  if (error?.errMsg?.includes('timeout')) return true
  if (error?.statusCode >= 500) return true
  return false
}

重试次数不宜过大

建议 maxRetries 控制在 3~5 次，避免长时间阻塞用户操作。