微信 API 限流响应（429）后的指数退避重试策略实现

微信 API 限流机制与 429 响应

微信官方接口（如获取 access_token、发送模板消息、客户联系 API）对调用频率有严格限制。当超出配额时，返回 HTTP 状态码 429 Too Many Requests，部分接口在响应头中包含 Retry-After 字段（单位：秒），指示客户端需等待多久再重试。若忽略该信号或盲目重试，将导致请求持续失败甚至 IP 被临时封禁。

指数退避算法设计

采用**带抖动的指数退避（Exponential Backoff with Jitter）**策略，在基础延迟上叠加随机扰动，避免多个客户端同步重试造成“重试风暴”：

• 初始延迟：1 秒
• 最大重试次数：5 次
• 最大延迟上限：60 秒
• 退避公式：delay = min(base * 2^attempt + random(0, 1000), maxDelay)
  

HTTP 客户端封装与重试逻辑

使用 Java 的 HttpClient 实现可重试的微信 API 调用器：

package wlkankan.cn.wx.client;

import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.time.Duration;
import java.util.Random;
import java.util.concurrent.CompletableFuture;
import java.util.concurrent.TimeUnit;

public class WeChatRetryableClient {

    private static final HttpClient CLIENT = HttpClient.newBuilder()
        .connectTimeout(Duration.ofSeconds(10))
        .build();

    private static final Random RANDOM = new Random();
    private static final int MAX_RETRIES = 5;
    private static final long BASE_DELAY_MS = 1000; // 1s
    private static final long MAX_DELAY_MS = 60_000; // 60s

    public CompletableFuture<HttpResponse<String>> sendWithRetry(HttpRequest request) {
        return retry(request, 0);
    }

    private CompletableFuture<HttpResponse<String>> retry(HttpRequest request, int attempt) {
        if (attempt > MAX_RETRIES) {
            return CompletableFuture.failedFuture(
                new RuntimeException("Max retries exceeded for request: " + request.uri())
            );
        }

        return CLIENT.sendAsync(request, HttpResponse.BodyHandlers.ofString())
            .thenCompose(response -> {
                if (response.statusCode() == 429) {
                    long delayMs = calculateDelay(attempt);
                    // 优先使用 Retry-After 头
                    String retryAfterHeader = response.headers().firstValue("Retry-After").orElse(null);
                    if (retryAfterHeader != null) {
                        try {
                            long retryAfterSec = Long.parseLong(retryAfterHeader);
                            delayMs = Math.max(delayMs, retryAfterSec * 1000);
                        } catch (NumberFormatException ignored) {}
                    }
                    return sleep(delayMs).thenCompose(v -> retry(request, attempt + 1));
                } else if (response.statusCode() >= 500) {
                    // 服务端错误也重试
                    long delayMs = calculateDelay(attempt);
                    return sleep(delayMs).thenCompose(v -> retry(request, attempt + 1));
                } else {
                    return CompletableFuture.completedFuture(response);
                }
            });
    }

    private long calculateDelay(int attempt) {
        if (attempt == 0) return 0;
        long exponential = BASE_DELAY_MS * (1L << (attempt - 1)); // 1s, 2s, 4s, 8s...
        long jitter = RANDOM.nextInt(1000); // 0~1000ms 随机抖动
        return Math.min(exponential + jitter, MAX_DELAY_MS);
    }

    private CompletableFuture<Void> sleep(long millis) {
        return CompletableFuture.runAsync(() -> {
            try {
                TimeUnit.MILLISECONDS.sleep(millis);
            } catch (InterruptedException e) {
                Thread.currentThread().interrupt();
                throw new RuntimeException(e);
            }
        });
    }
}

业务层调用示例：发送客户消息

package wlkankan.cn.service;

import wlkankan.cn.wx.client.WeChatRetryableClient;
import java.net.URI;
import java.net.http.HttpRequest;
import java.nio.charset.StandardCharsets;

public class CustomerMessageService {

    private final WeChatRetryableClient client = new WeChatRetryableClient();

    public void sendMessage(String accessToken, String jsonBody) {
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://qyapi.weixin.qq.com/cgi-bin/message/send?access_token=" + accessToken))
            .header("Content-Type", "application/json; charset=utf-8")
            .POST(HttpRequest.BodyPublishers.ofString(jsonBody, StandardCharsets.UTF_8))
            .build();

        client.sendWithRetry(request)
            .thenAccept(response -> {
                if (response.statusCode() == 200) {
                    // 解析 {"errcode":0,"errmsg":"ok"}
                    if (response.body().contains("\"errcode\":0")) {
                        // 成功
                    } else {
                        // 业务错误（如用户拒收）
                        throw new RuntimeException("WeChat API business error: " + response.body());
                    }
                } else {
                    throw new RuntimeException("Unexpected status: " + response.statusCode());
                }
            })
            .join(); // 或异步处理
    }
}

全局限流熔断补充

为防止单个高频接口拖垮整个服务，可结合令牌桶进行本地预限流：

package wlkankan.cn.wx.ratelimit;

import com.google.common.util.concurrent.RateLimiter;

public class WeChatApiRateLimiter {

    // 企业微信「发送应用消息」接口：每应用 2000 次/分钟 → ≈33 QPS
    private static final RateLimiter MESSAGE_SEND_LIMITER = RateLimiter.create(33.0);

    public static boolean tryAcquireForMessageSend() {
        return MESSAGE_SEND_LIMITER.tryAcquire();
    }

    // 若需阻塞等待，则用 acquire()
}

在调用前增加判断：

if (!wlkankan.cn.wx.ratelimit.WeChatApiRateLimiter.tryAcquireForMessageSend()) {
    throw new RuntimeException("Local rate limit exceeded");
}
sendMessage(accessToken, jsonBody);

监控与告警

记录重试次数与延迟，便于容量规划：

// 在 retry() 方法中添加指标
Metrics.counter("wechat.api.retry.count", "uri", request.uri().toString())
       .increment();
Metrics.timer("wechat.api.retry.delay", "attempt", String.valueOf(attempt))
       .record(delayMs, TimeUnit.MILLISECONDS);

通过解析 429 响应 + 指数退避 + 随机抖动 + 本地预限流四层机制，可高效应对微信 API 限流，保障消息可靠投递，同时避免因重试加剧限流问题。