淘宝指定店铺商品销量与价格数据监控实战指南

import com.taobao.api.ApiException;import com.taobao.api.DefaultTaobaoClient;import com.taobao.api.TaobaoClient;import com.taobao.api.request.ItemsOnsaleGetRequest;import com.taobao.api.request.ItemGetRequest;import com.taobao.api.response.ItemsOnsaleGetResponse;import com.taobao.api.response.ItemGetResponse;import com.taobao.api.domain.Item;import java.util.List;import java.util.stream.Collectors;/**
 * 淘宝官方 API 店铺商品监控客户端
 * 适用于监控自有店铺数据
 */public class TaobaoOfficialMonitor {

    // 生产环境网关地址
    private static final String SERVER_URL = "https://gw.api.taobao.com/router/rest";
    private final String appKey;
    private final String appSecret;
    private final TaobaoClient client;

    public TaobaoOfficialMonitor(String appKey, String appSecret) {
        this.appKey = appKey;
        this.appSecret = appSecret;
        this.client = new DefaultTaobaoClient(SERVER_URL, appKey, appSecret);
    }

    /**
     * 获取店铺出售中商品列表
     * 
     * @param sessionKey 店铺授权令牌
     * @param pageNo 页码
     * @param pageSize 每页数量（最大 200）
     * @return 商品列表
     */
    public List<Item> getOnsaleItems(String sessionKey, int pageNo, int pageSize) 
            throws ApiException {
        
        ItemsOnsaleGetRequest req = new ItemsOnsaleGetRequest();
        req.setFields("num_iid,title,price,pic_url,num,list_time,delist_time,has_discount");
        req.setPageNo((long) pageNo);
        req.setPageSize((long) pageSize);
        // 可选：按类目过滤 req.setCid(50000671L);

        ItemsOnsaleGetResponse rsp = client.execute(req, sessionKey);
        
        if (!rsp.isSuccess()) {
            throw new ApiException(rsp.getSubCode(), rsp.getSubMsg());
        }
        
        return rsp.getItems();
    }

    /**
     * 获取单个商品详细信息（含销量、SKU价格等）
     * 
     * @param sessionKey 店铺授权令牌
     * @param numIid 商品数字ID
     * @return 商品详情
     */
    public Item getItemDetail(String sessionKey, long numIid) throws ApiException {
        ItemGetRequest req = new ItemGetRequest();
        // 关键字段：price(售价), num(库存), sold_quantity(销量), 
        // sku(规格价格), item_imgs(图片), desc(描述)
        req.setFields("num_iid,title,price,num,sold_quantity,sku,item_imgs," +
                      "list_time,delist_time,stuff_status,has_discount," +
                      "postage_id,express_fee,ems_fee");
        req.setNumIid(numIid);

        ItemGetResponse rsp = client.execute(req, sessionKey);
        
        if (!rsp.isSuccess()) {
            throw new ApiException(rsp.getSubCode(), rsp.getSubMsg());
        }
        
        return rsp.getItem();
    }

    /**
     * 全量扫描店铺商品并提取监控数据
     */
    public List<ProductSnapshot> scanStoreProducts(String sessionKey) {
        List<ProductSnapshot> snapshots = new ArrayList<>();
        int page = 1;
        int pageSize = 100;
        boolean hasMore = true;

        while (hasMore) {
            try {
                List<Item> items = getOnsaleItems(sessionKey, page, pageSize);
                
                for (Item item : items) {
                    // 获取详细数据
                    Item detail = getItemDetail(sessionKey, item.getNumIid());
                    
                    ProductSnapshot snapshot = new ProductSnapshot();
                    snapshot.setItemId(detail.getNumIid());
                    snapshot.setTitle(detail.getTitle());
                    snapshot.setPrice(Double.parseDouble(detail.getPrice()));
                    snapshot.setStock(detail.getNum());
                    snapshot.setSoldQuantity(detail.getSoldQuantity());
                    snapshot.setListTime(detail.getListTime());
                    snapshot.setHasDiscount(detail.getHasDiscount());
                    
                    // 解析 SKU 级别价格
                    if (detail.getSkus() != null) {
                        List<<SkuInfo> skus = detail.getSkus().stream()
                            .map(sku -> new SkuInfo(
                                sku.getSkuId(),
                                sku.getPropertiesName(),
                                Double.parseDouble(sku.getPrice()),
                                sku.getQuantity()
                            ))
                            .collect(Collectors.toList());
                        snapshot.setSkus(skus);
                    }
                    
                    snapshots.add(snapshot);
                }

                hasMore = items.size() == pageSize;
                page++;
                
                // 官方限流：建议间隔 100ms 以上
                Thread.sleep(100);
                
            } catch (ApiException e) {
                if ("isv.item-get-service-error".equals(e.getSubCode())) {
                    System.err.println("商品已下架或无权访问: " + e.getSubCode());
                    continue;
                }
                handleApiError(e);
                break;
            } catch (InterruptedException e) {
                Thread.currentThread().interrupt();
                break;
            }
        }
        
        return snapshots;
    }

    private void handleApiError(ApiException e) {
        String subCode = e.getSubCode();
        if (subCode != null && subCode.contains("limit")) {
            System.err.println("触发限流，请降低请求频率");
        } else if (subCode != null && subCode.contains("session")) {
            System.err.println("授权失效，请重新获取 SessionKey");
        } else {
            System.err.println("API 错误: " + e.getMessage());
        }
    }

    // ==================== 数据模型 ====================

    @Data
    public static class ProductSnapshot {
        private long itemId;
        private String title;
        private double price;           // 当前售价
        private long stock;             // 库存
        private long soldQuantity;      // 累计销量
        private String listTime;        // 上架时间
        private boolean hasDiscount;    // 是否有优惠
        private List<<SkuInfo> skus;     // SKU 规格信息
        private LocalDateTime captureTime = LocalDateTime.now();
    }

    @Data
    @AllArgsConstructor
    public static class SkuInfo {
        private long skuId;
        private String properties;      // 规格属性（如"颜色:红色;尺码:M"）
        private double price;           // SKU 价格
        private long quantity;          // SKU 库存
    }}

