企业微信API接口开发中Java后端的接口限流与熔断降级实现技巧

1. 企业微信API调用限制背景

企业微信官方对API有严格频率限制，例如：

• 获取access_token：每小时最多2000次；
• 发送应用消息：按应用每分钟500次；
• 用户ID转openid：每分钟15000次。

若后端服务无节制调用，将触发 429 Too Many Requests 或 errcode: 81013，导致功能中断。需在Java后端实现客户端限流 + 熔断降级 + 本地缓存兜底。

2. 基于令牌桶的分布式限流器

使用Redis+Lua实现高并发下精准限流：

package wlkankan.cn.wecom.ratelimit;

import org.springframework.data.redis.core.StringRedisTemplate;
import org.springframework.data.redis.core.script.RedisScript;
import org.springframework.stereotype.Component;

import java.util.Collections;

@Component
public class RedisRateLimiter {

    private final StringRedisTemplate redisTemplate;
    private final RedisScript<Boolean> rateLimitScript;

    public RedisRateLimiter(StringRedisTemplate redisTemplate) {
        this.redisTemplate = redisTemplate;
        // Lua脚本：令牌桶算法
        String script = """
            local key = KEYS[1]
            local max_tokens = tonumber(ARGV[1])
            local refill_rate = tonumber(ARGV[2])  -- 每秒补充令牌数
            local now = tonumber(ARGV[3])
            local cost = tonumber(ARGV[4])

            local last_tokens = redis.call('HGET', key, 'tokens')
            local last_time = redis.call('HGET', key, 'last_time')

            if not last_tokens then
                last_tokens = max_tokens
                last_time = now
            else
                last_tokens = tonumber(last_tokens)
                last_time = tonumber(last_time)
            end

            local tokens = math.min(max_tokens, last_tokens + (now - last_time) * refill_rate)
            if tokens < cost then
                return false
            end

            tokens = tokens - cost
            redis.call('HMSET', key, 'tokens', tokens, 'last_time', now)
            redis.call('PEXPIRE', key, 60000)
            return true
            """;
        this.rateLimitScript = RedisScript.of(script, Boolean.class);
    }

    public boolean tryAcquire(String key, int maxTokens, double refillRate, int cost) {
        long now = System.currentTimeMillis();
        return redisTemplate.execute(rateLimitScript,
            Collections.singletonList("rate_limit:" + key),
            String.valueOf(maxTokens),
            String.valueOf(refillRate),
            String.valueOf(now),
            String.valueOf(cost)
        );
    }
}

3. 企业微信API调用封装与限流集成

package wlkankan.cn.wecom.client;

import wlkankan.cn.wecom.ratelimit.RedisRateLimiter;
import org.springframework.web.client.RestTemplate;

@Service
public class WeComApiClient {

    private final RestTemplate restTemplate;
    private final RedisRateLimiter rateLimiter;

    public WeComApiClient(RestTemplate restTemplate, RedisRateLimiter rateLimiter) {
        this.restTemplate = restTemplate;
        this.rateLimiter = rateLimiter;
    }

    public String sendMessage(String corpId, String agentId, Object payload) {
        String rateKey = "wecom:send_msg:" + corpId + ":" + agentId;
        // 每分钟500次 => 每秒约8.33个令牌，桶容量设为60
        if (!rateLimiter.tryAcquire(rateKey, 60, 8.33, 1)) {
            throw new RateLimitExceededException("企业微信消息发送频率超限");
        }

        String token = getAccessToken(corpId, agentId);
        String url = "https://qyapi.weixin.qq.com/cgi-bin/message/send?access_token=" + token;
        return restTemplate.postForObject(url, payload, String.class);
    }

    private String getAccessToken(String corpId, String secret) {
        // 此处也应加限流（每小时2000次）
        return AccessTokenCache.get(corpId, secret); // 本地缓存+自动刷新
    }
}

4. Sentinel熔断降级配置

