Java SDK

使用 Java Core SDK 从已认证的业务服务记录服务端事件。Core 保持 Java 8 兼容且不绑定 Web 框架；当前下载包不包含 Servlet Filter 和 Spring Boot Starter。

接入前向项目负责人获取测试环境的 endpoint 和公开 projectKey，并确认所选 SDK 包与宿主运行环境兼容。

1. 安装

从 Java SDK 下载页取得 server-java-core-1.0.0-offline.zip 离线集成包，核对归档内清单和校验材料，再将 maven/ 内容导入内部 Maven 仓库，或按组织规则配置离线 Maven 仓库：

xml

<dependency>
    <groupId>com.trackbusiness</groupId>
    <artifactId>track-business-server-core</artifactId>
    <version>1.0.0</version>
</dependency>

Gradle 可使用相同坐标。SDK 通过离线包或内部仓库安装，运行时要求 Java 8 或更高版本。

2. 初始化并记录首个事件

在应用启动时创建并复用 ServerClient，在宿主停机时关闭。示例从环境变量读取项目凭据。

java

import com.trackbusiness.server.ServerClient;
import com.trackbusiness.server.model.ServerIdentity;
import java.io.IOException;
import java.util.Collections;
import java.util.Map;

final class AnalyticsEvents {
    private final ServerClient analytics;

    AnalyticsEvents() throws IOException {
        String projectKey = System.getenv("TRACK_PROJECT_KEY");
        if (projectKey == null || projectKey.isEmpty()) {
            throw new IllegalStateException("TRACK_PROJECT_KEY is required");
        }
        this.analytics = ServerClient.builder(
            "https://collector.example.com/v1/events/batch", projectKey).build();
    }

    void record(String authenticatedUserId) {
        // authenticatedUserId 来自宿主完成认证后的业务主体。
        Map<String, Object> properties = Collections.<String, Object>singletonMap(
            "source", "java-docs");
        boolean admitted = analytics.track(
            "sdk_integration_check",
            new ServerIdentity(authenticatedUserId, null), properties);
        if (!admitted) {
            // 记录脱敏的拒收计数；不要写入身份或事件属性。
        }
    }

    void close() {
        try {
            com.trackbusiness.server.model.FlushResult result = analytics.close(5000L);
            if (result.getUnresolved() > 0) {
                // 接入宿主的脱敏告警；未决不等于成功或确定失败。
            }
            if (result.getRejected() > 0) {
                // 接入宿主的脱敏告警；本次关闭中有事件被拒绝。
            }
        } catch (Exception ignored) {
            // 记录脱敏关闭状态，不输出原始事件、凭据或异常内容。
        }
    }
}

示例使用合成测试事件。正式接入时按业务定义替换事件名与属性；authenticatedUserId 来自宿主认证结果，不能直接信任客户端 Header 或请求字段。

track() 的布尔结果只表示 SDK 是否接纳本次调用，不表示已经上传或 Collector 已确认。默认队列是有界内存队列，不能作为业务事务 Outbox 或崩溃恢复保证。交易等必须与业务事务一致的事件，按宿主事务 Outbox设计。

默认队列最多容纳 1000 条事件，SDK 每 5 秒调度一次后台发送，达到 100 条时也会唤醒发送；发送间隔不是送达时限。队列已满时新事件无法入队，应关注返回值和队列满计数。

3. 关闭并验证接收

在宿主已有的关闭钩子中调用 AnalyticsEvents.close()：先停止接收新请求并等待在途处理，再有界关闭 SDK。不要在每个请求或循环中调用 flush()。

在开发部署环境使用测试项目和合成账号触发业务路径，通过该环境授权的查询或诊断核对接收记录。close() 超时或返回未决事件时，按未确认处理。验证边界见数据校验。

关闭结果只反映本次关闭处理的事件；运行期间也应关注累计诊断，以发现此前后台发送的失败或拒绝。

请求作用域与停机顺序

一个项目的 Client 可由多个请求复用，但用户身份必须在每次调用时显式传入。若使用 RequestContextScope，在处理请求的同一线程内用 try-with-resources 打开与关闭作用域；线程池复用前必须清理。该作用域不会自动传播到异步任务或 Servlet async dispatch，需要宿主显式传递并重新打开。

停机时先停止接纳新请求/任务并等待已有处理，再停止领取新的 Outbox 记录，最后调用带预算的 close(timeoutMs)。Java 关闭可能抛出 TimeoutException；记录脱敏状态并按未确认处理，不能因为关闭钩子已执行就报告全部送达。不要在等待超时后立即关闭 File Store、删除锁或启动替代 owner；先确认旧网络操作结束或原进程退出。内存队列不提供强杀恢复保证。

事务事件的提交未知与租约处理见Java 宿主事务 Outbox。

可选框架模块

Spring 宿主复用 Core

Spring 应用可以直接用 Core 声明项目级单例，无须安装 Starter。以下示例假设应用已经配置 tracking.endpoint 和 tracking.project-key：

java

import com.trackbusiness.server.ServerClient;
import org.springframework.beans.factory.DisposableBean;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
class AnalyticsConfiguration {
    @Bean(destroyMethod = "")
    ServerClient analyticsClient(@Value("${tracking.endpoint}") String endpoint,
                                 @Value("${tracking.project-key}") String projectKey) throws Exception {
        return ServerClient.builder(endpoint, projectKey).build();
    }

    @Bean
    DisposableBean analyticsShutdown(ServerClient analyticsClient) {
        return () -> {
            try {
                com.trackbusiness.server.model.FlushResult result = analyticsClient.close(5000);
                if (result.getUnresolved() > 0 || result.getRejected() > 0) {
                    // 增加脱敏的未确认或拒绝事件告警。
                }
            } catch (Exception ignored) {
                // 记录关闭未完成；不要输出原始异常、凭据或事件内容。
            }
        };
    }
}

在宿主已有停机流程中先停止接收新请求并等待在途业务结束，再销毁 Spring 容器；关闭超时或未决不表示送达。

Spring Boot Starter 与 Servlet Filter 当前没有独立 Maven 发布包，不要为它们填写未发布的依赖坐标。若你的交付包含框架适配模块，应按该交付包附带的说明显式配置和注册；身份仍须来自宿主认证结果，不能由 SDK 从请求 Header 推断。

更多投递模式、身份边界、日志和诊断信息见服务端 SDK 概览。

Java SDK ​

1. 安装 ​

2. 初始化并记录首个事件 ​

3. 关闭并验证接收 ​

请求作用域与停机顺序 ​

可选框架模块 ​

Spring 宿主复用 Core ​