Node
最新版本:v0.0.2
更新时间:2026-10-29
1. 概述
从 AE 6.1 版本开始,实验套件支持在后台创建实验,为对照组和实验组配置不同的变量值。Node.js 服务端实验 SDK 用于获取这些 Feature 配置:业务传入当前用户身份和 Feature Key,由配置中心(RCC)完成远端分流,SDK 返回配置值及命中的实验信息。业务采用配置后,再按实际曝光时机上报事件。
- Feature Key 是后台配置的变量标识,示例使用 checkout_button,接入时请替换为项目实际发布的 Key。
- createClient() 只校验并创建客户端,不访问网络,也不会自动拉取配置;通过 client.fetch(request) 发起查询。
- 未命中实验仍可能返回后台默认配置值。Feature 有值与命中实验是两个不同的判断。
- 当前版本仅支持远端分流(REMOTE)。LOCAL 为预留值,传入会报 INVALID_CONFIG;结果缓存和业务默认值不进行本地分流。
2. 集成
2.1 环境与依赖
要求 Node.js 12.0.0 或以上版本。SDK 以 CommonJS 发布,并提供 TypeScript 类型声明;下文 CommonJS 示例可在最低运行时使用。
SDK 已发布到 npm,安装最新版本:
npm install td-feature-node@latest
npm 将同时安装生产依赖,其中官方采集 SDK 为 thinkingdata-node@1.5.0。业务运行无需 TypeScript 或其他开发工具;安装需要能够访问配置的 npm registry。
2.2 接入前准备
| 信息 | 用途 |
|---|---|
| appId | 实验项目的 App ID,请使用平台提供的值。 |
| serverUrl | 支持远端决策和曝光采集的服务基础地址,例如 https://service.example.com。 |
| Feature Key | 平台已配置并发布的变量标识。 |
| 当前用户身份 | accountId、distinctId 至少一个为非空字符串,且满足后台分流主体和人群条件。 |
| 自定义请求参数 | 后台规则所需的上下文,参数名、类型和含义与后台配置一致。 |
3. 初始化与快速接入
3.1 完整示例
保存为 quickstart.js,将 App ID、服务地址、用户身份和业务 Key 替换为实际值,执行 node quickstart.js。示例使用默认配置,获取全部 Key、读取 checkout_button,并在采用结果后手动曝光;SDK 自动创建采集实例。
const { createClient, SplitMode } = require('td-feature-node');
// 在长期服务中,每个进程、每个项目复用一个 Client。
const client = createClient({
appId: 'YOUR_APP_ID',
serverUrl: 'https://YOUR_SERVER_URL',
splitMode: SplitMode.REMOTE,
});
async function main() {
try {
const config = await client.fetch({
accountId: 'user_123',
distinctId: 'visitor_456',
// 不指定 featureKeys,获取当前身份可见的全部配置。
});
console.log('本次返回的全部 Feature Key:', Object.keys(config.features));
const feature = config.features['checkout_button'];
const buttonStyle = feature ? feature.asString('control') : 'control';
console.log('采用的按钮样式:', buttonStyle); // 替换为业务实际使用逻辑。
// 实际采用结果后再曝光;未匹配有效实验时 SDK 会跳过。
client.expose(feature, { scene: 'checkout' });
} catch (error) {
// 请求失败使用业务默认值,不构造实验结果或上报曝光。
console.error('配置请求失败:', error.code, error.message);
console.log('采用的按钮样式:control');
} finally {
// 这是单次脚本;长期服务只在应用退出时关闭共享 Client。
await client.close();
}
}
main().catch(function (error) {
console.error(error);
process.exitCode = 1;
});
长期服务应按项目和服务地址在每个进程内复用 Client。每个业务请求传入当前用户的身份,不要逐请求创建或关闭 Client,也不要跨用户复用 Feature。client.options 是归一化后的只读配置,client.closed 表示是否已开始关闭。
3.2 复用已有采集实例
如果业务已接入官方 Node.js 采集 SDK,保留原有实例的 Consumer、批量和定时刷新配置,在采集实例初始化完成后,将同一个实例传给 tdAnalytics:
const { createClient, SplitMode } = require('td-feature-node');
// existingAnalytics 是业务已初始化的 track/flush/close 实例。
const client = createClient({
appId: 'YOUR_APP_ID',
serverUrl: 'https://YOUR_SERVER_URL',
splitMode: SplitMode.REMOTE,
tdAnalytics: existingAnalytics,
});
未注入时,SDK 在首次曝光时惰性创建官方 Batch 采集实例,使用同一 appId 和 serverUrl。
3.3 ESM 与 TypeScript
ESM 项目通过默认导入消费 CommonJS 包;下方为导入写法,其余调用放在 async 函数中:
import sdk from 'td-feature-node';
const { createClient, SplitMode } = sdk;
TypeScript 项目可直接导入 API 与公开类型,编译工具版本应与业务工程匹配:
import { createClient, SplitMode } from 'td-feature-node';
import type { ClientOptions, FeatureRequest } from 'td-feature-node';
const options: ClientOptions = {
appId: 'YOUR_APP_ID',
serverUrl: 'https://YOUR_SERVER_URL',
splitMode: SplitMode.REMOTE,
};
const client = createClient(options);
const request: FeatureRequest = {
accountId: 'user_123',
featureKeys: ['checkout_button'],
};
3.4 初始化配置参考
3.4.1 连接与请求
| 配置 | 默认值 | 说明 |
|---|---|---|
| appId | 必填 | 项目 App ID,非空字符串。 |
| serverUrl | 必填 | 远端决策与 SDK 自建采集共用的 HTTP(S) 基础地址。 |
| splitMode | SplitMode.REMOTE | 也可传字符串 REMOTE;LOCAL 当前不支持。 |
| timeout | 5000 ms | 每次 HTTP 尝试的超时。 |
| maxHttpConnections | 20 | RCC 连接池最大连接数。 |
| tlsCa | Node 默认信任根 | 可选 PEM CA 字符串或数组,显式设置会替换该 Client 的默认 CA 列表。 |
3.4.2 重试
| 配置 | 默认值 | 说明 |
|---|---|---|
| retryTimes | 0 | 首次请求之后的额外重试次数,范围 0–10。 |
| retryStrategy | EXPONENTIAL_BACKOFF | 可选 FIXED_INTERVAL。 |
| retryInterval | 500 ms | 初始退避间隔,允许为 0。 |
3.4.3 结果缓存
| 配置 | 默认值 | 说明 |
|---|---|---|
| enableCache | false | 显式启用成功结果缓存。 |
| cacheExpireTime | 86400 秒 | 仅在 RCC TTL 非正数时回退,允许为 0。 |
| maxCacheSize | 10000 | 结果缓存条目上限,0 表示不保存。 |
3.4.4 曝光与采集
| 配置 | 默认值 | 说明 |
|---|---|---|
| autoExposure | false | 首次原始值或类型化值读取时尝试曝光。 |
| exposureDedupMaxSize | 100000 | 曝光去重条目上限。 |
| exposureDedupExpireSeconds | 86400 秒 | 非滑动去重 TTL。 |
| tdAnalytics | 未指定 | 业务已有官方采集实例,由业务持有和关闭。 |
| exposureAdapter | 未指定 | 自定义采集适配器,与 tdAnalytics 互斥,由业务持有。 |
3.4.5 私有 CA 与自定义采集
使用私有 CA 时可以显式传入受信任的证书;证书链和主机名校验仍然生效。tlsCa 只影响 RCC 和 SDK 自建采集器,外部实例仍使用自身的 TLS 配置:
const fs = require('fs');
const { createClient } = require('td-feature-node');
const client = createClient({
appId: 'YOUR_APP_ID',
serverUrl: 'https://YOUR_SERVER_URL',
tlsCa: fs.readFileSync('/path/to/trusted-ca.pem', 'utf8'),
});
4. 获取配置与实验信息
4.1 传入当前用户身份
| 请求参数 | 含义 | 使用要求 |
|---|---|---|
| accountId | 账号 ID,对应 #account_id | 按账号分流时传入稳定、准确的账号标识。 |
| distinctId | 访客或设备 ID,对应 #distinct_id | 按访客分流时传入与后台定义一致的标识。 |
accountId 和 distinctId 至少一个为非空字符串,也可同时传入。数字 ID 需由业务明确转为字符串;身份不能含控制字符。
4.2 获取一个或多个 Feature
client.fetch(request, options?) 返回 Promise<Evaluation>。以下局部示例中的 client 为第 3 节创建的共享 Client,await 调用应放在 async 函数内。单个和多个 Key 均使用 featureKeys 数组:
const config = await client.fetch({
accountId: 'user_123',
distinctId: 'visitor_456',
featureKeys: ['checkout_button', 'recommendation_enabled'],
});
const feature = config.features['checkout_button'];
4.3 读取不同类型的配置值
| 后台变量类型 | 读取方法 | 返回类型与回退规则 |
|---|---|---|
| 字符串 | feature.asString(defaultValue) | string;非 null 值转字符串,对象和数组转 JSON 文本。 |
| 数值 | feature.asNumber(defaultValue) | number;接受数字或非空数字字符串,使用原生 Number() 转换。 |
| 布尔 | feature.asBoolean(defaultValue) | boolean;接受布尔值及大小写不敏感的 true/false 字符串,数字 0/1 不转换。 |
| JSON 对象 | feature.asJson(defaultValue) | JSON 对象;接受对象或可解析为对象的 JSON 字符串,数组、null、无效 JSON 回退。 |
| 原始值 | feature.value | 原始 JSON 值,包括数组和 null。 |
const config = await client.fetch({
accountId: 'user_123',
featureKeys: ['recommendation_enabled', 'discount_rate', 'page_config'],
});
const enabledFeature = config.features['recommendation_enabled'];
const enabled = enabledFeature ? enabledFeature.asBoolean(false) : false;
const rateFeature = config.features['discount_rate'];
const rate = rateFeature ? rateFeature.asNumber(0) : 0;
const defaults = { theme: 'default' };
const pageFeature = config.features['page_config'];
const page = pageFeature ? pageFeature.asJson(defaults) : defaults;
四种类型读取方法省略默认值时返回 null;值为 null 或不能转换时使用传入的默认值。配置缺失与转换失败需要分别处理。false、0、空字符串是有效值,请勿用 value || defaultValue 覆盖。
4.4 获取实验信息
const feature = config.features['checkout_button'];
if (feature) {
console.log('Feature Key:', feature.key);
console.log('是否有值:', feature.hasValue);
const info = feature.experiment;
if (info && info.experimentId && info.experimentGroupId) {
console.log('实验 ID:', info.experimentId);
console.log('分组 ID:', info.experimentGroupId);
console.log('是否对照组:', info.isControlGroup);
console.log('分桶身份:', info.bucketId);
}
}
4.5 获取当前请求可见的全部配置
const all = await client.fetch({
accountId: 'user_123',
distinctId: 'visitor_456',
});
const keys = Object.keys(all.features);
console.log(keys);
console.log(all.ttl); // RCC 原始 TTL,单位秒,不是缓存剩余时间。
featureKeys 省略、为 null 或为空数组时,获取当前身份及请求条件下服务端返回的全部配置。
4.6 自定义请求参数
const config = await client.fetch({
accountId: 'user_123',
featureKeys: ['checkout_button'],
customParams: {
vip_level: 3,
channel: 'app_store',
country: 'CN',
},
});
customParams 为 JSON 对象,参数名、类型和含义须与后台规则一致。支持字符串、有限数字、布尔、null、数组和嵌套对象;不接受 undefined、Date、BigInt、函数、NaN、Infinity 或循环引用。对象和数组中的 null 会保留。#account_id、#distinct_id、#lib、#feature_key 由 SDK 管理,不能通过自定义参数覆盖。自定义参数不等于设置新的分流主体。
5. 上报曝光事件
曝光表示实验配置实际参与业务。fetch 成功、拿到 Feature 或查看实验元信息均不代表已经曝光。SDK 通过采集实例上报 te_experiment_exposure,携带 #experiment_id、#experiment_group_id、#is_control_group 和 #rule_type="experiment"。当前远端解析未提供的 Feature 版本、分流来源等字段不会补造到事件中。
5.1 手动曝光(默认方式)
默认 autoExposure: false。在业务实际采用配置后,将本次返回的 Feature 对象传给 expose();参数不是 Feature Key 字符串:
const feature = config.features['checkout_button'];
const style = feature.asString('control');
console.log('业务已采用:', style); // 替换为实际业务逻辑。
const accepted = client.expose(feature, { scene: 'checkout', channel: 'web' });
console.log('曝光是否入队:', accepted);
5.2 自动曝光(可选)
const client = createClient({
appId: 'YOUR_APP_ID',
serverUrl: 'https://YOUR_SERVER_URL',
autoExposure: true,
});
const config = await client.fetch({
accountId: 'user_123',
featureKeys: ['checkout_button'],
});
const feature = config.features['checkout_button'];
const style = feature ? feature.asString('control') : 'control';
开启后,首次读取 feature.value 或调用 asString/asNumber/asBoolean/asJson 会尝试曝光,前提是有有效实验信息。每个返回的 Feature 最多自动触发一次,再经过 Client 级去重;缓存命中会返回带独立自动触发状态的新 Feature。
5.3 去重、异步发送与刷新
- 按“分流主体 + 实验 ID + 分组 ID”在当前 Client 内存中去重。主体优先选取 bucketId 的首个非空项,再选 accountId、distinctId;Feature Key 不参与去重,同一实验分组的多个 Feature 共用一次曝光。
- 去重始终启用,默认最多 100000 项、86400 秒,读取不续期。到期、容量淘汰、Client 重建或进程重启后可能再次上报;
- 曝光通过有界异步队列发送,默认 10000 个等待位置,另有一个活跃任务。SDK 自建采集器默认每批 100 条,不足一批最多缓冲 1000 ms。
6. 异步获取配置
6.1 async/await 与 Promise
async function readStyle(accountId) {
try {
const config = await client.fetch({
accountId: accountId,
featureKeys: ['checkout_button'],
});
const feature = config.features['checkout_button'];
return feature ? feature.asString('control') : 'control';
} catch (error) {
console.error('配置请求失败:', error.code);
return 'control';
}
}
client.fetch({ accountId: 'user_123', featureKeys: ['checkout_button'] })
.then(function (config) {
const feature = config.features['checkout_button'];
console.log(feature ? feature.asString('control') : 'control');
})
.catch(function (error) {
console.error(error.code, error.message);
});
上面的异步取值示例只展示查询,默认不会上报曝光;在实际采用返回值的位置,按第 5 节添加曝光调用。
6.2 超时、重试与并发
- timeout 默认 5000 ms,只约束每次 HTTP 尝试,包括连接等待和响应读取。排队、重试退避和 RCC 字段解码不计入该 HTTP 超时;开启重试后每次尝试重新计时。
- retryTimes 默认 0,不自动重试。显式设置为正数后,最大尝试次数为 1 + retryTimes,临时网络错误、单次超时及 HTTP 408/429/500/502/503/504 可有限重试。RCC 业务错误、非法响应、永久 DNS/证书错误等不重试。
- 默认最多 20 个活跃 fetch,无等待队列(maxQueueSize: 0)。并发位置满时立即以 QUEUE_FULL 拒绝;显式将 maxQueueSize 设为正数才启用有界 FIFO 排队,等待位置满同样拒绝。缓存命中直接返回,不占队列。

