Browse Source

feat(observability): 幂等层审计与每次调用独立 requestId

- IdempotencyGuard 注入 CallObserver,EXECUTED / 回放 / 崩溃窗口修复 / 并发冲突 /
  终态失败 / 跨 provider 冲突 / 可重试与不可重试失败全部留痕
- 新增 WriteAudit,操作名 writes.<action>,params 带 businessKey / providerKey / stage
- ChannelContext 增加 withRequestId / ofKey,门面各视图可刷新链路 ID
- ChannelSdk 增加 requestIdSupplier;capabilities 纳入埋点;build 时打启动自检日志
feature/supplier-lingxing
lml 2 weeks ago
parent
commit
e889cbc40f
  1. 9
      core/src/main/java/common/ecommerce/capability/AfterSales.java
  2. 9
      core/src/main/java/common/ecommerce/capability/Outbounds.java
  3. 9
      core/src/main/java/common/ecommerce/capability/Products.java
  4. 9
      core/src/main/java/common/ecommerce/capability/SalesOrders.java
  5. 9
      core/src/main/java/common/ecommerce/capability/Settlements.java
  6. 82
      core/src/main/java/common/ecommerce/idempotency/IdempotencyGuard.java
  7. 117
      core/src/main/java/common/ecommerce/idempotency/WriteAudit.java
  8. 2
      core/src/main/java/common/ecommerce/sdk/CallSupport.java
  9. 49
      core/src/main/java/common/ecommerce/sdk/ChannelContext.java
  10. 122
      core/src/main/java/common/ecommerce/sdk/ChannelSdk.java

9
core/src/main/java/common/ecommerce/capability/AfterSales.java