import org.springframework.scheduling.annotation.Scheduled;import org.springframework.stereotype.Component;import java.util.Map;import java.util.concurrent.ConcurrentHashMap;@Componentpublic class StoreMonitorScheduler {

    private final TaobaoOfficialMonitor monitor;
    private final ProductDataRepository repository;
    private final AlertService alertService;
    
    // 缓存上一次数据，用于比对变化
    private final Map<Long, ProductSnapshot> lastSnapshot = new ConcurrentHashMap<>();

    public StoreMonitorScheduler(TaobaoOfficialMonitor monitor, 
                                  ProductDataRepository repository,
                                  AlertService alertService) {
        this.monitor = monitor;
        this.repository = repository;
        this.alertService = alertService;
    }

    /**
     * 每 30 分钟监控一次价格变动
     */
    @Scheduled(fixedRate = 30 * 60 * 1000)
    public void monitorPriceChanges() {
        String sessionKey = getValidSessionKey();
        List<ProductSnapshot> current = monitor.scanStoreProducts(sessionKey);
        
        for (ProductSnapshot product : current) {
            ProductSnapshot previous = lastSnapshot.get(product.getItemId());
            
            if (previous != null) {
                // 检测价格变动
                if (Math.abs(product.getPrice() - previous.getPrice()) > 0.01) {
                    PriceChangeEvent event = new PriceChangeEvent(
                        product.getItemId(),
                        product.getTitle(),
                        previous.getPrice(),
                        product.getPrice(),
                        product.getCaptureTime()
                    );
                    alertService.sendPriceAlert(event);
                }
                
                // 检测库存变化（补货/缺货）
                if (previous.getStock() == 0 && product.getStock() > 0) {
                    alertService.sendRestockAlert(product.getItemId(), product.getTitle());
                }
                if (previous.getStock() > 0 && product.getStock() == 0) {
                    alertService.sendOutOfStockAlert(product.getItemId(), product.getTitle());
                }
            }
            
            // 更新缓存并持久化
            lastSnapshot.put(product.getItemId(), product);
            repository.save(product);
        }
    }

    /**
     * 每 6 小时深度扫描销量数据
     */
    @Scheduled(cron = "0 0 */6 * * ?")
    public void monitorSalesTrend() {
        // 计算销量增长率、识别爆款等
    }

    private String getValidSessionKey() {
        // 从数据库或缓存获取有效令牌，过期则刷新
        return "your_session_key";
    }}

