Java 基础 API

以下示例使用已初始化的 client。安装见Java 集成，发送方式见上报方式，事件定义见服务端事件与用户操作。

事件与画像操作

生命周期事件 (trackLifecycle)

记录服务调用、批处理任务或事务的开始、完成与失败：

import com.trackbusiness.server.operations.ServerLifecycleOperation;
import com.trackbusiness.server.operations.ServerOperationOptions;
import com.trackbusiness.server.model.ServerIdentity;

long start = System.currentTimeMillis();
String txId = "tx_987654";
ServerOperationOptions options = ServerOperationOptions.builder(new ServerIdentity("user_1024", null)).build();

// 记录事务开始
client.trackLifecycle(ServerLifecycleOperation.builder(options,
    ServerLifecycleOperation.Kind.TRANSACTION, "payment-transaction",
    ServerLifecycleOperation.Phase.STARTED, txId).build());

try {
    doPaymentTransaction();
    // 记录事务成功（必须包含耗时 durationMs）
    client.trackLifecycle(ServerLifecycleOperation.builder(options,
        ServerLifecycleOperation.Kind.TRANSACTION, "payment-transaction",
        ServerLifecycleOperation.Phase.COMPLETED, txId)
        .durationMs(System.currentTimeMillis() - start).build());
} catch (Exception ex) {
    // 记录事务失败（传入低基数错误类型）
    client.trackLifecycle(ServerLifecycleOperation.builder(options,
        ServerLifecycleOperation.Kind.TRANSACTION, "payment-transaction",
        ServerLifecycleOperation.Phase.FAILED, txId)
        .durationMs(System.currentTimeMillis() - start)
        .errorType("BALANCE_INSUFFICIENT").build());
    throw ex;
}

用户画像操作 (profileSet / profileDelete)

画像方法提交的是操作事件；实际画像更新、并发原子性和删除范围取决于接收端实现。详见服务端操作语义。

import com.trackbusiness.server.model.ServerIdentity;
import java.util.HashMap;
import java.util.Map;

ServerIdentity user = new ServerIdentity("user_1024", null);

// 覆盖用户画像标签
Map<String, Object> profile = new HashMap<>();
profile.put("vip_level", 3);
profile.put("company_name", "Acme Corp");
client.profileSet(user, profile);

// 提交数值画像属性自增请求（如累计充值次数）
client.profileIncrement(user, java.util.Collections.<String, Object>singletonMap("total_recharges", 1));

// 提交用户画像删除请求
client.profileDelete(user);

---

公共与动态属性

同名属性的优先级为：单次事件属性 > 动态属性 > 公共属性。

公共属性 (registerSuperProperties)

适用于多个事件共用的属性，例如服务版本和集群代号：

Map<String, Object> superProps = new HashMap<>();
superProps.put("cluster_id", "k8s-prod-shanghai-01");
client.registerSuperProperties(superProps);

动态属性（MDC / ThreadLocal）

构建 ServerClient 时设置 dynamicProperties(Supplier)，在调用 track() 的线程读取 trace_id 等请求字段：

import org.slf4j.MDC;
import java.util.HashMap;
import java.util.Map;

ServerClient client = ServerClient.builder(endpoint, projectKey)
    // 注册动态属性提供器：在当前调用线程同步提取
    .dynamicProperties(() -> {
        Map<String, Object> dynamic = new HashMap<>();
        String traceId = MDC.get("traceId");
        if (traceId != null) {
            dynamic.put("trace_id", traceId);
        }
        return dynamic;
    })
    .build();