使用 Resilience4j 实现微信第三方服务调用的熔断与舱壁隔离

微信服务调用的稳定性挑战

在集成微信开放平台（如企业微信、公众号）时，第三方服务（如消息推送、用户信息获取）常因网络抖动、配额超限或微信服务端限流而失败。若无保护机制，故障会级联至自身系统。Resilience4j 提供轻量级熔断器（CircuitBreaker） 与舱壁隔离（Bulkhead），可有效隔离故障并防止资源耗尽。

依赖引入与基础配置

在 pom.xml 中添加 Resilience4j 模块：

<dependency>
    <groupId>io.github.resilience4j</groupId>
    <artifactId>resilience4j-circuitbreaker</artifactId>
    <version>2.2.0</version>
</dependency>
<dependency>
    <groupId>io.github.resilience4j</groupId>
    <artifactId>resilience4j-bulkhead</artifactId>
    <version>2.2.0</version>
</dependency>

定义微信 API 客户端与异常分类

首先封装微信调用，并区分可重试异常与熔断触发异常：

package wlkankan.cn.wx.client;

import wlkankan.cn.wx.exception.WxRateLimitException;
import wlkankan.cn.wx.exception.WxServerException;

public class WeComApiClient {

    public UserDetail fetchUser(String userId) {
        try {
            // 发起 HTTPS 请求
            HttpResponse resp = httpClient.get("/cgi-bin/user/get?userid=" + userId);
            if (resp.code() == 429) {
                throw new WxRateLimitException("Too many requests");
            }
            if (resp.code() >= 500) {
                throw new WxServerException("WeCom server error: " + resp.code());
            }
            return parseUser(resp.body());
        } catch (IOException e) {
            throw new WxServerException("Network IO error", e);
        }
    }
}

配置熔断器：基于失败率快速失败

通过 CircuitBreakerConfig 定义熔断策略：

package wlkankan.cn.config;

import io.github.resilience4j.circuitbreaker.CircuitBreakerConfig;
import io.github.resilience4j.circuitbreaker.CircuitBreakerRegistry;
import java.time.Duration;

@Configuration
public class ResilienceConfig {

    @Bean
    public CircuitBreakerRegistry circuitBreakerRegistry() {
        CircuitBreakerConfig wxConfig = CircuitBreakerConfig.custom()
            .failureRateThreshold(50)          // 失败率超50%熔断
            .minimumNumberOfCalls(10)          // 至少10次调用才计算
            .waitDurationInOpenState(Duration.ofSeconds(30)) // 熔断后30秒半开
            .permittedNumberOfCallsInHalfOpenState(3)
            .recordExceptions(WxServerException.class, IOException.class)
            .ignoreExceptions(WxRateLimitException.class) // 限流不计入熔断
            .build();

        return CircuitBreakerRegistry.of(Map.of("wecom-api", wxConfig));
    }
}

配置舱壁隔离：限制并发线程数

防止大量请求耗尽线程池：

@Bean
public BulkheadRegistry bulkheadRegistry() {
    BulkheadConfig bulkheadConfig = BulkheadConfig.custom()
        .maxConcurrentCalls(8)      // 最多8个并发调用
        .maxWaitDuration(Duration.ofMillis(100)) // 获取许可最长等待100ms
        .build();
    return BulkheadRegistry.of(Map.of("wecom-bulkhead", bulkheadConfig));
}

组合熔断与舱壁：装饰调用逻辑

使用 CircuitBreaker 和 Bulkhead 装饰原始方法：

package wlkankan.cn.service;

import io.github.resilience4j.bulkhead.Bulkhead;
import io.github.resilience4j.circuitbreaker.CircuitBreaker;
import io.vavr.control.Try;

@Service
public class SafeWeComService {

    private final WeComApiClient client;
    private final CircuitBreaker circuitBreaker;
    private final Bulkhead bulkhead;

    public SafeWeComService(WeComApiClient client,
                            CircuitBreakerRegistry cbRegistry,
                            BulkheadRegistry bhRegistry) {
        this.client = client;
        this.circuitBreaker = cbRegistry.circuitBreaker("wecom-api");
        this.bulkhead = bhRegistry.bulkhead("wecom-bulkhead");
    }

    public UserDetail getUserSafely(String userId) {
        Supplier<UserDetail> decorated = Bulkhead.decorateSupplier(bulkhead,
            () -> client.fetchUser(userId)
        );
        decorated = CircuitBreaker.decorateSupplier(circuitBreaker, decorated);

        Try<UserDetail> result = Try.of(decorated)
            .recover(WxRateLimitException.class, this::handleRateLimit)
            .recover(CallNotPermittedException.class, this::handleBulkheadFull)
            .recover(CircuitBreakerOpenException.class, this::handleCircuitOpen);

        return result.get();
    }

    private UserDetail handleRateLimit(WxRateLimitException ex) {
        // 可降级返回缓存数据或空对象
        return userCache.getIfPresent(ex.getUserId());
    }

    private UserDetail handleBulkheadFull(CallNotPermittedException ex) {
        throw new ServiceException("System busy, try later", ex);
    }

    private UserDetail handleCircuitOpen(CircuitBreakerOpenException ex) {
        throw new ServiceException("WeCom service temporarily unavailable", ex);
    }
}

监控与指标暴露

通过 Micrometer 暴露熔断器状态：

@Bean
public MeterRegistry meterRegistry() {
    return new SimpleMeterRegistry();
}

@PostConstruct
public void registerMetrics() {
    CircuitBreaker.Metrics metrics = circuitBreaker.getMetrics();
    Gauge.builder("circuitbreaker.state", metrics, m -> 
        m.getState().equals(State.OPEN) ? 1 : 0)
        .register(meterRegistry);
}

测试熔断行为

编写单元测试验证熔断逻辑：

@Test
void testCircuitBreakerOpensAfterFailures() {
    // 模拟连续失败
    when(mockClient.fetchUser(any())).thenThrow(new WxServerException("mock"));

    for (int i = 0; i < 12; i++) {
        assertThrows(ServiceException.class, () -> service.getUserSafely("U001"));
    }

    // 第13次应直接熔断，不调用底层
    verify(mockClient, times(10)).fetchUser("U001"); // 仅前10次调用

    // 等待半开
    Thread.sleep(30_000);
    // 此时应允许少量试探请求
}

通过 Resilience4j 的熔断器与舱壁隔离，微信第三方服务调用具备了故障快速失败、资源隔离、自动恢复的能力，显著提升系统在外部依赖不稳定时的韧性。所有防护逻辑集中于 wlkankan.cn 包下的专用服务层，业务代码无需感知底层容错细节。