Spring Boot 3.5 + Java 25 + Cloud Native 系列（三）：BFF 聚合层

public BuyerApi.DashboardResponse loadDashboard(String buyerId) {
    try (var executor = Executors.newVirtualThreadPerTaskExecutor()) {
        var profileFuture = executor.submit(() ->
                call("profileService", true,
                        () -> profileClient.getProfile(buyerId),
                        "Profile service unavailable"));
        var walletFuture = executor.submit(() ->
                call("walletService", true,
                        () -> walletClient.getAccount(buyerId),
                        "Wallet service unavailable"));
        var promotionsFuture = executor.submit(() ->
                call("promotionService", true,
                        () -> promotionClient.listOffers(),
                        "Promotions unavailable"));
        var marketplaceFuture = executor.submit(() ->
                call("marketplaceService", true,
                        () -> marketplaceClient.listProducts(),
                        "Marketplace unavailable"));
        var loyaltyFuture = executor.submit(() ->
                call("loyaltyService", true,
                        () -> loyaltyClient.getAccount(buyerId),
                        "Loyalty service unavailable"));

        return new BuyerApi.DashboardResponse(
                profileFuture.get(), walletFuture.get(), promotionsFuture.get(),
                marketplaceFuture.get(), loyaltyFuture.get());
    } catch (InterruptedException e) {
        Thread.currentThread().interrupt();
        throw new BusinessException(CommonErrorCode.INTERNAL_ERROR,
                "Buyer dashboard interrupted", e);
    } catch (ExecutionException e) {
        throw new BusinessException(CommonErrorCode.DOWNSTREAM_ERROR,
                "Buyer dashboard aggregation failed", e);
    }
}

private <T> T call(String instanceName, boolean retryEnabled,
                   Supplier<T> supplier, String unavailableMessage) {
    if (retryEnabled) {
        return resilienceHelper.read(instanceName, supplier,
                throwable -> failDownstream(unavailableMessage, throwable));
    }
    return resilienceHelper.write(instanceName, supplier,
            throwable -> failDownstream(unavailableMessage, throwable));
}

// 装饰器链顺序：Retry → CircuitBreaker → Bulkhead → TimeLimiter
Supplier<T> retryDecorated = retryEnabled ?
        Retry.decorateSupplier(retry, supplier) : supplier;
Supplier<T> circuitDecorated =
        CircuitBreaker.decorateSupplier(circuitBreaker, retryDecorated);
Supplier<T> bulkheadDecorated =
        Bulkhead.decorateSupplier(bulkhead, circuitDecorated);
return timeLimiter.executeFutureSupplier(
        () -> executorService.submit(bulkheadDecorated::get));

// 声明式客户端接口
@HttpExchange
public interface SearchServiceClient {
    @GetExchange("/api/search/products")
    SearchApi.SearchResponse searchProducts(@RequestParam("q") String query,
                                             @RequestParam("page") int page);
}

// 配置类中装配
@Bean
SearchServiceClient searchServiceClient(BuyerClientProperties properties,
                                        JdkClientHttpRequestFactory factory) {
    RestClient searchRestClient = RestClient.builder()
            .requestFactory(factory)
            .baseUrl(properties.searchServiceUrl())
            .build();
    HttpServiceProxyFactory httpFactory = HttpServiceProxyFactory
            .builderFor(RestClientAdapter.create(searchRestClient))
            .build();
    return httpFactory.createClient(SearchServiceClient.class);
}

// 迁移前：OpenFeign
@FeignClient(name = "user-service", url = "https://api.example.com/users")
public interface UserFeignClient {
    @GetMapping("/{id}")
    UserResponse getUserById(@PathVariable("id") Long id);

    @PostMapping
    UserResponse createUser(@RequestBody CreateUserRequest request);
}

// 迁移后：@HttpExchange
@HttpExchange("/users")
public interface UserHttpClient {
    @GetExchange("/{id}")
    UserResponse getUserById(@PathVariable("id") Long id);

    @PostExchange
    UserResponse createUser(@RequestBody CreateUserRequest request);
}

// buyer-bff: HTTP/1.1（默认）
HttpClient.newBuilder()
    .version(properties.httpVersion())  // HTTP_1_1
    .connectTimeout(properties.connectTimeout())
    .build();

// seller-bff: HTTP/2
HttpClient.newBuilder()
    .version(HttpClient.Version.HTTP_2)  // 强制 HTTP/2
    .connectTimeout(properties.connectTimeout())
    .build();

PromotionApi.CouponValidationResponse couponValidation = null;
if (request.couponCode() != null && !request.couponCode().isBlank()) {
    couponValidation = validateCouponForCheckout(request.couponCode(), cart.subtotal());
    // 如果 promotion-service 不可用，couponValidation 为 null
    // 结账继续进行，只是不使用优惠券折扣
}

public PromotionApi.CouponValidationResponse validateCouponForCheckoutFallback(
        String couponCode, BigDecimal orderAmount, Throwable throwable) {
    if (throwable instanceof BusinessException businessException
            && shouldPropagateCouponFailure(businessException)) {
        throw businessException;  // 业务错误（券无效/已过期）→ 硬失败
    }
    log.warn("promotion-service unavailable, skipping coupon {}: {}",
            couponCode, throwable.getMessage());
    return null;  // 系统错误 → 优雅降级：不使用优惠继续结账
}