import com.taobao.api.TaobaoClient;import com.taobao.api.DefaultTaobaoClient;import com.taobao.api.request.TbkItemInfoGetRequest;import com.taobao.api.request.TbkItemGetRequest;import com.taobao.api.response.TbkItemInfoGetResponse;import com.taobao.api.response.TbkItemGetResponse;/**
 * 淘宝联盟商品监控（适合公开商品/竞品监控）
 */public class TaobaoUnionMonitor {

    private static final String SERVER_URL = "https://gw.api.taobao.com/router/rest";
    private final String appKey;
    private final String appSecret;
    private final TaobaoClient client;

    public TaobaoUnionMonitor(String appKey, String appSecret) {
        this.appKey = appKey;
        this.appSecret = appSecret;
        this.client = new DefaultTaobaoClient(SERVER_URL, appKey, appSecret);
    }

    /**
     * 通过商品 ID 获取详细信息（含销量、价格、佣金）
     */
    public TbkItemInfoGetResponse.NTbkItem getItemInfo(long numIid) throws Exception {
        TbkItemInfoGetRequest req = new TbkItemInfoGetRequest();
        req.setNumIids(String.valueOf(numIid));
        // 返回字段：title(标题), pict_url(图片), small_images(小图),
        // reserve_price(原价), zk_final_price(折扣价), user_type(1天猫/0淘宝),
        // volume(30天销量), provcity(地区), item_url(链接),
        // coupon_info(优惠券), commission_rate(佣金比例)
        req.setFields("title,pict_url,reserve_price,zk_final_price,user_type," +
                      "volume,provcity,item_url,coupon_info,commission_rate," +
                      "seller_id,category,level_1_category_name");

        TbkItemInfoGetResponse rsp = client.execute(req);
        
        if (rsp.isSuccess() && rsp.getResults() != null && !rsp.getResults().isEmpty()) {
            return rsp.getResults().get(0);
        }
        return null;
    }

    /**
     * 搜索指定店铺的商品（通过卖家昵称过滤）
     */
    public List<TbkItemGetResponse.NTbkItem> searchStoreItems(String keyword, 
                                                               String sellerNick,
                                                               int pageSize) throws Exception {
        TbkItemGetRequest req = new TbkItemGetRequest();
        req.setQ(keyword);                    // 搜索关键词
        req.setPageSize((long) pageSize);
        req.setPageNo(1L);
        req.setSort("total_sales_des");       // 按销量降序
        req.setFields("num_iid,title,pict_url,reserve_price,zk_final_price," +
                      "user_type,volume,nick,item_url,seller_id");
        
        TbkItemGetResponse rsp = client.execute(req);
        
        if (rsp.isSuccess() && rsp.getResults() != null) {
            // 过滤指定卖家
            return rsp.getResults().stream()
                .filter(item -> sellerNick.equals(item.getNick()))
                .collect(Collectors.toList());
        }
        return Collections.emptyList();
    }}