@ -32,6 +32,15 @@ public final class AfterSales { @@ -32,6 +32,15 @@ public final class AfterSales {
this.observer = observer == null ? CallObserver.NOOP : observer;
}
/**
* 换一个链路 ID 的副本,供缓存的视图对象在每次调用时刷新。
*
* @see ChannelContext#withRequestId(String)
*/
public AfterSales withRequestId(String requestId) {
return new AfterSales(adapter, account, ctx.withRequestId(requestId), observer);
}
public Page<AfterSale> pull(final AfterSaleQuery query) {
return CallSupport.observe(observer, ctx, "afterSales.pull",
CallSupport.params(

9
core/src/main/java/common/ecommerce/capability/Outbounds.java

@ -43,6 +43,15 @@ public final class Outbounds { @@ -43,6 +43,15 @@ public final class Outbounds {
this.observer = observer == null ? CallObserver.NOOP : observer;
}
/**
* 换一个链路 ID 的副本,供缓存的视图对象在每次调用时刷新。
*
* @see ChannelContext#withRequestId(String)
*/
public Outbounds withRequestId(String requestId) {
return new Outbounds(adapter, account, ctx.withRequestId(requestId), observer);
}
public boolean submit(final List<OutboundPackage> packages) {
return CallSupport.observeSummary(observer, ctx, "outbounds.submit",
CallSupport.params("packageCount", packages == null ? 0 : packages.size()),

9
core/src/main/java/common/ecommerce/capability/Products.java

@ -31,6 +31,15 @@ public final class Products { @@ -31,6 +31,15 @@ public final class Products {
this.observer = observer == null ? CallObserver.NOOP : observer;
}
/**
* 换一个链路 ID 的副本,供缓存的视图对象在每次调用时刷新。
*
* @see ChannelContext#withRequestId(String)
*/
public Products withRequestId(String requestId) {
return new Products(adapter, account, ctx.withRequestId(requestId), observer);
}
public Page<ProductListing> pull(final ProductQuery query) {
return CallSupport.observe(observer, ctx, "products.pull",
CallSupport.params(

9
core/src/main/java/common/ecommerce/capability/SalesOrders.java

@ -41,6 +41,15 @@ public final class SalesOrders { @@ -41,6 +41,15 @@ public final class SalesOrders {
this.observer = observer == null ? CallObserver.NOOP : observer;
}
/**
* 换一个链路 ID 的副本,供缓存的视图对象在每次调用时刷新。
*
* @see ChannelContext#withRequestId(String)
*/
public SalesOrders withRequestId(String requestId) {
return new SalesOrders(adapter, account, ctx.withRequestId(requestId), observer);
}
public Page<SalesOrder> pull(final SalesOrderQuery query) {
return CallSupport.observe(observer, ctx, "salesOrders.pull",
CallSupport.params(

9
core/src/main/java/common/ecommerce/capability/Settlements.java

@ -32,6 +32,15 @@ public final class Settlements { @@ -32,6 +32,15 @@ public final class Settlements {
this.observer = observer == null ? CallObserver.NOOP : observer;
}
/**
* 换一个链路 ID 的副本,供缓存的视图对象在每次调用时刷新。
*
* @see ChannelContext#withRequestId(String)
*/
public Settlements withRequestId(String requestId) {
return new Settlements(adapter, account, ctx.withRequestId(requestId), observer);
}
public Page<SettlementTransaction> pull(final SettlementQuery query) {
return CallSupport.observe(observer, ctx, "settlements.pull",
CallSupport.params(

82
core/src/main/java/common/ecommerce/idempotency/IdempotencyGuard.java

@ -1,5 +1,7 @@ @@ -1,5 +1,7 @@
package common.ecommerce.idempotency;
import common.ecommerce.audit.CallObserver;
import common.ecommerce.audit.CallOutcome;
import common.ecommerce.error.ChannelException;
import common.ecommerce.error.CrossProviderConflictException;
import common.ecommerce.error.IdempotencyConflictException;
@ -10,6 +12,7 @@ import common.ecommerce.spi.IdempotencyStore; @@ -10,6 +12,7 @@ import common.ecommerce.spi.IdempotencyStore;
import java.time.Clock;
import java.time.Instant;
import java.util.Map;
import java.util.Objects;
import java.util.Optional;
import java.util.UUID;
@ -36,6 +39,23 @@ import java.util.function.Supplier; @@ -36,6 +39,23 @@ import java.util.function.Supplier;
* </ul>
*
* <p>守卫不碰平台协议,也不自行重试;重试由宿主调度决定。</p>
*
* <h2>审计</h2>
*
* <p>注入 {@link CallObserver} 后,<b>每一次</b>裁决都会回调一条 {@code CallRecord},
* 操作名是 {@code writes.<action>},{@code params} 带 {@code businessKey} / {@code providerKey}
* / {@code stage}。覆盖的场景:</p>
*
* <ul>
* <li>{@code EXECUTED}——记 {@link CallOutcome#SUCCESS}(结论 SUCCESS)</li>
* <li>{@code ALREADY_COMPLETED} / {@code REPAIRED_FROM_PROVIDER_KEY}——回放,也是 SUCCESS</li>
* <li>{@code FAILED_RETRYABLE} / {@code FAILED}——记 {@link CallOutcome#FAILURE}</li>
* <li>{@code IN_PROGRESS} / {@code FAILED_FINAL} / {@code CROSS_PROVIDER_CONFLICT}——
* 抛异常的同时记 FAILURE,{@code params.stage} 区分具体原因</li>
* </ul>
*
* <p>幂等层不参与「业务失败但没抛异常」的判定:写方法必须先把这类结果
* 转成异常(见 {@code PlatformBusinessException}),否则这里仍然会记成功。</p>
*/
public final class IdempotencyGuard {
@ -45,12 +65,21 @@ public final class IdempotencyGuard { @@ -45,12 +65,21 @@ public final class IdempotencyGuard {
private final String owner;
private final Clock clock;
private final long claimTtlSeconds;
private final CallObserver observer;
public IdempotencyGuard(IdempotencyStore store, Clock clock) {
this(store, UUID.randomUUID().toString(), clock, DEFAULT_CLAIM_TTL_SECONDS);
}
public IdempotencyGuard(IdempotencyStore store, String owner, Clock clock, long claimTtlSeconds) {
this(store, owner, clock, claimTtlSeconds, CallObserver.NOOP);
}
/**
* @param observer 幂等层审计;null 等价于 {@link CallObserver#NOOP}
*/
public IdempotencyGuard(IdempotencyStore store, String owner, Clock clock, long claimTtlSeconds,
CallObserver observer) {
this.store = Objects.requireNonNull(store, "store");
this.owner = Objects.requireNonNull(owner, "owner");
this.clock = Objects.requireNonNull(clock, "clock");
@ -58,13 +87,15 @@ public final class IdempotencyGuard { @@ -58,13 +87,15 @@ public final class IdempotencyGuard {
throw new IllegalArgumentException("claimTtlSeconds must be positive");
}
this.claimTtlSeconds = claimTtlSeconds;
this.observer = observer == null ? CallObserver.NOOP : observer;
}
/**
* 执行一次写操作。
*
* @param scope 标识维度
* @param action 平台写操作;抛 {@link ChannelException} 时按其 {@code retryable()} 决定是否可重试
* @param action 平台写操作;抛 {@link ChannelException} 时按其 {@code retryable()} 决定是否可重试。
* <b>业务失败必须抛异常</b>,返回「失败结果」会被记成已成功
* @param resultRef 从执行结果中提取结果引用(订单号 / 包裹号等),可为 null
*/
public <T> WriteResult<T> execute(WriteScope scope, Supplier<T> action, Function<? super T, String> resultRef) {
@ -85,12 +116,16 @@ public final class IdempotencyGuard { @@ -85,12 +116,16 @@ public final class IdempotencyGuard {
// 2) provider 键:识别「平台已写、业务键没来得及记成功」的崩溃窗口
IdempotencyClaim provider = store.claim(providerKey, owner, scope.provider(), now, claimTtlSeconds);
if (!provider.acquired()) {
Map<String, Object> providerOutcome =
WriteAudit.params(scope, WriteAudit.Stage.CLAIMED, "providerOutcome",
String.valueOf(provider.outcome()));
if (provider.outcome() == IdempotencyClaim.Outcome.SUCCEEDED) {
store.complete(businessKey, owner, provider.record().resultRef(), Instant.now(clock));
return replay(scope, provider.record(), businessKey, providerKey);
return replay(scope, provider.record(), businessKey, providerKey,
WriteAudit.Stage.REPAIRED_FROM_PROVIDER_KEY, providerOutcome);
}
store.fail(businessKey, owner, provider.outcome() != IdempotencyClaim.Outcome.FAILED_FINAL,
Instant.now(clock));
boolean retryable = provider.outcome() != IdempotencyClaim.Outcome.FAILED_FINAL;
store.fail(businessKey, owner, retryable, Instant.now(clock));
return handleNotAcquired(scope, provider, businessKey, providerKey);
}
@ -102,6 +137,9 @@ public final class IdempotencyGuard { @@ -102,6 +137,9 @@ public final class IdempotencyGuard {
boolean retryable = isRetryable(e);
store.fail(providerKey, owner, retryable, Instant.now(clock));
store.fail(businessKey, owner, retryable, Instant.now(clock));
WriteAudit.record(observer, clock, scope, CallOutcome.FAILURE,
retryable ? WriteAudit.Stage.FAILED_RETRYABLE : WriteAudit.Stage.FAILED,
e, WriteAudit.params(scope, WriteAudit.Stage.FAILED, "retryable", retryable));
throw e;
}
@ -109,6 +147,8 @@ public final class IdempotencyGuard { @@ -109,6 +147,8 @@ public final class IdempotencyGuard {
String ref = resultRef.apply(value);
store.complete(providerKey, owner, ref, Instant.now(clock));
store.complete(businessKey, owner, ref, Instant.now(clock));
WriteAudit.record(observer, clock, scope, CallOutcome.SUCCESS, WriteAudit.Stage.EXECUTED, null,
WriteAudit.params(scope, WriteAudit.Stage.EXECUTED, "resultRef", ref));
return WriteResult.executed(value, ref, businessKey, providerKey);
}
@ -119,16 +159,22 @@ public final class IdempotencyGuard { @@ -119,16 +159,22 @@ public final class IdempotencyGuard {
IdempotencyRecord record = claim.record();
switch (claim.outcome()) {
case SUCCEEDED:
return replay(scope, record, businessKey, providerKey);
case IN_PROGRESS:
throw new IdempotencyConflictException(ChannelException.builder()
return replay(scope, record, businessKey, providerKey,
WriteAudit.Stage.ALREADY_COMPLETED, null);
case IN_PROGRESS: {
IdempotencyConflictException ex = new IdempotencyConflictException(ChannelException.builder()
.message("write already in progress: " + providerKey)
.operation(scope.action())
.provider(scope.provider().name())
.omsStoreId(scope.omsStoreId())
.platform(scope.platform()), businessKey);
case FAILED_FINAL:
throw ChannelException.builder()
WriteAudit.record(observer, clock, scope, CallOutcome.FAILURE,
WriteAudit.Stage.IN_PROGRESS, ex, WriteAudit.params(scope,
WriteAudit.Stage.IN_PROGRESS, "owner", record.owner()));
throw ex;
}
case FAILED_FINAL: {
ChannelException ex = ChannelException.builder()
.message("previous attempt failed permanently, manual intervention required: " + businessKey)
.operation(scope.action())
.provider(scope.provider().name())
@ -136,15 +182,21 @@ public final class IdempotencyGuard { @@ -136,15 +182,21 @@ public final class IdempotencyGuard {
.platform(scope.platform())
.retryable(false)
.build();
WriteAudit.record(observer, clock, scope, CallOutcome.FAILURE,
WriteAudit.Stage.FAILED_FINAL, ex, WriteAudit.params(scope,
WriteAudit.Stage.FAILED_FINAL, "owner", record.owner()));
throw ex;
}
default:
throw new IllegalStateException("unexpected claim outcome " + claim.outcome() + " for " + businessKey);
}
}
private <T> WriteResult<T> replay(WriteScope scope, IdempotencyRecord record,
String businessKey, String providerKey) {
String businessKey, String providerKey,
WriteAudit.Stage stage, Map<String, Object> extra) {
if (record.provider() != null && record.provider() != scope.provider()) {
throw new CrossProviderConflictException(ChannelException.builder()
CrossProviderConflictException ex = new CrossProviderConflictException(ChannelException.builder()
.message("business action already completed by " + record.provider()
+ ", requested via " + scope.provider() + ": " + businessKey)
.operation(scope.action())
@ -152,7 +204,15 @@ public final class IdempotencyGuard { @@ -152,7 +204,15 @@ public final class IdempotencyGuard {
.omsStoreId(scope.omsStoreId())
.platform(scope.platform())
.retryable(false), record.provider().name());
WriteAudit.record(observer, clock, scope, CallOutcome.FAILURE,
WriteAudit.Stage.CROSS_PROVIDER_CONFLICT, ex, WriteAudit.params(scope,
WriteAudit.Stage.CROSS_PROVIDER_CONFLICT,
"completedByProvider", record.provider().name()));
throw ex;
}
WriteAudit.record(observer, clock, scope, CallOutcome.SUCCESS, stage, null,
extra != null ? extra
: WriteAudit.params(scope, stage, "resultRef", record.resultRef()));
return WriteResult.alreadyCompleted(record.resultRef(), businessKey, providerKey);
}

117
core/src/main/java/common/ecommerce/idempotency/WriteAudit.java

@ -0,0 +1,117 @@ @@ -0,0 +1,117 @@
package common.ecommerce.idempotency;
import common.ecommerce.audit.CallObserver;
import common.ecommerce.audit.CallOutcome;
import common.ecommerce.audit.CallRecord;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import java.time.Clock;
import java.time.Instant;
import java.util.LinkedHashMap;
import java.util.Map;
/**
* 幂等守卫的埋点:把「抢占结果 + 平台写结果」拼成一条 {@link CallRecord}。
*
* <p>幂等层没有 {@code ChannelContext}(写操作可能先于取视图发生,也不一定绑定连接),
* 所以这里只用 {@link WriteScope} 拼出 provider / platform / omsStoreId,
* 不含 externalStoreId 与链路 requestId。</p>
*
* <p><b>约定</b>:观察者异常一律吞掉并打 WARN,绝不影响写操作本身;
* 与 {@code CallSupport} 保持一致。</p>
*/
final class WriteAudit {
private static final Logger LOG = LoggerFactory.getLogger(WriteAudit.class);
/**
* 操作名前缀。门面读操作是 {@code salesOrders.pull} 这类「能力.动作」,
* 幂等层统一挂 {@code writes.} 前缀,便于在审计里把「发起写」和
* 「幂等层裁决」两条记录对上。
*/
static final String OPERATION_PREFIX = "writes.";
private WriteAudit() {
}
/** 操作名:{@code writes.<scope.action()>}。 */
static String operation(WriteScope scope) {
return OPERATION_PREFIX + scope.action();
}
/**
* 记录一次幂等裁决。
*
* @param observer 观察者;null 等价于 NOOP
* @param scope 标识维度
* @param outcome {@link #OPERATION_PREFIX} 语义下的结论:成功 / 回放 / 失败
* @param stage 守卫阶段,见 {@link Stage}
* @param error 失败时的异常,成功为 null
* @param extra 额外摘要(如 {@code providerOutcome}),可为 null
*/
static void record(CallObserver observer, Clock clock, WriteScope scope, CallOutcome outcome,
Stage stage, RuntimeException error, Map<String, Object> extra) {
CallObserver effective = observer == null ? CallObserver.NOOP : observer;
try {
Instant now = Instant.now(clock);
CallRecord.Builder record = CallRecord.builder()
.occurredAt(now)
.provider(scope.provider())
.platform(scope.platform())
.omsStoreId(scope.omsStoreId())
.operation(operation(scope))
.outcome(outcome)
.failedCount(outcome == CallOutcome.SUCCESS ? 0 : 1)
.params(params(scope, stage, extra))
.error(error);
effective.onCall(record.build());
} catch (RuntimeException e) {
LOG.warn("idempotency audit observer failed, record dropped: op={} businessKey={}",
operation(scope), scope.businessKey(), e);
}
}
/** 摘要:业务键 / provider 键 / 守卫阶段 / 额外信息。不放金额等业务明细。 */
static Map<String, Object> params(WriteScope scope, Stage stage, Map<String, Object> extra) {
Map<String, Object> map = new LinkedHashMap<String, Object>();
map.put("businessKey", scope.businessKey());
map.put("providerKey", scope.providerKey());
map.put("stage", stage.name());
if (extra != null) {
map.putAll(extra);
}
return map;
}
/** 单键值摘要,避免调用处拼 map。 */
static Map<String, Object> params(WriteScope scope, Stage stage, String key, Object value) {
Map<String, Object> map = new LinkedHashMap<String, Object>();
if (key != null) {
map.put(key, value);
}
return params(scope, stage, map);
}
/** 守卫阶段:从抢占到落库的每一步都有名字,便于按 stage 聚合。 */
enum Stage {
/** 业务键已抢占,即将执行平台写。 */
CLAIMED,
/** 本次真正执行了平台写,两个键都记成功。 */
EXECUTED,
/** 业务动作此前已成功,本次回放,未调平台。 */
ALREADY_COMPLETED,
/** provider 键已完成但业务键没记上(崩溃窗口),补记后回放。 */
REPAIRED_FROM_PROVIDER_KEY,
/** 业务键被并发占用。 */
IN_PROGRESS,
/** 业务键处于终态失败,需人工介入。 */
FAILED_FINAL,
/** 业务动作已由另一个 provider 完成。 */
CROSS_PROVIDER_CONFLICT,
/** 平台写抛异常且可重试。 */
FAILED_RETRYABLE,
/** 平台写抛异常且不可重试,已记终态。 */
FAILED
}
}

2
core/src/main/java/common/ecommerce/sdk/CallSupport.java

@ -195,7 +195,7 @@ public final class CallSupport { @@ -195,7 +195,7 @@ public final class CallSupport {
.provider(ctx.provider())
.platform(ctx.platform())
.omsStoreId(ctx.omsStoreId())
.externalStoreId(ctx.account().externalStoreId())
.externalStoreId(ctx.account() == null ? null : ctx.account().externalStoreId())
.operation(operation)
.durationMillis(Math.max(0L, ctx.clock().millis() - startedMillis))
.params(params);

49
core/src/main/java/common/ecommerce/sdk/ChannelContext.java

@ -1,5 +1,6 @@ @@ -1,5 +1,6 @@
package common.ecommerce.sdk;
import common.ecommerce.model.account.AccountKey;
import common.ecommerce.model.account.ChannelAccount;
import common.ecommerce.model.ChannelProvider;
import common.ecommerce.model.Platform;
@ -15,37 +16,69 @@ import java.util.Objects; @@ -15,37 +16,69 @@ import java.util.Objects;
*/
public final class ChannelContext {
private final AccountKey key;
private final ChannelAccount account;
private final ChannelConnection connection;
private final String requestId;
private final Clock clock;
private ChannelContext(ChannelAccount account, ChannelConnection connection, String requestId, Clock clock) {
this.account = Objects.requireNonNull(account, "account");
this.connection = Objects.requireNonNull(connection, "connection");
private ChannelContext(AccountKey key, ChannelAccount account, ChannelConnection connection,
String requestId, Clock clock) {
this.key = key != null ? key : account.key();
this.account = account;
this.connection = connection;
this.requestId = requestId;
this.clock = Objects.requireNonNull(clock, "clock");
}
public static ChannelContext of(ChannelAccount account, ChannelConnection connection,
String requestId, Clock clock) {
return new ChannelContext(account, connection, requestId, clock);
Objects.requireNonNull(account, "account");
Objects.requireNonNull(connection, "connection");
return new ChannelContext(null, account, connection, requestId, clock);
}
/**
* 只带账户标识的上下文:账户没查到、或调用方没传连接时用于埋点。
*
* <p>此时 {@link #account()}、{@link #connection()} 为 null,适配器不能用它发请求;
* 只允许 {@code CallSupport} 读取 {@link #requestId()} 与账户维度。</p>
*/
public static ChannelContext ofKey(AccountKey key, String requestId, Clock clock) {
return new ChannelContext(Objects.requireNonNull(key, "key"), null, null, requestId, clock);
}
/**
* 复制一份上下文,只替换链路 ID。
*
* <p>门面对象({@code sdk.salesOrders(key, conn)})会持有取视图时的上下文;
* 宿主若缓存门面对象反复调用,就需要在每次方法调用时用本方法换一个新 ID,
* 否则多次调用共用同一个 {@link #requestId()},日志与审计无法按次区分。</p>
*/
public ChannelContext withRequestId(String requestId) {
return new ChannelContext(key, account, connection, requestId, clock);
}
/** 账户标识;即使账户没查到也有值。 */
public AccountKey key() {
return key;
}
/** 账户配置;{@link #ofKey} 构造时为 null。 */
public ChannelAccount account() {
return account;
}
public String omsStoreId() {
return account.omsStoreId();
return key.omsStoreId();
}
public Platform platform() {
return account.platform();
return key.platform();
}
public ChannelProvider provider() {
return account.provider();
return key.provider();
}
/** 本次调用的连接信息,由调用方传入。 */
@ -63,7 +96,7 @@ public final class ChannelContext { @@ -63,7 +96,7 @@ public final class ChannelContext {
return connection.secret();
}
/** 链路 ID,用于日志与原始报文关联。 */
/** 链路 ID,用于日志与原始报文关联;每次门面调用一个,可用 {@link #withRequestId(String)} 替换。 */
public String requestId() {
return requestId;
}

122
core/src/main/java/common/ecommerce/sdk/ChannelSdk.java

@ -2,6 +2,7 @@ package common.ecommerce.sdk; @@ -2,6 +2,7 @@ package common.ecommerce.sdk;
import common.ecommerce.model.Platform;
import common.ecommerce.audit.CallObserver;
import common.ecommerce.audit.Slf4jCallObserver;
import common.ecommerce.capability.AdapterCapabilityReport;
import common.ecommerce.capability.AfterSales;
import common.ecommerce.capability.AggregatorCapable;
@ -19,6 +20,8 @@ import common.ecommerce.model.account.ChannelAccount; @@ -19,6 +20,8 @@ import common.ecommerce.model.account.ChannelAccount;
import common.ecommerce.spi.ChannelAccountRepository;
import common.ecommerce.sdk.AdapterFactory.AdapterConfig;
import common.ecommerce.spi.IdempotencyStore;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import java.time.Clock;
import java.util.ArrayList;
@ -28,7 +31,9 @@ import java.util.LinkedHashMap; @@ -28,7 +31,9 @@ import java.util.LinkedHashMap;
import java.util.List;
import java.util.Map;
import java.util.Objects;
import java.util.Optional;
import java.util.UUID;
import java.util.function.Supplier;
/**
* 渠道 SDK 统一门面。业务层只依赖本类。
@ -60,6 +65,8 @@ import java.util.UUID; @@ -60,6 +65,8 @@ import java.util.UUID;
*/
public final class ChannelSdk implements ProviderResolver {
private static final Logger LOG = LoggerFactory.getLogger(ChannelSdk.class);
/**
* 已注册的适配器。
*
@ -95,14 +102,23 @@ public final class ChannelSdk implements ProviderResolver { @@ -95,14 +102,23 @@ public final class ChannelSdk implements ProviderResolver {
*/
private final CallObserver callObserver;
/**
* 链路 ID 生成器。
*
* <p>每次 {@code newContext(...)} 调用一次;宿主可以用它把 traceId
* 写进 SDK 的 {@code requestId},从而和自己日志对上。缺省随机 UUID。</p>
*/
private final Supplier<String> requestIdSupplier;
private ChannelSdk(Builder b) {
this.adapters = Collections.unmodifiableMap(new LinkedHashMap<String, PlatformAdapter>(b.adapters));
this.accountRepository = b.accountRepository;
this.clock = b.clock;
this.callObserver = b.callObserver == null ? CallObserver.NOOP : b.callObserver;
this.requestIdSupplier = b.requestIdSupplier;
this.idempotencyGuard = b.idempotencyStore == null ? null
: new IdempotencyGuard(b.idempotencyStore, b.idempotencyOwner, b.clock,
IdempotencyGuard.DEFAULT_CLAIM_TTL_SECONDS);
this.callObserver = b.callObserver == null ? CallObserver.NOOP : b.callObserver;
IdempotencyGuard.DEFAULT_CLAIM_TTL_SECONDS, callObserver);
}
public static Builder builder() {
@ -117,10 +133,21 @@ public final class ChannelSdk implements ProviderResolver { @@ -117,10 +133,21 @@ public final class ChannelSdk implements ProviderResolver {
* <p>只读,不触发任何真实 API。聚合器(如领星)会按子平台细化,
* 例如领星下 eBay 只有订单、沃尔玛有订单和商品。</p>
*
* <p>注入 {@code callObserver} 后,每次调用也会记一条 {@code capabilities} 记录;
* 账户或适配器没配好时记 FAILURE,这是上线初期最常见的配置类故障。</p>
*
* @param key 账户标识;账户未配置时抛 {@link IllegalStateException}
* @throws IllegalStateException 账户未配置,或该 provider+platform 没有适配器
*/
public CapabilityReport capabilities(AccountKey key) {
// 账户都不在时没有 ChannelContext,用 key 自己拼一个最小上下文
return CallSupport.observe(callObserver, contextFor(key), "capabilities",
CallSupport.params("capabilities", null),
report -> CallSupport.NO_COUNT,
() -> capabilitiesOf(key));
}
private CapabilityReport capabilitiesOf(AccountKey key) {
ChannelAccount account = requireAccount(key);
return new AdapterCapabilityReport(resolve(key), account);
}
@ -195,6 +222,51 @@ public final class ChannelSdk implements ProviderResolver { @@ -195,6 +222,51 @@ public final class ChannelSdk implements ProviderResolver {
});
}
/** 生成一次调用使用的链路 ID。 */
private String newRequestId() {
String id = requestIdSupplier.get();
if (id == null || id.trim().isEmpty()) {
throw new IllegalStateException("requestIdSupplier returned blank id");
}
return id;
}
/**
* 启动自检:只打一次 INFO,说明装配了什么。
*
* <p>「日志怎么没出来」时先看这一行——没 observer、observer 类型不对、
* 时区是容器默认 UTC,都能在这里看到。</p>
*/
private void logStartup() {
if (!LOG.isInfoEnabled()) {
return;
}
StringBuilder providers = new StringBuilder();
for (String key : adapters.keySet()) {
if (providers.length() > 0) {
providers.append(',');
}
providers.append(key);
}
LOG.info("channel-sdk initialized adapters={} observer={} zone={} requestIdSupplier={} "
+ "idempotency={} clock={}",
providers, describeObserver(), describeZone(), requestIdSupplier.getClass().getName(),
idempotencyGuard != null, clock.getClass().getSimpleName());
}
private String describeObserver() {
if (callObserver == CallObserver.NOOP) {
return "NOOP(no call log; set Builder.callObserver(...) to enable)";
}
return callObserver.getClass().getName();
}
/** 宿主时区只对 {@link Slf4jCallObserver} 有意义;其它实现由宿主自己决定。 */
private String describeZone() {
return callObserver instanceof Slf4jCallObserver
? ((Slf4jCallObserver) callObserver).zone().getId() : "n/a";
}
/**
* 写操作幂等守卫(业务键 + provider 请求键双锁)。
*
@ -233,7 +305,19 @@ public final class ChannelSdk implements ProviderResolver { @@ -233,7 +305,19 @@ public final class ChannelSdk implements ProviderResolver {
/** 组装单次调用的上下文:账户 + 连接 + 链路 ID + 时钟。 */
private ChannelContext newContext(ChannelAccount account, ChannelConnection connection) {
return ChannelContext.of(account, connection, UUID.randomUUID().toString(), clock);
return ChannelContext.of(account, connection, newRequestId(), clock);
}
/**
* 没有账户也要能埋点的调用({@code capabilities}):成功路径能拿到真实账户,
* 账户缺失时用 {@link ChannelContext#ofKey} 记一条失败记录,而不是什么都没留。
*/
private ChannelContext contextFor(AccountKey key) {
Optional<ChannelAccount> account =
accountRepository.findByKey(key.provider().name(), key.platform().name(), key.omsStoreId());
return account.isPresent()
? ChannelContext.of(account.get(), null, newRequestId(), clock)
: ChannelContext.ofKey(key, newRequestId(), clock);
}
/** 注册维度:provider + platform。同一组合下只能有一个适配器。 */
@ -268,6 +352,20 @@ public final class ChannelSdk implements ProviderResolver { @@ -268,6 +352,20 @@ public final class ChannelSdk implements ProviderResolver {
/** 调用观察者,默认不记录。 */
private CallObserver callObserver = CallObserver.NOOP;
/**
* 链路 ID 生成器,缺省随机 UUID。
*
* <p>返回 null / 空串会直接失败,避免静默产生一串空 requestId。</p>
*/
private Supplier<String> requestIdSupplier = DEFAULT_REQUEST_ID_SUPPLIER;
private static final Supplier<String> DEFAULT_REQUEST_ID_SUPPLIER = new Supplier<String>() {
@Override
public String get() {
return UUID.randomUUID().toString();
}
};
/** 时钟,默认 UTC;测试注入固定时钟。 */
private Clock clock = Clock.systemUTC();
@ -327,6 +425,20 @@ public final class ChannelSdk implements ProviderResolver { @@ -327,6 +425,20 @@ public final class ChannelSdk implements ProviderResolver {
}
/**
* 注入链路 ID 生成器,缺省 {@code UUID.randomUUID()}。
*
* <p>宿主已经有 traceId / MDC 时,用
* {@code requestIdSupplier(() -> MDC.get("traceId"))} 让 SDK 的
* {@code CallRecord.requestId()}、平台请求头与自身日志天然对齐。
* 生成器必须是纯函数式的轻量调用:它在<b>每次取视图</b>时同步执行,
* 抛异常会让门面调用失败。</p>
*/
public Builder requestIdSupplier(Supplier<String> requestIdSupplier) {
this.requestIdSupplier = Objects.requireNonNull(requestIdSupplier, "requestIdSupplier");
return this;
}
/**
* 注册适配器工厂。
*
* <p>生产推荐这种写法:工厂在 {@link #build()} 时调用 {@code create(...)},
@ -384,7 +496,9 @@ public final class ChannelSdk implements ProviderResolver { @@ -384,7 +496,9 @@ public final class ChannelSdk implements ProviderResolver {
for (AdapterFactory factory : factories) {
register(factory.create(AdapterConfig.NONE));
}
return new ChannelSdk(this);
ChannelSdk sdk = new ChannelSdk(this);
sdk.logStartup();
return sdk;
}
/** 注册单个适配器,键为 provider|platform;重复注册不同实例直接失败。 */

Loading…
Cancel
Save