public boolean deductLoyaltyPointsForCheckoutFallback(...) {
    if (throwable instanceof BusinessException businessException
            && shouldPropagateLoyaltyFailure(businessException)) {
        throw businessException;  // 余额不足 → 硬失败
    }
    log.warn("loyalty-service unavailable, skipping points deduction for buyer {}: {}",
            buyerId, throwable.getMessage());
    return false;  // 系统错误 → 不使用积分继续结账
}

public void deductInventoryForCheckoutFallback(...) {
    throw new BusinessException(CommonErrorCode.DOWNSTREAM_ERROR,
            "Marketplace inventory is temporarily unavailable", throwable);
}

public boolean isGuestBuyer(String buyerId) {
    return buyerId != null && buyerId.startsWith("guest-buyer-");
}

@Component
public class GuestCartStore {
    private static final String CART_KEY_PREFIX = "buyer:guest:cart:";
    private static final Duration DEFAULT_TTL = Duration.ofHours(48);

    private final RedissonClient redissonClient;

    public List<OrderApi.CartItemResponse> listCart(String buyerId) {
        RBucket<String> bucket = redissonClient.getBucket(CART_KEY_PREFIX + buyerId);
        String json = bucket.get();
        if (json == null) return List.of();
        return objectMapper.readValue(json, new TypeReference<>() {});
    }

    public void addToCart(String buyerId, OrderApi.CartItemRequest item) {
        List<OrderApi.CartItemResponse> items = listCart(buyerId);
        // 合并同类项逻辑
        redissonClient.getBucket(CART_KEY_PREFIX + buyerId)
                .set(objectMapper.writeValueAsString(items), DEFAULT_TTL.toMillis(), TimeUnit.MILLISECONDS);
    }
}

public OrderApi.CartView listCart(String buyerId) {
    if (guestCartStore.isGuestBuyer(buyerId)) {
        return guestCartStore.listCart(buyerId);  // 走 Redis
    }
    return call("orderService", false,
            () -> orderClient.listCart(buyerId),  // 走 order-service DB
            "Cart service unavailable");
}

// GuestBuyerController
@PostMapping("/checkout")
public ApiResponse<OrderApi.OrderResponse> guestCheckout(
        @Valid @RequestBody OrderApi.GuestCheckoutRequest request) {
    return ApiResponse.success(service.guestCheckout(request));
}

// 游客订单追踪：通过 order_token 而非 buyerId
@GetMapping("/order/track")
public ApiResponse<OrderApi.OrderResponse> trackOrder(
        @RequestParam String token) {
    return ApiResponse.success(service.trackOrder(token));
}

@PostMapping("/cart/merge")
public ApiResponse<OrderApi.CartView> mergeCart(
        @RequestHeader("X-Buyer-Id") String headerBuyerId,
        @RequestHeader("X-Roles") String headerRoles,
        @Valid @RequestBody BuyerApi.MergeGuestCartRequest request) {
    requireSignedInBuyer(headerRoles, "Buyer cart merge");
    return ApiResponse.success(service.mergeGuestCart(
            requireAuthenticatedBuyerId(headerBuyerId, "Buyer cart merge"),
            request.guestBuyerId()));
}

// shop-contracts-buyer 中的 DashboardResponse
public record DashboardResponse(
        ProfileApi.ProfileResponse profile,       // 来自 profile-service
        WalletApi.WalletAccountResponse wallet,   // 来自 wallet-service
        List<PromotionApi.OfferResponse> promotions, // 来自 promotion-service
        List<MarketplaceApi.ProductResponse> marketplace, // 来自 marketplace-service
        LoyaltyApi.AccountResponse loyalty) {}    // 来自 loyalty-service

List<SearchApi.ProductHit> hits = fallback.products().stream()
        .map(product -> new SearchApi.ProductHit(
                product.id().toString(), product.sellerId(), product.name(),
                product.description(), product.price(),
                product.inventory() == null ? 0 : product.inventory(),
                product.categoryId(), product.categoryName(),
                product.imageUrl(), product.status()))
        .toList();

@Test
void validateCouponFallback_rethrowsDomainCouponErrors() {
    // 业务错误（券无效）→ 在当前实现里继续抛出
    when(service.validateCoupon(...))
            .thenThrow(new BusinessException(CommonErrorCode.COUPON_INVALID, "..."));
    assertThrows(BusinessException.class, () -> ...);
}

@Test
void validateCouponFallback_skipsOnSystemFailures() {
    // 系统错误（服务不可用）→ 返回 null，继续结账
    when(service.validateCoupon(...))
            .thenThrow(new BusinessException(CommonErrorCode.DOWNSTREAM_ERROR, "..."));
    var result = service.validateCouponForCheckout(...);
    assertNull(result);
}

@Test
void guestBuyerCannotMergeCart() {
    mockMvc.perform(post("/buyer/v1/cart/merge")
                    .header("X-Roles", "ROLE_BUYER_GUEST"))
            .andExpect(status().isForbidden());
}

@Test
void checkoutRecordsDurationMetrics() {
    mockMvc.perform(post("/buyer/v1/checkout/create"))
            .andExpect(status().isOk());
    assertThat(registry.find("shop_order_checkout_duration_seconds")
            .timer()).isNotNull();
}