import com.google.gson.Gson;import com.google.gson.annotations.SerializedName;import lombok.Data;import okhttp3.HttpUrl;import okhttp3.OkHttpClient;import okhttp3.Request;import okhttp3.Response;import java.io.IOException;import java.time.LocalDateTime;import java.util.List;import java.util.concurrent.TimeUnit;/**
 * 通用商品监控客户端（适配第三方数据服务）
 * 支持：JustOneAPI、万邦、其他 HTTP API
 */public class ProductMonitorClient {

    private final OkHttpClient httpClient;
    private final Gson gson;
    private final String baseUrl;
    private final String apiKey;

    public ProductMonitorClient(String baseUrl, String apiKey) {
        this.baseUrl = baseUrl;
        this.apiKey = apiKey;
        this.httpClient = new OkHttpClient.Builder()
                .connectTimeout(15, TimeUnit.SECONDS)
                .readTimeout(30, TimeUnit.SECONDS)
                .build();
        this.gson = new Gson();
    }

    /**
     * 获取单个商品详情（含实时销量、价格）
     */
    public ProductDetail getItemDetail(long itemId) throws IOException {
        HttpUrl url = HttpUrl.parse(baseUrl + "/api/item/detail").newBuilder()
                .addQueryParameter("token", apiKey)
                .addQueryParameter("itemId", String.valueOf(itemId))
                .build();

        Request request = new Request.Builder().url(url).get().build();
        
        try (Response response = httpClient.newCall(request).execute()) {
            if (!response.isSuccessful()) {
                throw new IOException("HTTP " + response.code());
            }
            String json = response.body().string();
            ApiResponse<ProductDetail> apiResp = gson.fromJson(json, 
                new TypeToken<<ApiResponse<ProductDetail>>(){}.getType());
            return apiResp.getData();
        }
    }

    /**
     * 搜索指定店铺的商品列表
     */
    public List<ProductBrief> searchStoreItems(String sellerNick, int page) throws IOException {
        HttpUrl url = HttpUrl.parse(baseUrl + "/api/item/search").newBuilder()
                .addQueryParameter("token", apiKey)
                .addQueryParameter("sellerNick", sellerNick)
                .addQueryParameter("page", String.valueOf(page))
                .addQueryParameter("sort", "sales")  // 按销量排序
                .build();

        Request request = new Request.Builder().url(url).get().build();
        
        try (Response response = httpClient.newCall(request).execute()) {
            String json = response.body().string();
            ApiResponse<List<ProductBrief>> apiResp = gson.fromJson(json,
                new TypeToken<<ApiResponse<List<ProductBrief>>>(){}.getType());
            return apiResp.getData();
        }
    }

    // ==================== 数据模型 ====================

    @Data
    public static class ProductDetail {
        @SerializedName("item_id")
        private long itemId;
        
        private String title;
        
        @SerializedName("original_price")
        private double originalPrice;      // 划线价/原价
        
        @SerializedName("promotion_price")
        private double promotionPrice;     // 促销价
        
        @SerializedName("final_price")
        private double finalPrice;         // 最终到手价（含券）
        
        @SerializedName("month_sales")
        private int monthSales;            // 月销量
        
        @SerializedName("total_sales")
        private int totalSales;            // 总销量
        
        @SerializedName("stock")
        private int stock;                 // 库存
        
        @SerializedName("seller_nick")
        private String sellerNick;
        
        @SerializedName("is_tmall")
        private boolean isTmall;
        
        @SerializedName("coupon_info")
        private String couponInfo;         // 优惠券信息
        
        @SerializedName("promotions")
        private List<<Promotion> promotions; // 活动列表
        
        @SerializedName("skus")
        private List<<SkuDetail> skus;      // SKU 详情
        
        @SerializedName("update_time")
        private LocalDateTime updateTime;
    }

    @Data
    public static class Promotion {
        private String type;               // 满减/折扣/秒杀
        private String description;
        @SerializedName("start_time")
        private LocalDateTime startTime;
        @SerializedName("end_time")
        private LocalDateTime endTime;
    }

    @Data
    public static class SkuDetail {
        @SerializedName("sku_id")
        private long skuId;
        private String properties;          // 颜色:红色;尺码:M
        private double price;
        private int stock;
        @SerializedName("sales")
        private int skuSales;
    }

    @Data
    public static class ProductBrief {
        @SerializedName("item_id")
        private long itemId;
        private String title;
        private double price;
        @SerializedName("month_sales")
        private int monthSales;
        @SerializedName("pic_url")
        private String picUrl;
    }

    @Data
    public static class ApiResponse<T> {
        private int code;
        private String message;
        private T data;
        
        public boolean isSuccess() {
            return code == 0 || code == 200;
        }
    }}

-- 商品基础信息表CREATE TABLE tb_product (
    id BIGINT PRIMARY KEY AUTO_INCREMENT,
    item_id BIGINT NOT NULL COMMENT '淘宝商品ID',
    seller_nick VARCHAR(100) NOT NULL COMMENT '卖家昵称',
    title VARCHAR(500) NOT NULL COMMENT '商品标题',
    category VARCHAR(100) COMMENT '类目',
    pic_url VARCHAR(500),
    is_tmall TINYINT(1) DEFAULT 0,
    status TINYINT(1) DEFAULT 1 COMMENT '1上架 0下架',
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
    UNIQUE KEY uk_item_id (item_id)) ENGINE=InnoDB COMMENT='商品基础信息';-- 价格历史表（时序数据）CREATE TABLE tb_price_history (
    id BIGINT PRIMARY KEY AUTO_INCREMENT,
    item_id BIGINT NOT NULL,
    original_price DECIMAL(10,2) COMMENT '原价',
    promotion_price DECIMAL(10,2) COMMENT '促销价',
    final_price DECIMAL(10,2) NOT NULL COMMENT '到手价',
    coupon_info VARCHAR(500) COMMENT '优惠券信息',
    captured_at TIMESTAMP NOT NULL COMMENT '采集时间',
    INDEX idx_item_time (item_id, captured_at)) ENGINE=InnoDB COMMENT='价格历史';-- 销量历史表CREATE TABLE tb_sales_history (
    id BIGINT PRIMARY KEY AUTO_INCREMENT,
    item_id BIGINT NOT NULL,
    month_sales INT COMMENT '月销量',
    total_sales INT COMMENT '总销量',
    daily_increment INT COMMENT '日增量',
    captured_at TIMESTAMP NOT NULL,
    INDEX idx_item_time (item_id, captured_at)) ENGINE=InnoDB COMMENT='销量历史';-- SKU 监控表CREATE TABLE tb_sku_snapshot (
    id BIGINT PRIMARY KEY AUTO_INCREMENT,
    item_id BIGINT NOT NULL,
    sku_id BIGINT NOT NULL,
    properties VARCHAR(200) COMMENT '规格属性',
    price DECIMAL(10,2),
    stock INT,
    captured_at TIMESTAMP NOT NULL,
    UNIQUE KEY uk_item_sku_time (item_id, sku_id, captured_at)) ENGINE=InnoDB COMMENT='SKU快照';

