服务端上报相关参数详解

1. 概述

SnailJob 支持本地重试与服务端重试的灵活切换，服务端上报相关参数用于控制客户端与服务端之间的重试数据交互方式，包括重试策略、异步/同步上报、超时时间等。合理配置这些参数，可以满足不同业务场景下的高可用与高性能需求。

2. 参数说明

参数	描述	默认值	必须指定
retryStrategy	重试策略	LOCAL_REMOTE	✅
async	是否异步上报数据到服务端	true	❌
timeout	同步(async:false)上报数据需要配置超时时间	60 * 1000	❌
unit	超时时间单位	TimeUnit.MILLISECONDS	❌

2.1 retryStrategy（重试策略）

• 作用：指定重试的执行模式。
• 可选值：
  • ONLY_LOCAL：仅本地重试，异常不会上报服务端。
  • ONLY_REMOTE：仅远程重试，异常直接上报服务端，由服务端调度重试。
  • LOCAL_REMOTE：先本地重试，失败后再上报服务端。
• 说明：三种模式的区别如下：

策略	释义
ONLY_LOCAL	在内存中执行重试，重试结束后依然异常则抛出异常或打印错误日志
ONLY_REMOTE	将异常上报至服务端，由服务端管理重试动作
LOCAL_REMOTE	优先本地重试，失败后上报服务端，由服务端继续处理

2.2 async（是否异步上报）

• 作用：控制数据上报服务端时的同步/异步方式。
• 默认值：true（异步）
• 说明：
  • async=true：通过滑动窗口异步上传，提升吞吐量。
  • async=false：实时通过NettyClient同步上报，适合对一致性要求高的场景。

2.3 timeout/unit（超时时间及单位）

• timeout：同步上报时的超时时间，单位由unit指定。
• unit：超时时间单位，默认毫秒（TimeUnit.MILLISECONDS）。
• 说明：仅在async=false时生效。

3. 配置与代码示例

3.1 参数配置示例

  retryStrategy: LOCAL_REMOTE
  async: true
  timeout: 60000
  unit: TimeUnit.MILLISECONDS

3.2 代码与场景演示

3.2.1 基本远程重试案例

@Component
public class RemoteRetryService {
    @Retryable(scene = "remoteRetry", retryStrategy = RetryType.ONLY_REMOTE)
    public void remoteRetry() {
        System.out.println("远程重试方法启动");
        double i = 1 / 0;
    }
}

@RestController
@RequestMapping("/remote")
public class RemoteRetryController {
    @Autowired
    private RemoteRetryService remoteRetryService;

    @GetMapping("/retry")
    public void remote() {
        remoteRetryService.remoteRetry();
    }
}

• 启动客户端服务，通过HTTP请求触发远程重试，任务会被上报到服务端并由服务端调度。
• 可在管理后台查看任务执行与重试详情。

3.2.2 retryStrategy/async/timeout/unit 综合案例

/**
 * 使用先本地再远程的策略同步上传重试请求
 * retryStrategy = LOCAL_REMOTE 代表本地重试3次后再执行远程上报
 * async = false 代表使用同步上传的方式
 * timeout = 1 代表超时时间为1
 * unit = MINUTES 代表超时时间的单位是分钟
 */
@Retryable(scene = "remoteRetryWithSync", retryStrategy = RetryType.LOCAL_REMOTE,
        async = false, timeout = 1, unit = TimeUnit.MINUTES)
public String remoteRetryWithLocalRemote(String requestId) {
    double i = 1 / 0;
    return requestId;
}

• 先本地重试3次，失败后同步上报服务端，超时时间1分钟。

4. 最佳实践

• 业务对一致性要求高时建议使用同步上报（async=false），但需合理设置timeout避免阻塞。
• 大批量高并发场景建议使用异步上报（async=true），提升吞吐量。
• retryStrategy建议根据业务容错需求灵活选择，常用为LOCAL_REMOTE。
• 配置合理的超时时间和单位，避免因网络抖动导致重试数据丢失。
• 结合管理后台监控重试任务状态，及时处理死信队列中的异常任务。