diff --git a/core/src/main/java/common/ecommerce/idempotency/IdempotencyGuard.java b/core/src/main/java/common/ecommerce/idempotency/IdempotencyGuard.java index 71a877d..d84eb4b 100644 --- a/core/src/main/java/common/ecommerce/idempotency/IdempotencyGuard.java +++ b/core/src/main/java/common/ecommerce/idempotency/IdempotencyGuard.java @@ -12,7 +12,6 @@ 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; @@ -116,13 +115,10 @@ public final class IdempotencyGuard { // 2) provider 键:识别「平台已写、业务键没来得及记成功」的崩溃窗口 IdempotencyClaim provider = store.claim(providerKey, owner, scope.provider(), now, claimTtlSeconds); if (!provider.acquired()) { - Map 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, - WriteAudit.Stage.REPAIRED_FROM_PROVIDER_KEY, providerOutcome); + WriteAudit.Stage.REPAIRED_FROM_PROVIDER_KEY); } boolean retryable = provider.outcome() != IdempotencyClaim.Outcome.FAILED_FINAL; store.fail(businessKey, owner, retryable, Instant.now(clock)); @@ -137,9 +133,10 @@ 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)); + WriteAudit.Stage stage = retryable + ? WriteAudit.Stage.FAILED_RETRYABLE : WriteAudit.Stage.FAILED; + WriteAudit.record(observer, clock, scope, CallOutcome.FAILURE, stage, e, + "retryable", retryable); throw e; } @@ -148,7 +145,7 @@ public final class IdempotencyGuard { 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)); + "resultRef", ref); return WriteResult.executed(value, ref, businessKey, providerKey); } @@ -160,7 +157,7 @@ public final class IdempotencyGuard { switch (claim.outcome()) { case SUCCEEDED: return replay(scope, record, businessKey, providerKey, - WriteAudit.Stage.ALREADY_COMPLETED, null); + WriteAudit.Stage.ALREADY_COMPLETED); case IN_PROGRESS: { IdempotencyConflictException ex = new IdempotencyConflictException(ChannelException.builder() .message("write already in progress: " + providerKey) @@ -169,8 +166,7 @@ public final class IdempotencyGuard { .omsStoreId(scope.omsStoreId()) .platform(scope.platform()), businessKey); WriteAudit.record(observer, clock, scope, CallOutcome.FAILURE, - WriteAudit.Stage.IN_PROGRESS, ex, WriteAudit.params(scope, - WriteAudit.Stage.IN_PROGRESS, "owner", record.owner())); + WriteAudit.Stage.IN_PROGRESS, ex, "owner", record.owner()); throw ex; } case FAILED_FINAL: { @@ -183,8 +179,7 @@ public final class IdempotencyGuard { .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())); + WriteAudit.Stage.FAILED_FINAL, ex, "owner", record.owner()); throw ex; } default: @@ -194,7 +189,7 @@ public final class IdempotencyGuard { private WriteResult replay(WriteScope scope, IdempotencyRecord record, String businessKey, String providerKey, - WriteAudit.Stage stage, Map extra) { + WriteAudit.Stage stage) { if (record.provider() != null && record.provider() != scope.provider()) { CrossProviderConflictException ex = new CrossProviderConflictException(ChannelException.builder() .message("business action already completed by " + record.provider() @@ -205,14 +200,12 @@ public final class IdempotencyGuard { .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())); + WriteAudit.Stage.CROSS_PROVIDER_CONFLICT, ex, + "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())); + "resultRef", record.resultRef()); return WriteResult.alreadyCompleted(record.resultRef(), businessKey, providerKey); } diff --git a/core/src/main/java/common/ecommerce/idempotency/WriteAudit.java b/core/src/main/java/common/ecommerce/idempotency/WriteAudit.java index 33424e9..29d598b 100644 --- a/core/src/main/java/common/ecommerce/idempotency/WriteAudit.java +++ b/core/src/main/java/common/ecommerce/idempotency/WriteAudit.java @@ -43,15 +43,35 @@ final class WriteAudit { /** * 记录一次幂等裁决。 * - * @param observer 观察者;null 等价于 NOOP - * @param scope 标识维度 - * @param outcome {@link #OPERATION_PREFIX} 语义下的结论:成功 / 回放 / 失败 - * @param stage 守卫阶段,见 {@link Stage} - * @param error 失败时的异常,成功为 null - * @param extra 额外摘要(如 {@code providerOutcome}),可为 null + *

参数分为「固定字段」和「额外摘要」两部分:{@code businessKey} / + * {@code providerKey} / {@code stage} 由 {@code scope} 与本方法的 {@code stage} + * 决定,调用方只在 {@code extraKey} / {@code extraValue} 里补充别的字段。 + * 这样记录里的 stage 与 {@code outcome} 永远出自同一次调用,不会错位。

+ * + *

参数拼装在 try 之外:调用方传错属于代码缺陷,必须当场暴露; + * 只有「观察者自身抛异常」才允许被吞掉。

+ * + * @param observer 观察者;null 等价于 NOOP + * @param scope 标识维度 + * @param outcome 结论 + * @param stage 守卫阶段 + * @param error 失败时的异常,成功为 null + * @param extraKey 额外摘要的键(如 {@code resultRef} / {@code retryable}),可为 null + * @param extraValue 额外摘要的值 */ static void record(CallObserver observer, Clock clock, WriteScope scope, CallOutcome outcome, - Stage stage, RuntimeException error, Map extra) { + Stage stage, RuntimeException error, String extraKey, Object extraValue) { + Map auditParams = base(scope, stage); + if (extraKey != null) { + if ("businessKey".equals(extraKey) || "providerKey".equals(extraKey) || "stage".equals(extraKey)) { + // 这三个字段只由 scope 与 stage 决定;允许调用方覆盖会让审计记录 + // 与实际裁决脱节(曾出现 CLAIMED 冒充 REPAIRED_FROM_PROVIDER_KEY) + throw new IllegalArgumentException( + "extra key '" + extraKey + "' is derived from scope and stage"); + } + auditParams.put(extraKey, extraValue); + } + CallObserver effective = observer == null ? CallObserver.NOOP : observer; try { Instant now = Instant.now(clock); @@ -63,7 +83,7 @@ final class WriteAudit { .operation(operation(scope)) .outcome(outcome) .failedCount(outcome == CallOutcome.SUCCESS ? 0 : 1) - .params(params(scope, stage, extra)) + .params(auditParams) .error(error); effective.onCall(record.build()); } catch (RuntimeException e) { @@ -72,27 +92,15 @@ final class WriteAudit { } } - /** 摘要:业务键 / provider 键 / 守卫阶段 / 额外信息。不放金额等业务明细。 */ - static Map params(WriteScope scope, Stage stage, Map extra) { + /** 三个固定字段:业务键、provider 键、守卫阶段。 */ + private static Map base(WriteScope scope, Stage stage) { Map map = new LinkedHashMap(); 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 params(WriteScope scope, Stage stage, String key, Object value) { - Map map = new LinkedHashMap(); - if (key != null) { - map.put(key, value); - } - return params(scope, stage, map); - } - /** 守卫阶段:从抢占到落库的每一步都有名字,便于按 stage 聚合。 */ enum Stage { /** 业务键已抢占,即将执行平台写。 */ diff --git a/core/src/main/java/common/ecommerce/sdk/ChannelContext.java b/core/src/main/java/common/ecommerce/sdk/ChannelContext.java index c3114b1..e11976d 100644 --- a/core/src/main/java/common/ecommerce/sdk/ChannelContext.java +++ b/core/src/main/java/common/ecommerce/sdk/ChannelContext.java @@ -39,6 +39,17 @@ public final class ChannelContext { } /** + * 有账户但没有连接的上下文:{@code capabilities} 这类不联网的调用用它埋点。 + * + *

{@link #connection()} 为 null,{@link #endpointBaseUrl()} / {@link #secret()} + * 会抛 {@link IllegalStateException}。适配器不能用它发请求。

+ */ + public static ChannelContext ofAccount(ChannelAccount account, String requestId, Clock clock) { + Objects.requireNonNull(account, "account"); + return new ChannelContext(null, account, null, requestId, clock); + } + + /** * 只带账户标识的上下文:账户没查到、或调用方没传连接时用于埋点。 * *

此时 {@link #account()}、{@link #connection()} 为 null,适配器不能用它发请求; @@ -86,13 +97,19 @@ public final class ChannelContext { return connection; } - /** 本次调用的目标基址。 */ + /** 本次调用的目标基址;没有连接时({@link #ofAccount})抛异常。 */ public String endpointBaseUrl() { + if (connection == null) { + throw new IllegalStateException("this call has no ChannelConnection"); + } return connection.endpointBaseUrl(); } - /** 本次调用的凭据,SDK 不落盘。 */ + /** 本次调用的凭据,SDK 不落盘;没有连接时({@link #ofAccount})抛异常。 */ public ChannelSecret secret() { + if (connection == null) { + throw new IllegalStateException("this call has no ChannelConnection"); + } return connection.secret(); } diff --git a/core/src/main/java/common/ecommerce/sdk/ChannelSdk.java b/core/src/main/java/common/ecommerce/sdk/ChannelSdk.java index ab0e4fc..c117e2e 100644 --- a/core/src/main/java/common/ecommerce/sdk/ChannelSdk.java +++ b/core/src/main/java/common/ecommerce/sdk/ChannelSdk.java @@ -316,7 +316,7 @@ public final class ChannelSdk implements ProviderResolver { Optional account = accountRepository.findByKey(key.provider().name(), key.platform().name(), key.omsStoreId()); return account.isPresent() - ? ChannelContext.of(account.get(), null, newRequestId(), clock) + ? ChannelContext.ofAccount(account.get(), newRequestId(), clock) : ChannelContext.ofKey(key, newRequestId(), clock); } diff --git a/core/src/test/java/common/ecommerce/idempotency/WriteAuditTest.java b/core/src/test/java/common/ecommerce/idempotency/WriteAuditTest.java index 7deca99..2b1565e 100644 --- a/core/src/test/java/common/ecommerce/idempotency/WriteAuditTest.java +++ b/core/src/test/java/common/ecommerce/idempotency/WriteAuditTest.java @@ -322,11 +322,25 @@ class WriteAuditTest { @Test void paramsCarryBothKeysAndStage() { - Map params = WriteAudit.params(SCOPE, WriteAudit.Stage.EXECUTED, - "resultRef", null); + guard.execute(SCOPE, () -> "SHIP-1", v -> v); + + Map params = observer.only().params(); assertEquals(SCOPE.businessKey(), params.get("businessKey")); assertEquals(SCOPE.providerKey(), params.get("providerKey")); assertEquals("EXECUTED", params.get("stage")); - assertTrue(params.containsKey("resultRef")); + assertEquals("SHIP-1", params.get("resultRef")); + } + + @Test + void extraKeyCannotOverrideDerivedFields() { + // businessKey / providerKey / stage 只由 scope 与 stage 决定, + // 调用方用额外字段覆盖属于代码缺陷,必须当场暴露 + assertThrows(IllegalArgumentException.class, () -> WriteAudit.record( + observer, CLOCK, SCOPE, CallOutcome.SUCCESS, WriteAudit.Stage.EXECUTED, + null, "stage", "CLAIMED")); + assertThrows(IllegalArgumentException.class, () -> WriteAudit.record( + observer, CLOCK, SCOPE, CallOutcome.SUCCESS, WriteAudit.Stage.EXECUTED, + null, "businessKey", "forged")); + assertEquals(0, observer.records.size(), "参数错误不应产生任何审计记录"); } } diff --git a/core/src/test/java/common/ecommerce/sdk/RequestIdAndCoverageTest.java b/core/src/test/java/common/ecommerce/sdk/RequestIdAndCoverageTest.java index ae826ab..d0d7bfa 100644 --- a/core/src/test/java/common/ecommerce/sdk/RequestIdAndCoverageTest.java +++ b/core/src/test/java/common/ecommerce/sdk/RequestIdAndCoverageTest.java @@ -120,7 +120,9 @@ class RequestIdAndCoverageTest { for (CallRecord record : observer.records) { ids.add(record.requestId()); } - assertEquals(4, ids.size(), "刷新后每条记录应有不同的 requestId"); + // 4 次调用:前两次共用 cached,后面两次各一个 → 共 3 个不同 ID + assertEquals(3, ids.size(), "刷新后新调用应有不同的 requestId"); + assertTrue(ids.contains(cached)); assertTrue(ids.contains("trace-1")); assertTrue(ids.contains("trace-2")); } @@ -205,9 +207,8 @@ class RequestIdAndCoverageTest { @Test void missingAdapterIsObservedAsFailure() { CollectingObserver observer = new CollectingObserver(); - ChannelSdk sdk = builder(observer).build(); - // 账户存在,但没有注册 LINGXING 的适配器 + // 账户存在,但没有注册 LINGXING 的适配器(只注册了 DIRECT) AccountKey lingxing = AccountKey.of(ChannelProvider.LINGXING, Platform.WALMART_SC, "oms-wm-001"); ChannelAccount lingxingAccount = ChannelAccount.builder() .key(lingxing) @@ -216,14 +217,14 @@ class RequestIdAndCoverageTest { .marketplaceZone("America/Chicago") .currency("USD") .build(); - ChannelSdk withLingxingAccount = ChannelSdk.builder() + ChannelSdk sdk = ChannelSdk.builder() .accountRepository(new ChannelSdkTest.FixedAccounts(lingxingAccount)) .clock(CLOCK) .register(new ChannelSdkTest.FakeDirectAdapter()) .callObserver(observer) .build(); - assertThrows(IllegalStateException.class, () -> withLingxingAccount.capabilities(lingxing)); + assertThrows(IllegalStateException.class, () -> sdk.capabilities(lingxing)); CallRecord record = observer.records.get(0); assertEquals(CallOutcome.FAILURE, record.outcome());