import org.springframework.stereotype.Service;import java.util.*;import java.util.stream.Collectors;@Servicepublic class ChangeDetectionService {

    private final ProductDataRepository repository;
    private final NotificationService notificationService;

    public ChangeDetectionService(ProductDataRepository repository,
                                   NotificationService notificationService) {
        this.repository = repository;
        this.notificationService = notificationService;
    }

    /**
     * 检测价格变动并触发告警
     */
    public void detectPriceChanges(long itemId, ProductDetail current) {
        // 获取最近一次历史数据
        PriceHistory lastHistory = repository.findLatestPrice(itemId);
        
        if (lastHistory == null) {
            // 首次采集，直接保存
            savePriceHistory(itemId, current);
            return;
        }

        List<String> changes = new ArrayList<>();
        
        // 检测到手价变化
        double priceDiff = current.getFinalPrice() - lastHistory.getFinalPrice();
        if (Math.abs(priceDiff) > 0.01) {
            double changePercent = (priceDiff / lastHistory.getFinalPrice()) * 100;
            changes.add(String.format("到手价变动: ¥%.2f → ¥%.2f (%+.1f%%)",
                lastHistory.getFinalPrice(), current.getFinalPrice(), changePercent));
        }
        
        // 检测优惠券变化
        if (!Objects.equals(current.getCouponInfo(), lastHistory.getCouponInfo())) {
            changes.add(String.format("优惠券变更: %s → %s",
                lastHistory.getCouponInfo(), current.getCouponInfo()));
        }
        
        // 检测库存状态
        if (lastHistory.getStock() == 0 && current.getStock() > 0) {
            changes.add("🟢 商品补货！");
        } else if (lastHistory.getStock() > 0 && current.getStock() == 0) {
            changes.add("🔴 商品缺货！");
        }

        // 保存新数据
        savePriceHistory(itemId, current);
        
        // 发送告警
        if (!changes.isEmpty()) {
            PriceAlert alert = PriceAlert.builder()
                .itemId(itemId)
                .title(current.getTitle())
                .changes(changes)
                .currentPrice(current.getFinalPrice())
                .previousPrice(lastHistory.getFinalPrice())
                .timestamp(LocalDateTime.now())
                .build();
            
            notificationService.send(alert);
        }
    }

    /**
     * 检测销量异常增长（识别爆款）
     */
    public void detectSalesAnomaly(long itemId, ProductDetail current) {
        SalesHistory yesterday = repository.findSalesAt(itemId, LocalDateTime.now().minusDays(1));
        
        if (yesterday != null) {
            int dailyIncrement = current.getMonthSales() - yesterday.getMonthSales();
            double growthRate = (double) dailyIncrement / yesterday.getMonthSales();
            
            // 日销量增长超过 300% 触发告警
            if (growthRate > 3.0 && dailyIncrement > 50) {
                SalesAlert alert = SalesAlert.builder()
                    .itemId(itemId)
                    .title(current.getTitle())
                    .dailyIncrement(dailyIncrement)
                    .growthRate(growthRate)
                    .currentSales(current.getMonthSales())
                    .alertType("爆款预警")
                    .build();
                
                notificationService.send(alert);
            }
        }
        
        repository.saveSalesHistory(itemId, current.getMonthSales(), dailyIncrement);
    }

    /**
     * 检测 SKU 级别变化
     */
    public void detectSkuChanges(long itemId, List<<SkuDetail> currentSkus) {
        List<<SkuSnapshot> previousSkus = repository.findLatestSkuSnapshot(itemId);
        Map<Long, SkuSnapshot> previousMap = previousSkus.stream()
            .collect(Collectors.toMap(SkuSnapshot::getSkuId, s -> s));

        for (SkuDetail sku : currentSkus) {
            SkuSnapshot prev = previousMap.get(sku.getSkuId());
            
            if (prev != null) {
                // SKU 价格变化
                if (Math.abs(sku.getPrice() - prev.getPrice()) > 0.01) {
                    notificationService.sendSkuPriceAlert(itemId, sku, prev.getPrice());
                }
                // SKU 库存变化
                if (prev.getStock() == 0 && sku.getStock() > 0) {
                    notificationService.sendSkuRestockAlert(itemId, sku);
                }
            }
        }
        
        repository.saveSkuSnapshot(itemId, currentSkus);
    }}

