跳到主要内容

Java

最近更新 2026/10/27

最新版本: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 声明版本
thinkingdatasdkJava 数据采集 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
JSONgetValueAsJson(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();
这篇文档对你有帮助吗?