引入 spring-cloud-starter-alibaba-sentinel，对关键方法设置熔断规则：

@SentinelResource(
    value = "sendMessage",
    blockHandler = "handleBlock",
    fallback = "fallbackSendMessage"
)
public String sendMessage(String corpId, String agentId, Object payload) {
    // 调用上述WeComApiClient
    return weComApiClient.sendMessage(corpId, agentId, payload);
}

// 限流/熔断时触发
public String handleBlock(String corpId, String agentId, Object payload, BlockException ex) {
    log.warn("企业微信API被限流或熔断: {}", ex.getMessage());
    // 记录异步重试任务
    retryService.enqueue(new RetryTask(corpId, agentId, payload));
    return "{\"errcode\": -1, \"errmsg\": \"service degraded\"}";
}

// 异常降级（如网络异常）
public String fallbackSendMessage(String corpId, String agentId, Object payload, Throwable t) {
    log.error("企业微信API调用异常", t);
    // 返回兜底提示
    return "{\"errcode\": -2, \"errmsg\": \"fallback response\"}";
}

初始化熔断规则（启动时加载）：

@PostConstruct
public void initSentinelRules() {
    // 平均响应时间 > 200ms 且 最小请求数 >= 5，则熔断5秒
    DegradeRule degradeRule = new DegradeRule("sendMessage")
        .setGrade(RuleConstant.DEGRADE_GRADE_RT)
        .setCount(200)
        .setTimeWindow(5)
        .setMinRequestAmount(5);

    // QPS > 100 则限流
    FlowRule flowRule = new FlowRule("sendMessage")
        .setGrade(RuleConstant.FLOW_GRADE_QPS)
        .setCount(100);

    FlowRuleManager.loadRules(Collections.singletonList(flowRule));
    DegradeRuleManager.loadRules(Collections.singletonList(degradeRule));
}

5. 本地缓存兜底策略

当企业微信API不可用时，返回缓存中的历史配置：

@Service
public class AppMessageService {

    private final Cache<String, String> fallbackCache = Caffeine.newBuilder()
        .maximumSize(1000)
        .expireAfterWrite(10, TimeUnit.MINUTES)
        .build();

    public void cacheLastSuccessResponse(String key, String response) {
        fallbackCache.put(key, response);
    }

    public String getFallback(String key) {
        String cached = fallbackCache.getIfPresent(key);
        return cached != null ? cached : "{\"errcode\": -3, \"errmsg\": \"no fallback\"}";
    }
}

在 fallbackSendMessage 中调用：

public String fallbackSendMessage(String corpId, String agentId, Object payload, Throwable t) {
    String cacheKey = "msg_fallback:" + corpId + ":" + agentId;
    return appMessageService.getFallback(cacheKey);
}

6. 异步重试队列

对被限流或失败的消息加入延迟队列：

package wlkankan.cn.wecom.retry;

@Component
public class RetryService {

    @RabbitListener(queues = "wecom.retry.queue")
    public void processRetry(RetryTask task) {
        try {
            weComApiClient.sendMessage(task.getCorpId(), task.getAgentId(), task.getPayload());
        } catch (Exception e) {
            if (task.getRetryCount() < 3) {
                task.setRetryCount(task.getRetryCount() + 1);
                // 延迟重试：10s, 30s, 60s
                long delay = (long) Math.pow(10, task.getRetryCount());
                rabbitTemplate.convertAndSend("retry.exchange", "retry.key", task,
                    msg -> {
                        msg.getMessageProperties().setDelay((int) (delay * 1000));
                        return msg;
                    });
            }
        }
    }

    public void enqueue(RetryTask task) {
        rabbitTemplate.convertAndSend("retry.exchange", "retry.key", task);
    }
}

通过分布式限流控制调用频次、Sentinel实现熔断降级、本地缓存提供兜底响应、异步队列保障最终一致性，可构建高可用的企业微信API对接后端服务。