┌─────────────────────────────────────────────────────────────┐
│                     调度层（Spring Scheduler）                │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐      │
│  │ 价格监控任务  │  │ 销量监控任务  │  │ 库存扫描任务  │      │
│  │ (30min)      │  │ (6h)         │  │ (1h)         │      │
│  └──────┬───────┘  └──────┬───────┘  └──────┬───────┘      │
└─────────┼─────────────────┼─────────────────┼──────────────┘
          │                 │                 │
          ▼                 ▼                 ▼
┌─────────────────────────────────────────────────────────────┐
│                     数据采集层                                 │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐      │
│  │ 官方 API SDK │  │ 淘客 API     │  │ 第三方 HTTP  │      │
│  │ (自有店铺)   │  │ (公开商品)   │  │ (补充数据)   │      │
│  └──────┬───────┘  └──────┬───────┘  └──────┬───────┘      │
└─────────┼─────────────────┼─────────────────┼──────────────┘
          │                 │                 │
          ▼                 ▼                 ▼
┌─────────────────────────────────────────────────────────────┐
│                     数据处理层                                 │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐      │
│  │ 数据清洗     │  │ 变化检测     │  │ 异常识别     │      │
│  │ (字段映射)   │  │ (价格/销量)  │  │ (爆款/缺货)  │      │
│  └──────┬───────┘  └──────┬───────┘  └──────┬───────┘      │
└─────────┼─────────────────┼─────────────────┼──────────────┘
          │                 │                 │
          ▼                 ▼                 ▼
┌─────────────────────────────────────────────────────────────┐
│                     存储层                                     │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐      │
│  │ MySQL        │  │ Redis        │  │ Elasticsearch│      │
│  │ (关系数据)   │  │ (缓存/队列)  │  │ (全文检索)   │      │
│  └──────────────┘  └──────────────┘  └──────────────┘      │
└─────────────────────────────────────────────────────────────┘
          │
          ▼
┌─────────────────────────────────────────────────────────────┐
│                     告警通知层                                 │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐      │
│  │ 钉钉/飞书    │  │ 邮件         │  │ Webhook      │      │
│  │ 机器人      │  │ (详细报表)   │  │ (自定义)     │      │
│  └──────────────┘  └──────────────┘  └──────────────┘      │
└─────────────────────────────────────────────────────────────┘

import com.google.common.util.concurrent.RateLimiter;import org.springframework.retry.annotation.Backoff;import org.springframework.retry.annotation.Retryable;import org.springframework.stereotype.Component;@Componentpublic class ResilientApiCaller {

    // 令牌桶限流：每秒 2 个请求（官方 API 建议频率）
    private final RateLimiter rateLimiter = RateLimiter.create(2.0);

    /**
     * 带重试和限流的 API 调用
     */
    @Retryable(
        value = {ApiException.class, IOException.class},
        maxAttempts = 3,
        backoff = @Backoff(delay = 1000, multiplier = 2)
    )
    public <T> T callWithResilience(Callable<T> apiCall) throws Exception {
        // 获取令牌（阻塞等待）
        rateLimiter.acquire();
        
        try {
            return apiCall.call();
        } catch (ApiException e) {
            if (isRateLimitError(e)) {
                // 触发限流时额外等待
                Thread.sleep(5000);
            }
            throw e;
        }
    }

    private boolean isRateLimitError(ApiException e) {
        String subCode = e.getSubCode();
        return subCode != null && (
            subCode.contains("limit") ||
            subCode.contains("accesscontrol") ||
            subCode.contains("frequency")
        );
    }}