SDK
SDK 性能优化指南
批量调用、响应缓存、异步模式与连接池调优，让您的集成高效运行
核心优化原则
单例客户端
CuiniaoClient 包含连接池，应作为单例使用。每次请求都创建新实例会导致连接池频繁销毁重建，性能下降明显。
批量接口优先
需要操作多条记录时，优先使用 Batch 接口。循环调用单条接口会产生 N 次 HTTP 往返，批量接口只需 1 次。
异步非阻塞
在后台任务或高并发场景中使用异步 API，避免线程阻塞等待 HTTP 响应，提升系统吞吐量。
合理缓存
内容资源详情、CTA 配置等变化频率低的数据适合本地缓存，可大幅减少 API 调用次数。
批量调用
翠鸟 SDK 提供多个批量接口，建议优先使用以减少网络往返。
避免在循环中逐条调用 API。如需处理 1000 条数据，应分为 10 批（每批100条）调用批量接口，而非调用 1000 次单条接口。
// 批量创建线索（Java）- 最多100条/次
List<CreateLeadRequest> batch = leads.stream()
.map(l -> CreateLeadRequest.builder()
.email(l.getEmail())
.name(l.getName())
.company(l.getCompany())
.build())
.collect(Collectors.toList());
BatchCreateResult result = client.leads().batchCreate(batch);
System.out.println("成功: " + result.getSuccessCount() +
", 失败: " + result.getFailureCount());
异步调用模式
SDK v3.1.0 起所有方法均提供 Async 变体，返回 CompletableFuture，适合高并发场景。
// 并行发起多个查询（Java）
CompletableFuture<Analytics> overviewFuture =
client.analytics().overviewAsync(AnalyticsRequest.builder().days(7).build());
CompletableFuture<LeadList> leadsFuture =
client.leads().listAsync(LeadListRequest.builder().days(7).build());
// 等待两个请求同时完成
CompletableFuture.allOf(overviewFuture, leadsFuture).join();
Analytics overview = overviewFuture.get();
LeadList leads = leadsFuture.get();
使用
CompletableFuture.allOf() 并行发起多个独立请求，相比串行调用可节省 50%-70% 的总耗时。响应数据缓存
以下数据适合在应用层缓存，以减少 API 调用频次：
- 内容资源列表（
GET /v1/resources）— 建议缓存 5 分钟 - CTA 配置（
GET /v1/cta/{id}）— 建议缓存 10 分钟 - 分析总览数据（
GET /v1/analytics/overview）— 建议缓存 1 小时
// 使用 Caffeine 缓存 CTA 配置（Java）
private final Cache<String, Cta> ctaCache = Caffeine.newBuilder()
.expireAfterWrite(10, TimeUnit.MINUTES)
.maximumSize(500)
.build();
public Cta getCta(String ctaId) {
return ctaCache.get(ctaId, id -> client.cta().get(id));
}
限速与重试策略
翠鸟 API 对不同套餐有请求频率限制（Rate Limit）。SDK 内置了自动重试机制，当收到 429 响应时会按退避策略自动等待并重试。
- 默认最大重试次数：3次，可通过
.maxRetries(5)调整 - 退避策略：等待 1s、2s、4s（指数退避，含随机抖动）
- 可通过
.onRateLimited(callback)注册监听，记录限速事件
// 自定义重试配置
CuiniaoClient client = new CuiniaoClient.Builder()
.apiKey("ck_live_xxx")
.maxRetries(5)
.onRateLimited(info -> {
log.warn("API 限速，等待 {}ms 后重试（第 {} 次）",
info.getRetryAfterMs(), info.getAttempt());
})
.build();