跳到主要内容

Node

最近更新 2026/10/29

最新版本: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) 基础地址。
splitModeSplitMode.REMOTE也可传字符串 REMOTE;LOCAL 当前不支持。
timeout5000 ms每次 HTTP 尝试的超时。
maxHttpConnections20RCC 连接池最大连接数。
tlsCaNode 默认信任根可选 PEM CA 字符串或数组,显式设置会替换该 Client 的默认 CA 列表。

3.4.2 重试​

配置默认值说明
retryTimes0首次请求之后的额外重试次数,范围 0–10。
retryStrategyEXPONENTIAL_BACKOFF可选 FIXED_INTERVAL。
retryInterval500 ms初始退避间隔,允许为 0。

3.4.3 结果缓存​

配置默认值说明
enableCachefalse显式启用成功结果缓存。
cacheExpireTime86400 秒仅在 RCC TTL 非正数时回退,允许为 0。
maxCacheSize10000结果缓存条目上限,0 表示不保存。

3.4.4 曝光与采集​

配置默认值说明
autoExposurefalse首次原始值或类型化值读取时尝试曝光。
exposureDedupMaxSize100000曝光去重条目上限。
exposureDedupExpireSeconds86400 秒非滑动去重 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 排队,等待位置满同样拒绝。缓存命中直接返回,不占队列。
这篇文档对你有帮助吗?