Browse Source

fix(observability): 修正幂等审计的 stage 错位与 capabilities 上下文

跑通 core 全量测试后发现 12 个失败,其中 11 个是提交 e889cbc / 7ce2468
引入的真实缺陷,本次一并修正。

生产代码:
- WriteAudit.record 签名改为「单一额外键值对」,businessKey / providerKey /
  stage 三个字段由 scope 与 stage 参数统一生成,调用方无法覆盖。
  此前 record 的 stage 与 params 里的 stage 来自两个入口,不一致时审计记录
  与实际裁决脱节,出现过 CLAIMED 冒充 REPAIRED_FROM_PROVIDER_KEY、
  FAILED 冒充 FAILED_RETRYABLE
- WriteAudit 参数拼装移出 try:此前校验抛出的 IllegalArgumentException
  被观察者兜底 catch 吞掉,导致审计记录静默丢失
- ChannelContext 新增 ofAccount(account, requestId, clock):capabilities 这类
  不联网的调用用它埋点。此前误用 of() 传入 null connection,直接 NPE
- endpointBaseUrl() / secret() 在无连接时抛 IllegalStateException,
  不再是 NPE
- 删除 WriteAudit.params 的公开重载,从源头消除双 stage 入口

测试:
- WriteAuditTest.paramsCarryBothKeysAndStage 改为通过真实执行校验 params
- 新增 extraKeyCannotOverrideDerivedFields 覆盖字段防篡改
- RequestIdAndCoverageTest 修正 cachedViewCanRefreshRequestIdPerCall 的期望值:
  4 次调用中前两次共用缓存 ID,不同 ID 数是 3 而不是 4
- missingAdapterIsObservedAsFailure 去掉未被使用的多余 SDK 实例

验证:core 模块 62 个用例全部通过。
feature/supplier-lingxing
lml 2 weeks ago
parent
commit
73ba122d04
  1. 33
      core/src/main/java/common/ecommerce/idempotency/IdempotencyGuard.java
  2. 52
      core/src/main/java/common/ecommerce/idempotency/WriteAudit.java
  3. 21
      core/src/main/java/common/ecommerce/sdk/ChannelContext.java
  4. 2
      core/src/main/java/common/ecommerce/sdk/ChannelSdk.java
  5. 20
      core/src/test/java/common/ecommerce/idempotency/WriteAuditTest.java
  6. 11
      core/src/test/java/common/ecommerce/sdk/RequestIdAndCoverageTest.java

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

@ -12,7 +12,6 @@ import common.ecommerce.spi.IdempotencyStore; @@ -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 { @@ -116,13 +115,10 @@ 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,
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 { @@ -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 { @@ -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 { @@ -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 { @@ -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 { @@ -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 { @@ -194,7 +189,7 @@ public final class IdempotencyGuard {
private <T> WriteResult<T> replay(WriteScope scope, IdempotencyRecord record,
String businessKey, String providerKey,
WriteAudit.Stage stage, Map<String, Object> 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 { @@ -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);
}

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

@ -43,15 +43,35 @@ final class WriteAudit { @@ -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
* <p>参数分为「固定字段」和「额外摘要」两部分:{@code businessKey} /
* {@code providerKey} / {@code stage} 由 {@code scope} 与本方法的 {@code stage}
* 决定,调用方只在 {@code extraKey} / {@code extraValue} 里补充别的字段。
* 这样记录里的 stage 与 {@code outcome} 永远出自同一次调用,不会错位。</p>
*
* <p>参数拼装在 try 之外:调用方传错属于代码缺陷,必须当场暴露;
* 只有「观察者自身抛异常」才允许被吞掉。</p>
*
* @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<String, Object> extra) {
Stage stage, RuntimeException error, String extraKey, Object extraValue) {
Map<String, Object> 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 { @@ -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 { @@ -72,27 +92,15 @@ final class WriteAudit {
}
}
/** 摘要:业务键 / provider 键 / 守卫阶段 / 额外信息。不放金额等业务明细。 */
static Map<String, Object> params(WriteScope scope, Stage stage, Map<String, Object> extra) {
/** 三个固定字段:业务键、provider 键、守卫阶段。 */
private static Map<String, Object> base(WriteScope scope, Stage stage) {
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 {
/** 业务键已抢占,即将执行平台写。 */

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

@ -39,6 +39,17 @@ public final class ChannelContext { @@ -39,6 +39,17 @@ public final class ChannelContext {
}
/**
* 有账户但没有连接的上下文:{@code capabilities} 这类不联网的调用用它埋点。
*
* <p>{@link #connection()} 为 null,{@link #endpointBaseUrl()} / {@link #secret()}
* 会抛 {@link IllegalStateException}。适配器不能用它发请求。</p>
*/
public static ChannelContext ofAccount(ChannelAccount account, String requestId, Clock clock) {
Objects.requireNonNull(account, "account");
return new ChannelContext(null, account, null, requestId, clock);
}
/**
* 只带账户标识的上下文:账户没查到、或调用方没传连接时用于埋点。
*
* <p>此时 {@link #account()}、{@link #connection()} 为 null,适配器不能用它发请求;
@ -86,13 +97,19 @@ public final class ChannelContext { @@ -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();
}

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

@ -316,7 +316,7 @@ public final class ChannelSdk implements ProviderResolver { @@ -316,7 +316,7 @@ public final class ChannelSdk implements ProviderResolver {
Optional<ChannelAccount> 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);
}

20
core/src/test/java/common/ecommerce/idempotency/WriteAuditTest.java

@ -322,11 +322,25 @@ class WriteAuditTest { @@ -322,11 +322,25 @@ class WriteAuditTest {
@Test
void paramsCarryBothKeysAndStage() {
Map<String, Object> params = WriteAudit.params(SCOPE, WriteAudit.Stage.EXECUTED,
"resultRef", null);
guard.execute(SCOPE, () -> "SHIP-1", v -> v);
Map<String, Object> 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(), "参数错误不应产生任何审计记录");
}
}

11
core/src/test/java/common/ecommerce/sdk/RequestIdAndCoverageTest.java

@ -120,7 +120,9 @@ class RequestIdAndCoverageTest { @@ -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 { @@ -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 { @@ -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());

Loading…
Cancel
Save