Java 上报方式

先在服务端 SDK 概览按事件风险选定路径，再使用本页的构造。安装、首条事件和 Spring 停机在Java 集成；track 与画像签名在Java 基础 API。

路径	构造	本页
默认批量	ServerClient.builder(endpoint, projectKey).build()	批量
日志交接	com.trackbusiness.server.consumer.LoggingConsumer	日志
同步直发	同包的 DirectConsumer，由 DirectConsumerOptions.builder(transport) 配置	直发
宿主事务 Outbox	宿主数据库与 Relay，不由 SDK 再构造一种 Client	Outbox

日志与直发示例展示低层 Consumer；普通业务埋点使用快速接入页的 ServerClient.track()。

默认批量

ServerClient.builder 不接收 Consumer，创建的就是有界内存队列和后台冲刷。初始化示例在集成页。

默认队列的进程退出风险见服务端 SDK 概览。需要与业务事务一起提交的事实使用宿主事务 Outbox。

日志交接

LoggingConsumer 将事件写入本地文件；文件格式、交接、磁盘预算和恢复规则见日志交接边界。

import com.trackbusiness.server.consumer.LoggingConsumer;
import com.trackbusiness.server.consumer.LoggingConsumerOptions;
import com.trackbusiness.server.consumer.LoggingSyncPolicy;

LoggingConsumer consumer = new LoggingConsumer(
    LoggingConsumerOptions.builder(java.nio.file.Paths.get("/var/log/track-business"), "1.0.0")
        .filePrefix("events")
        .maxFileBytes(64 * 1024 * 1024L)
        .maxTotalBytes(1024 * 1024 * 1024L)
        .syncPolicy(LoggingSyncPolicy.ON_FLUSH)
        .build());

consumer.accept(event);
consumer.close();

同步直发

DirectConsumer 使用宿主提供的 BatchTransport 发送事件。确认与重试语义见服务端 SDK 概览。

import com.trackbusiness.server.consumer.DirectConsumer;
import com.trackbusiness.server.consumer.DirectConsumerOptions;
import com.trackbusiness.server.consumer.DirectResult;

DirectConsumer direct = new DirectConsumer(DirectConsumerOptions.builder(transport).build());
DirectResult result = direct.accept(event);

返回的 DirectOutcome 只描述这一次响应：接受、拒绝或未决。超时和未完成是未知，不是成功。

宿主事务 Outbox

宿主事务 Outbox 由业务数据库事务和 Relay 实现；不要把同一事件同时送入默认队列。实现边界见服务端 SDK 概览。

业务写入与不可变事件记录必须使用同一个数据库事务；回滚时两者一起回滚。不要先提交订单，再调用 track()，并把这称为事务 Outbox。数据库迁移、事件完整序列化、租约、重试/死信与终态行保留均由宿主管理，SDK 不会自动安装数据库表或驱动。

接收端整批 ACK 与宿主终态提交是两个步骤。若接收端已接受但数据库提交报错或更新零行，Relay 报告提交未知并停止本次 drain。此时不能标记成功，也不能生成新的 eventId 作为补偿；按原记录、原 eventId 及稳定批次身份重试，并由 Collector 幂等处理。跨步骤不承诺 Exactly Once。

领取、续约、accepted/rejected 与 release 必须按记录 ID 和租约 token 限制，且终态/续约还须检查租约未过期；旧 owner 不能改变新 owner 的记录。租约使用数据库统一时间。慢发送需要续约时，宿主 Store 实现续约接口并显式配置间隔；间隔必须小于租约，留出数据库和网络抖动余量。续约失败时即使 HTTP 返回成功，也不能据此提交 accepted，已发出的请求不能靠本地取消撤回。

Java 使用 RenewableTransactionalOutboxStore 和 new OutboxRelay(store, direct, destination, leaseRenewalIntervalMs)。未配置第四个参数时不自动续约。捕获 OutboxRelayCommitUnknownException 后暂停本 Relay 的后续调度，交由宿主恢复策略处理；异常内容和事件值不要写入普通日志。Core 仍兼容 Java 8，不依赖 JDBC、Servlet 或 Spring。