Java
最新版本:v1.0.0
更新时间:2026-10-27
1. 概述
从 6.1 版本开始,AE 新增实验套件功能,支持在 AE 后台创建实验,设置对照组和实验组的变量值,通过SDK 拉取至实验相关信息,为不同组别的用户展示不同的内容。
本文介绍Java服务端SDK的集成过程,只需要关注与数数 SDK 的交互即可,不需要关心 AE 后台的任务细节。
Java 服务端实验 SDK 用于获取 AE 实验中的 Feature 配置。业务服务传入当前用户标识和需要的 Feature Key,由配置中心(RCC)完成远端分流,SDK 返回配置值及命中的实验信息。业务根据配置执行逻辑,并在配置实际参与业务后上报曝光事件。
- Feature Key 是后台配置的变量标识,示例使用 checkout_button,接入时替换为项目实际的 Key。
- 客户端初始化后不会自动拉取当前用户的实验配置;业务通过 fetch(FeatureRequest) 或 fetch(accountId, distinctId) 发起请求。
- 未命中实验仍可能返回 Feature 的默认配置值。
2. 集成
2.1 环境与依赖
要求 JDK 8 或以上版本。SDK 已发布到 Maven Central,推荐通过 Maven 或 Gradle 自动引入,以同时解析所需的传递依赖。
<dependency>
<groupId>cn.thinkingdata</groupId>
<artifactId>td-feature-java</artifactId>
<version>1.0.0</version>
</dependency>
Gradle 示例:
repositories {
mavenCentral()
}
dependencies {
implementation 'cn.thinkingdata:td-feature-java:1.0.0'
}
Maven 坐标的 groupId 为 cn.thinkingdata;Java 包名仍为 cn.thinkingai.feature,POM 声明的运行依赖如下:
| 依赖 | 用途 | 1.0.0 POM 声明版本 |
|---|---|---|
| thinkingdatasdk | Java 数据采集 SDK,用于曝光上报 | 3.0.6 |
| httpclient | 访问配置中心 | 4.5.14 |
| caffeine | 配置缓存与曝光去重 | 2.9.3 |
| slf4j-api | 日志接口,日志实现由业务工程提供 | 1.7.36 |
| guava / re2j / commons-codec | 基础依赖 | 31.1-jre / 1.8 / 1.14 |
这些依赖会随 SDK 传递引入,通常无需逐项添加。
3. 初始化与快速接入
3.1 完整示例:
下面的示例使用 SDK 默认配置,由 SDK 自动创建数据采集实例,获取当前用户可见的全部 Feature,并通过 getFeatureKeys() 取得全部 Key,再选取 checkout_button 用于业务并手动曝光。TDFeatureClient 应按 App ID 和服务地址在应用内复用为单例;每次请求分别构造当前用户的 FeatureRequest。serverUrl 请填写同时支持配置查询和数据采集的服务根地址,并将 App ID、用户标识和业务 Key 替换为实际值。
import cn.thinkingai.feature.api.FeatureConfig;
import cn.thinkingai.feature.api.FeatureRequest;
import cn.thinkingai.feature.api.FeatureResult;
import cn.thinkingai.feature.api.SplitMode;
import cn.thinkingai.feature.api.TDFeatureClient;
import cn.thinkingai.feature.common.Config;
import java.util.Collections;
import java.util.Set;
public class RemoteSplitQuickStart {
public static void main(String[] args) throws Exception {
String appId = "YOUR_APP_ID";
TDFeatureClient client = new TDFeatureClient(Config.builder()
.appId(appId)
.serverUrl("https://YOUR_SERVER_URL")
.splitMode(SplitMode.REMOTE)
.build());
try {
String buttonStyle = "control"; // 业务默认值
FeatureResult feature = null;
try {
FeatureConfig config = client.fetch(FeatureRequest.builder()
.accountId("user_123")
.distinctId("visitor_456")
// 不指定 featureKey/featureKeys,拉取当前用户可见的全部配置
.build());
Set<String> featureKeys = config.getFeatureKeys();
System.out.println("本次返回的全部 Feature Key:" + featureKeys);
feature = config.getFeature("checkout_button");
if (feature != null && feature.hasValue()) {
buttonStyle = feature.getValueAsString("control");
}
} catch (RuntimeException e) {
// 请求失败时使用业务默认值,并记录日志
System.err.println("配置请求失败:" + e.getMessage());
}
} finally {
// 实际服务仅在应用退出时执行;不要在每个请求结束后关闭单例
client.close();
}
}
}
3.2 已有 TDAnalytics
如果业务已经接入 Java 采集 SDK(TDAnalytics),保留原有采集 SDK 的初始化、Consumer 和上报配置。在采集 SDK 初始化完成后,将业务持有的同一个 TDAnalytics 单例传入 tdAnalytics(...),再创建实验 SDK,无需重新创建采集实例。
import cn.thinkingai.feature.api.SplitMode;
import cn.thinkingai.feature.api.TDFeatureClient;
import cn.thinkingai.feature.common.Config;
import cn.thinkingdata.analytics.TDAnalytics;
public class ExistingAnalyticsIntegration {
public static TDFeatureClient createFeatureClient(
String appId, String rccServerUrl, TDAnalytics analytics) {
if (analytics == null) {
throw new IllegalArgumentException("请传入业务已有的 TDAnalytics 实例");
}
return new TDFeatureClient(Config.builder()
.appId(appId)
.serverUrl(rccServerUrl)
.splitMode(SplitMode.REMOTE)
.tdAnalytics(analytics) // 复用已有采集 SDK
.build());
}
}
4. 获取配置与实验信息
4.1 传入当前用户身份
| 请求参数 | 含义 | 使用要求 |
|---|---|---|
| accountId | 账号 ID,对应 #account_id | 按账号分流的实验应传入准确、稳定的账号 ID。 |
| distinctId | 访客 ID,对应 #distinct_id | 按访客分流的实验应传入与后台定义一致的访客 ID。 |
accountId 和 distinctId 至少传入一个非空值,可以同时传入。仅满足“有一个 ID”并不保证命中实验,实际传入的身份必须满足后台分流主体和人群条件。用户切换时,应在新的请求中传入新用户的标识;不要跨用户复用 FeatureResult。
4.2 获取一个或多个 Feature
FeatureConfig config = client.fetch(FeatureRequest.builder()
.accountId("user_123")
.featureKeys("checkout_button", "recommendation_enabled", "discount_rate", "page_config")
.build());
FeatureResult button = config.getFeature("checkout_button");
String buttonStyle = button == null
? "control" : button.getValueAsString("control");
单个 Key 使用 featureKey("checkout_button");多个 Key 使用 featureKeys(...),支持可变参数和 List<String>。建议按业务需要请求 Key,减少传输及结果处理开销。getFeature(key) 在返回结果中没有该 Key 时返回 null。
4.3 读取不同类型的配置值
| 后台变量类型 | 读取方法 | 返回类型 |
|---|---|---|
| 字符串 | getValueAsString(defaultValue) | String |
| 数值 | getValueAsDouble(defaultValue) | Double |
| 布尔值 | getValueAsBoolean(defaultValue) | Boolean |
| JSON | getValueAsJson(defaultValue) | com.alibaba.fastjson2.JSONObject |
| 原始值 | getValue() | Object |
FeatureConfig config = client.fetch(FeatureRequest.builder()
.accountId("user_123")
.featureKeys("recommendation_enabled", "discount_rate", "page_config")
.build());
FeatureResult enabledFeature = config.getFeature("recommendation_enabled");
boolean enabled = enabledFeature == null
? false : enabledFeature.getValueAsBoolean(false);
FeatureResult rateFeature = config.getFeature("discount_rate");
double rate = rateFeature == null ? 0.0 : rateFeature.getValueAsDouble(0.0);
JSONObject defaults = new JSONObject();
defaults.put("theme", "default");
FeatureResult pageFeature = config.getFeature("page_config");
com.alibaba.fastjson2.JSONObject page = pageFeature == null
? defaults : pageFeature.getValueAsJson(defaults);
四种类型读取方法都提供无参重载;值缺失或无法转换时返回 null,带参重载返回传入的默认值。JSON 使用 Fastjson2 的 JSONObject。布尔读取识别布尔类型及 true/false 字符串,其他值回退到默认值。业务仍需处理配置请求失败抛出的异常,类型默认值不会替代网络异常处理。
4.4 获取实验信息
if (feature != null && feature.isExperimentMatched()) {
ExperimentInfo info = feature.getExperimentInfo();
String experimentId = info.fetchId();
String groupId = info.fetchGroupId();
boolean controlGroup = info.isControlGroup();
String featureKey = feature.getFeatureKey();
String featureVersion = feature.getFeatureVersion();
}
hasValue() 表示当前 Feature 是否有值;isExperimentMatched() 表示是否带有有效实验信息。未命中实验时也可能得到后台默认值,此时 getExperimentInfo() 为 null。只读取实验信息或调用 hasValue()/isExperimentMatched() 不会触发自动曝光。
4.5 获取当前请求可见的全部配置
FeatureConfig all = client.fetch("user_123", "visitor_456");
Set<String> keys = all.getFeatureKeys();
不指定 Feature Key 时获取当前身份和请求条件下服务端返回的全部配置。
4.6 自定义请求参数
FeatureConfig config = client.fetch(FeatureRequest.builder()
.accountId("user_123")
.featureKey("checkout_button")
.customParam("vip_level", 3)
.customParam("channel", "app_store")
.build());
通过 customParam(key, value) 追加一个参数,也可以用 customParams(Map<String, Object>) 批量传入。参数名、类型及含义应与后台配置通道和规则定义一致。身份、SDK 标识及 Key 筛选分别由专用参数管理,不要通过自定义参数覆盖 #account_id、#distinct_id、#lib、#feature_key。自定义请求参数不等于设置新的分流主体。
5. 上报曝光事件
曝光表示实验配置实际参与业务。仅仅发起 fetch、返回 FeatureConfig 或查看实验元信息,都不代表配置已经用于业务。SDK 通过数据采集实例上报 te_experiment_exposure 事件,携带实验、分组和 Feature 等信息。
5.1 手动曝光(默认方式)
初始化时保持 automaticExposureTracking(false)。在业务实际采用配置后,传入本次获取的 FeatureResult;曝光 API 的参数是结果对象,不是 Feature Key 字符串。
// feature 必须来自本次当前用户的 fetch 结果
// 在此之前,业务已经实际使用了该 Feature 的配置值
if (feature != null && feature.hasValue() && feature.isExperimentMatched()) {
Map<String, Object> properties = new HashMap<>();
properties.put("scene", "checkout");
client.exposure(feature, properties);
// 不需要自定义属性时,使用 client.exposure(feature)
}
自定义曝光属性中,以 # 开头的属性名由 SDK 保留,传入时会被忽略。SDK 会跳过没有有效实验信息的结果。
5.2 自动曝光(可选)
将 automaticExposureTracking 设置为 true 后,首次读取结果的 getValue() 或 getValueAsString/Double/Boolean/Json(...) 时触发自动曝光,前提是该结果命中实验。
TDFeatureClient automaticClient = new TDFeatureClient(Config.builder()
.appId("YOUR_APP_ID")
.serverUrl("https://YOUR_RCC_SERVER")
.splitMode(SplitMode.REMOTE)
.tdAnalytics(analytics)
.automaticExposureTracking(true)
.build());
// automaticClient 在应用中复用,仅在应用退出时 close()
FeatureConfig config = automaticClient.fetch(FeatureRequest.builder()
.accountId("user_123")
.featureKey("checkout_button")
.build());
FeatureResult result = config.getFeature("checkout_button");
String value = result == null ? "control" : result.getValueAsString("control");
// 若命中实验,上面的值读取会触发曝光
5.3 去重、异步发送与刷新
曝光在 SDK 后台队列中异步处理,exposure(...) 返回不代表事件已经入库。默认按“分流主体 + 实验 ID + 分组 ID”在当前 Client 的内存缓存中去重:最多保留 100000 条标记,默认有效期 86400 秒。去重缓存容量淘汰、Client 重建或进程重启后可能再次上报;
// 排障、短生命周期任务结束或应用退出前按需调用
client.flush();
flush() 等待此前接受的曝光任务,并触发采集 SDK 的 flush。
6. 异步获取配置
异步重载同样需要传入 FeatureRequest。异步线程数默认 5,等待队列容量默认 1000;队列满或 Client 已关闭时产生 RejectedExecutionException,应回退业务默认值并记录异常。
6.1 Future 形式
FeatureRequest request = FeatureRequest.builder()
.accountId("user_123")
.featureKey("checkout_button")
.build();
Future<FeatureConfig> future = client.fetchAsync(request);
String value = "control";
try {
FeatureConfig config = future.get(2, TimeUnit.SECONDS);
FeatureResult result = config.getFeature("checkout_button");
if (result != null) {
value = result.getValueAsString("control");
}
} catch (InterruptedException e) {
Thread.currentThread().interrupt();
} catch (java.util.concurrent.TimeoutException
| java.util.concurrent.ExecutionException e) {
// 记录失败;value 保持业务默认值
System.err.println("异步获取失败:" + e.getMessage());
}
6.2 回调形式
client.fetchAsync(FeatureRequest.builder()
.accountId("user_123")
.featureKey("checkout_button")
.build(), new FeatureCallback() {
@Override
public void onSuccess(FeatureConfig config) {
FeatureResult result = config.getFeature("checkout_button");
String value = result == null
? "control" : result.getValueAsString("control");
// 将配置交给业务使用;手动曝光在实际使用后触发
}
@Override
public void onFailure(Exception e) {
// 记录失败,并继续使用业务默认值
System.err.println("异步获取失败:" + e.getMessage());
}
});
7. 配置缓存
配置缓存默认关闭。启用 enableCache(true) 后,相同有效请求的后续调用可以复用已缓存的返回配置;请求身份、Feature Key 集合和自定义请求参数均参与缓存区分。缓存不是后台轮询:缓存有效时调用可直接返回,缓存失效后在下一次请求时重新访问 RCC。
TDFeatureClient cachedClient = new TDFeatureClient(Config.builder()
.appId("YOUR_APP_ID")
.serverUrl("https://YOUR_RCC_SERVER")
.splitMode(SplitMode.REMOTE)
.tdAnalytics(analytics)
.enableCache(true)
.cacheExpireTime(300)
.maxCacheSize(10000)
.build());
// 仅清除当前 Client 的配置缓存
cachedClient.clearCache();

