From a6f3b3060fcbb4847d62f92d60819bb69868f009 Mon Sep 17 00:00:00 2001 From: chenchuchuan <13554600537@163.com> Date: Fri, 30 Oct 2026 14:20:37 +0800 Subject: [PATCH] =?UTF-8?q?feat(core):=20=E5=86=99=E6=93=8D=E4=BD=9C?= =?UTF-8?q?=E5=B9=82=E7=AD=89=E5=AE=88=E5=8D=AB=E4=B8=8E=20IdempotencyStor?= =?UTF-8?q?e=20SPI?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 业务键 + provider 请求键双锁:业务键不带 provider,直连与聚合器共用; provider 键只防单 provider 内重试。 - 新增 idempotency 包:WriteScope / WriteResult / IdempotencyGuard - 新增 SPI:IdempotencyStore 及 Claim / Record / Status 四态 - ChannelSdk.writes() 装配守卫;未注入 store 时显式失败,无降级路径 - 崩溃窗口由 provider 键恢复:平台已写但业务键未记成功时回放,不重复写 - testkit 新增 InMemoryIdempotencyStore / MutableClock,junit 改为 test 作用域 Co-Authored-By: Claude --- .../ecommerce/idempotency/IdempotencyGuard.java | 182 ++++++++++++++++++ .../common/ecommerce/idempotency/WriteResult.java | 71 +++++++ .../common/ecommerce/idempotency/WriteScope.java | 92 +++++++++ .../main/java/common/ecommerce/sdk/ChannelSdk.java | 36 +++- .../common/ecommerce/spi/IdempotencyClaim.java | 57 ++++++ .../common/ecommerce/spi/IdempotencyRecord.java | 69 +++++++ .../common/ecommerce/spi/IdempotencyStatus.java | 18 ++ .../common/ecommerce/spi/IdempotencyStore.java | 34 ++++ .../java/common/ecommerce/sdk/ChannelSdkTest.java | 69 ++++++- testkit/pom.xml | 1 + .../testkit/InMemoryIdempotencyStore.java | 116 +++++++++++ .../common/ecommerce/testkit/MutableClock.java | 49 +++++ .../idempotency/IdempotencyGuardTest.java | 212 +++++++++++++++++++++ 13 files changed, 1003 insertions(+), 3 deletions(-) create mode 100644 core/src/main/java/common/ecommerce/idempotency/IdempotencyGuard.java create mode 100644 core/src/main/java/common/ecommerce/idempotency/WriteResult.java create mode 100644 core/src/main/java/common/ecommerce/idempotency/WriteScope.java create mode 100644 core/src/main/java/common/ecommerce/spi/IdempotencyClaim.java create mode 100644 core/src/main/java/common/ecommerce/spi/IdempotencyRecord.java create mode 100644 core/src/main/java/common/ecommerce/spi/IdempotencyStatus.java create mode 100644 core/src/main/java/common/ecommerce/spi/IdempotencyStore.java create mode 100644 testkit/src/main/java/common/ecommerce/testkit/InMemoryIdempotencyStore.java create mode 100644 testkit/src/main/java/common/ecommerce/testkit/MutableClock.java create mode 100644 testkit/src/test/java/common/ecommerce/idempotency/IdempotencyGuardTest.java diff --git a/core/src/main/java/common/ecommerce/idempotency/IdempotencyGuard.java b/core/src/main/java/common/ecommerce/idempotency/IdempotencyGuard.java new file mode 100644 index 0000000..cba4218 --- /dev/null +++ b/core/src/main/java/common/ecommerce/idempotency/IdempotencyGuard.java @@ -0,0 +1,182 @@ +package common.ecommerce.idempotency; + +import common.ecommerce.error.ChannelException; +import common.ecommerce.error.CrossProviderConflictException; +import common.ecommerce.error.IdempotencyConflictException; +import common.ecommerce.spi.IdempotencyClaim; +import common.ecommerce.spi.IdempotencyRecord; +import common.ecommerce.spi.IdempotencyStatus; +import common.ecommerce.spi.IdempotencyStore; + +import java.time.Clock; +import java.time.Instant; +import java.util.Objects; +import java.util.Optional; +import java.util.UUID; +import java.util.function.Function; +import java.util.function.Supplier; + +/** + * 写操作幂等守卫:业务键 + provider 请求键双锁。 + * + *
+ * 1. 抢占业务键(不带 provider)——直连与聚合器共用,同一业务动作只成功一次
+ * 2. 抢占 provider 请求键(带 provider)——单 provider 内重试去重
+ * 3. 执行平台写操作
+ * 4. 先记 provider 键成功,再记业务键成功;中途崩溃时下次重试能靠 provider 键识别「已写过」
+ * 
+ * + *

语义:

+ * + * + *

守卫不碰平台协议,也不自行重试;重试由宿主调度决定。

+ */ +public final class IdempotencyGuard { + + public static final long DEFAULT_CLAIM_TTL_SECONDS = 300L; + + private final IdempotencyStore store; + private final String owner; + private final Clock clock; + private final long claimTtlSeconds; + + 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 = Objects.requireNonNull(store, "store"); + this.owner = Objects.requireNonNull(owner, "owner"); + this.clock = Objects.requireNonNull(clock, "clock"); + if (claimTtlSeconds <= 0) { + throw new IllegalArgumentException("claimTtlSeconds must be positive"); + } + this.claimTtlSeconds = claimTtlSeconds; + } + + /** + * 执行一次写操作。 + * + * @param scope 标识维度 + * @param action 平台写操作;抛 {@link ChannelException} 时按其 {@code retryable()} 决定是否可重试 + * @param resultRef 从执行结果中提取结果引用(订单号 / 包裹号等),可为 null + */ + public WriteResult execute(WriteScope scope, Supplier action, Function resultRef) { + Objects.requireNonNull(scope, "scope"); + Objects.requireNonNull(action, "action"); + Objects.requireNonNull(resultRef, "resultRef"); + + final String businessKey = scope.businessKey(); + final String providerKey = scope.providerKey(); + final Instant now = Instant.now(clock); + + // 1) 业务键:跨 provider 的最终裁决 + IdempotencyClaim business = store.claim(businessKey, owner, scope.provider(), now, claimTtlSeconds); + if (!business.acquired()) { + return handleNotAcquired(scope, business, businessKey, providerKey); + } + + // 2) provider 键:识别「平台已写、业务键没来得及记成功」的崩溃窗口 + IdempotencyClaim provider = store.claim(providerKey, owner, scope.provider(), now, claimTtlSeconds); + if (!provider.acquired()) { + if (provider.outcome() == IdempotencyClaim.Outcome.SUCCEEDED) { + store.complete(businessKey, owner, provider.record().resultRef(), Instant.now(clock)); + return replay(scope, provider.record(), businessKey, providerKey); + } + store.fail(businessKey, owner, provider.outcome() != IdempotencyClaim.Outcome.FAILED_FINAL, + Instant.now(clock)); + return handleNotAcquired(scope, provider, businessKey, providerKey); + } + + // 3) 执行 + T value; + try { + value = action.get(); + } catch (RuntimeException e) { + boolean retryable = isRetryable(e); + store.fail(providerKey, owner, retryable, Instant.now(clock)); + store.fail(businessKey, owner, retryable, Instant.now(clock)); + throw e; + } + + // 4) 先记 provider 键,再记业务键 + String ref = resultRef.apply(value); + store.complete(providerKey, owner, ref, Instant.now(clock)); + store.complete(businessKey, owner, ref, Instant.now(clock)); + return WriteResult.executed(value, ref, businessKey, providerKey); + } + + // ---------------------------------------------------------------- internals + + private WriteResult handleNotAcquired(WriteScope scope, IdempotencyClaim claim, + String businessKey, String providerKey) { + IdempotencyRecord record = claim.record(); + switch (claim.outcome()) { + case SUCCEEDED: + return replay(scope, record, businessKey, providerKey); + case IN_PROGRESS: + throw 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() + .message("previous attempt failed permanently, manual intervention required: " + businessKey) + .operation(scope.action()) + .provider(scope.provider().name()) + .omsStoreId(scope.omsStoreId()) + .platform(scope.platform()) + .retryable(false) + .build(); + default: + throw new IllegalStateException("unexpected claim outcome " + claim.outcome() + " for " + businessKey); + } + } + + private WriteResult replay(WriteScope scope, IdempotencyRecord record, + String businessKey, String providerKey) { + if (record.provider() != null && record.provider() != scope.provider()) { + throw new CrossProviderConflictException(ChannelException.builder() + .message("business action already completed by " + record.provider() + + ", requested via " + scope.provider() + ": " + businessKey) + .operation(scope.action()) + .provider(scope.provider().name()) + .omsStoreId(scope.omsStoreId()) + .platform(scope.platform()) + .retryable(false), record.provider().name()); + } + return WriteResult.alreadyCompleted(record.resultRef(), businessKey, providerKey); + } + + /** + * 只有显式标记可重试的 {@link ChannelException} 才允许重跑。 + * + *

超时等「结果未知」的异常由适配器先回查再抛:确认未写入抛可重试异常, + * 确认已写入应当返回成功,而不是抛异常。

+ */ + private static boolean isRetryable(RuntimeException e) { + return e instanceof ChannelException && ((ChannelException) e).retryable(); + } + + public String owner() { + return owner; + } + + /** 只读查询,供运维排查。 */ + public Optional status(WriteScope scope) { + return store.get(scope.businessKey()); + } + + /** 该状态是否可安全重跑。 */ + public static boolean isRetryableStatus(IdempotencyStatus status) { + return status == IdempotencyStatus.FAILED_RETRYABLE; + } +} diff --git a/core/src/main/java/common/ecommerce/idempotency/WriteResult.java b/core/src/main/java/common/ecommerce/idempotency/WriteResult.java new file mode 100644 index 0000000..d0accd8 --- /dev/null +++ b/core/src/main/java/common/ecommerce/idempotency/WriteResult.java @@ -0,0 +1,71 @@ +package common.ecommerce.idempotency; + +/** + * 写操作执行结果。 + * + *

重复调用不视为失败:{@link Outcome#ALREADY_COMPLETED} 表示该业务动作此前已成功, + * 本次没有再次调用平台。

+ */ +public final class WriteResult { + + public enum Outcome { + /** 本次真正执行了平台写操作。 */ + EXECUTED, + /** 此前已成功,本次直接回放,未调用平台。 */ + ALREADY_COMPLETED + } + + private final Outcome outcome; + private final T value; + private final String resultRef; + private final String businessKey; + private final String providerKey; + + private WriteResult(Outcome outcome, T value, String resultRef, String businessKey, String providerKey) { + this.outcome = outcome; + this.value = value; + this.resultRef = resultRef; + this.businessKey = businessKey; + this.providerKey = providerKey; + } + + public static WriteResult executed(T value, String resultRef, String businessKey, String providerKey) { + return new WriteResult(Outcome.EXECUTED, value, resultRef, businessKey, providerKey); + } + + /** 回放:没有本次调用的返回值,只有上次记录的结果引用。 */ + public static WriteResult alreadyCompleted(String resultRef, String businessKey, String providerKey) { + return new WriteResult(Outcome.ALREADY_COMPLETED, null, resultRef, businessKey, providerKey); + } + + public Outcome outcome() { + return outcome; + } + + /** 本次执行结果;ALREADY_COMPLETED 时为 null。 */ + public T value() { + return value; + } + + /** 结果引用(订单号 / 包裹号等);可能为 null。 */ + public String resultRef() { + return resultRef; + } + + public String businessKey() { + return businessKey; + } + + public String providerKey() { + return providerKey; + } + + public boolean alreadyCompleted() { + return outcome == Outcome.ALREADY_COMPLETED; + } + + @Override + public String toString() { + return "WriteResult{" + outcome + (resultRef == null ? "" : " -> " + resultRef) + '}'; + } +} diff --git a/core/src/main/java/common/ecommerce/idempotency/WriteScope.java b/core/src/main/java/common/ecommerce/idempotency/WriteScope.java new file mode 100644 index 0000000..2257647 --- /dev/null +++ b/core/src/main/java/common/ecommerce/idempotency/WriteScope.java @@ -0,0 +1,92 @@ +package common.ecommerce.idempotency; + +import common.ecommerce.model.support.CanonicalKeys; +import common.ecommerce.model.ChannelProvider; +import common.ecommerce.model.Platform; + +import java.util.Objects; + +/** + * 一次写操作的标识维度,由业务键与 provider 请求键共同组成。 + * + *
    + *
  • 业务键:{@code platform + omsStoreId + businessRef + action},不带 provider, + * 直连与聚合器共用,保证同一业务动作只成功一次
  • + *
  • provider 请求键:{@code provider + platform + externalStoreId + operation + providerRef}, + * 只防单 provider 内的重复请求/重试
  • + *
+ */ +public final class WriteScope { + + private final ChannelProvider provider; + private final Platform platform; + private final String omsStoreId; + private final String externalStoreId; + private final String action; + private final String businessRef; + + private WriteScope(ChannelProvider provider, Platform platform, String omsStoreId, String externalStoreId, + String action, String businessRef) { + this.provider = Objects.requireNonNull(provider, "provider"); + this.platform = Objects.requireNonNull(platform, "platform"); + this.omsStoreId = requireText(omsStoreId, "omsStoreId"); + this.externalStoreId = requireText(externalStoreId, "externalStoreId"); + this.action = requireText(action, "action"); + this.businessRef = requireText(businessRef, "businessRef"); + } + + /** + * @param businessRef 业务自然键,如 {@code PO-1:pkg-1} 或 {@code RET-1:ITEM-1:REFUND-1}; + * 不得使用金额 + */ + public static WriteScope of(ChannelProvider provider, Platform platform, String omsStoreId, + String externalStoreId, String action, String businessRef) { + return new WriteScope(provider, platform, omsStoreId, externalStoreId, action, businessRef); + } + + public ChannelProvider provider() { + return provider; + } + + public Platform platform() { + return platform; + } + + public String omsStoreId() { + return omsStoreId; + } + + public String externalStoreId() { + return externalStoreId; + } + + public String action() { + return action; + } + + public String businessRef() { + return businessRef; + } + + /** 跨 provider 的业务幂等键。 */ + public String businessKey() { + return CanonicalKeys.businessIdempotencyKey(platform, omsStoreId, businessRef, action); + } + + /** 单 provider 内的请求幂等键。 */ + public String providerKey() { + return CanonicalKeys.providerRequestKey(provider, platform, externalStoreId, action, businessRef); + } + + @Override + public String toString() { + return provider + ":" + platform + ":" + omsStoreId + ":" + action + ":" + businessRef; + } + + private static String requireText(String value, String name) { + if (value == null || value.trim().isEmpty()) { + throw new IllegalArgumentException(name + " must not be blank"); + } + return value.trim(); + } +} diff --git a/core/src/main/java/common/ecommerce/sdk/ChannelSdk.java b/core/src/main/java/common/ecommerce/sdk/ChannelSdk.java index 154ade2..c96a6dc 100644 --- a/core/src/main/java/common/ecommerce/sdk/ChannelSdk.java +++ b/core/src/main/java/common/ecommerce/sdk/ChannelSdk.java @@ -1,13 +1,16 @@ package common.ecommerce.sdk; +import common.ecommerce.model.Platform; import common.ecommerce.capability.AdapterCapabilityReport; import common.ecommerce.capability.CapabilityReport; import common.ecommerce.capability.PlatformAdapter; import common.ecommerce.capability.Products; import common.ecommerce.capability.SalesOrders; +import common.ecommerce.idempotency.IdempotencyGuard; import common.ecommerce.model.account.AccountKey; import common.ecommerce.model.account.ChannelAccount; import common.ecommerce.spi.ChannelAccountRepository; +import common.ecommerce.spi.IdempotencyStore; import java.time.Clock; import java.util.ArrayList; @@ -34,11 +37,15 @@ public final class ChannelSdk implements ProviderResolver { private final Map adapters; private final ChannelAccountRepository accountRepository; private final Clock clock; + private final IdempotencyGuard idempotencyGuard; private ChannelSdk(Builder b) { this.adapters = Collections.unmodifiableMap(new LinkedHashMap(b.adapters)); this.accountRepository = b.accountRepository; this.clock = b.clock; + this.idempotencyGuard = b.idempotencyStore == null ? null + : new IdempotencyGuard(b.idempotencyStore, b.idempotencyOwner, b.clock, + IdempotencyGuard.DEFAULT_CLAIM_TTL_SECONDS); } public static Builder builder() { @@ -65,6 +72,19 @@ public final class ChannelSdk implements ProviderResolver { return new Products(resolve(key), account, newContext(account)); } + /** + * 写操作幂等守卫(业务键 + provider 请求键双锁)。 + * + *

写操作必须经守卫执行;未注入 {@code IdempotencyStore} 时直接失败, + * 不提供「无幂等」的降级路径。

+ */ + public IdempotencyGuard writes() { + if (idempotencyGuard == null) { + throw new IllegalStateException("ChannelSdk requires an idempotencyStore for write operations"); + } + return idempotencyGuard; + } + /** 按 AccountKey 解析适配器;不自动选路、不自动兜底。 */ @Override public PlatformAdapter resolve(AccountKey key) { @@ -99,6 +119,8 @@ public final class ChannelSdk implements ProviderResolver { private final Map adapters = new LinkedHashMap(); private final List factories = new ArrayList(); private ChannelAccountRepository accountRepository; + private IdempotencyStore idempotencyStore; + private String idempotencyOwner = UUID.randomUUID().toString(); private Clock clock = Clock.systemUTC(); /** 注入账户仓库;宿主实现。 */ @@ -113,6 +135,18 @@ public final class ChannelSdk implements ProviderResolver { return this; } + /** 注入幂等存储;不注入时调用 {@link ChannelSdk#writes()} 会失败。 */ + public Builder idempotencyStore(IdempotencyStore idempotencyStore) { + this.idempotencyStore = idempotencyStore; + return this; + } + + /** 抢占方标识,多实例部署时应能区分;缺省随机 UUID。 */ + public Builder idempotencyOwner(String owner) { + this.idempotencyOwner = Objects.requireNonNull(owner, "owner"); + return this; + } + /** 注册适配器工厂;工厂覆盖的平台会在 build 时创建并注册。 */ public Builder register(AdapterFactory factory) { this.factories.add(Objects.requireNonNull(factory, "factory")); @@ -131,7 +165,7 @@ public final class ChannelSdk implements ProviderResolver { /** 直接注册适配器实例,主要用于测试替身。 */ public Builder register(PlatformAdapter adapter) { Objects.requireNonNull(adapter, "adapter"); - for (common.ecommerce.model.Platform p : adapter.platforms()) { + for (Platform p : adapter.platforms()) { put(adapter.provider().name() + '|' + p.name(), adapter); } return this; diff --git a/core/src/main/java/common/ecommerce/spi/IdempotencyClaim.java b/core/src/main/java/common/ecommerce/spi/IdempotencyClaim.java new file mode 100644 index 0000000..8a10d5c --- /dev/null +++ b/core/src/main/java/common/ecommerce/spi/IdempotencyClaim.java @@ -0,0 +1,57 @@ +package common.ecommerce.spi; + +/** + * 抢占幂等键的结果。 + * + *

宿主实现 {@link IdempotencyStore#claim} 时按以下规则返回:

+ *
    + *
  • 无记录,或记录为 FAILED_RETRYABLE,或 IN_PROGRESS 已超过 TTL:{@link Outcome#ACQUIRED},并写入 IN_PROGRESS
  • + *
  • 记录为 IN_PROGRESS 且未过期:{@link Outcome#IN_PROGRESS},拒绝并发执行
  • + *
  • 记录为 SUCCEEDED:{@link Outcome#SUCCEEDED},回放结果
  • + *
  • 记录为 FAILED_FINAL:{@link Outcome#FAILED_FINAL},需人工介入
  • + *
+ */ +public final class IdempotencyClaim { + + public enum Outcome { + ACQUIRED, + IN_PROGRESS, + SUCCEEDED, + FAILED_FINAL + } + + private final Outcome outcome; + private final IdempotencyRecord record; + + private IdempotencyClaim(Outcome outcome, IdempotencyRecord record) { + this.outcome = outcome; + this.record = record; + } + + /** 抢占成功;record 为 null(没有历史记录)。 */ + public static IdempotencyClaim acquire() { + return new IdempotencyClaim(Outcome.ACQUIRED, null); + } + + public static IdempotencyClaim of(Outcome outcome, IdempotencyRecord record) { + return new IdempotencyClaim(outcome, record); + } + + public Outcome outcome() { + return outcome; + } + + /** 已有记录;ACQUIRED 时为 null。 */ + public IdempotencyRecord record() { + return record; + } + + public boolean acquired() { + return outcome == Outcome.ACQUIRED; + } + + @Override + public String toString() { + return "IdempotencyClaim{" + outcome + (record == null ? "" : " " + record) + '}'; + } +} diff --git a/core/src/main/java/common/ecommerce/spi/IdempotencyRecord.java b/core/src/main/java/common/ecommerce/spi/IdempotencyRecord.java new file mode 100644 index 0000000..c9b010d --- /dev/null +++ b/core/src/main/java/common/ecommerce/spi/IdempotencyRecord.java @@ -0,0 +1,69 @@ +package common.ecommerce.spi; + +import common.ecommerce.model.ChannelProvider; + +import java.time.Instant; +import java.util.Objects; + +/** + * 幂等键的当前记录。 + * + *

{@code provider} 记录该动作最终由哪条接入通道完成,用于识别跨 provider + * 重复执行;{@code owner} 是抢占该键的实例标识,用于判断并发。

+ */ +public final class IdempotencyRecord { + + private final String key; + private final IdempotencyStatus status; + private final ChannelProvider provider; + private final String owner; + private final String resultRef; + private final Instant updatedAt; + + private IdempotencyRecord(String key, IdempotencyStatus status, ChannelProvider provider, + String owner, String resultRef, Instant updatedAt) { + this.key = Objects.requireNonNull(key, "key"); + this.status = Objects.requireNonNull(status, "status"); + this.provider = provider; + this.owner = owner; + this.resultRef = resultRef; + this.updatedAt = Objects.requireNonNull(updatedAt, "updatedAt"); + } + + public static IdempotencyRecord of(String key, IdempotencyStatus status, ChannelProvider provider, + String owner, String resultRef, Instant updatedAt) { + return new IdempotencyRecord(key, status, provider, owner, resultRef, updatedAt); + } + + public String key() { + return key; + } + + public IdempotencyStatus status() { + return status; + } + + /** 完成该动作的 provider;IN_PROGRESS 时为抢占方。 */ + public ChannelProvider provider() { + return provider; + } + + public String owner() { + return owner; + } + + /** 结果引用(订单号 / 包裹号等),不保存完整业务结果。 */ + public String resultRef() { + return resultRef; + } + + public Instant updatedAt() { + return updatedAt; + } + + @Override + public String toString() { + return "IdempotencyRecord{" + key + " " + status + " by " + provider + '/' + owner + + (resultRef == null ? "" : " -> " + resultRef) + '}'; + } +} diff --git a/core/src/main/java/common/ecommerce/spi/IdempotencyStatus.java b/core/src/main/java/common/ecommerce/spi/IdempotencyStatus.java new file mode 100644 index 0000000..4cec7a3 --- /dev/null +++ b/core/src/main/java/common/ecommerce/spi/IdempotencyStatus.java @@ -0,0 +1,18 @@ +package common.ecommerce.spi; + +/** + * 幂等键状态。 + * + *

写操作按「抢占 → 执行 → 记录结果」流转,只有 SUCCEEDED 可以回放结果。

+ */ +public enum IdempotencyStatus { + + /** 已抢占,执行中;并发重复请求被拒绝。 */ + IN_PROGRESS, + /** 已成功;重复请求直接回放结果。 */ + SUCCEEDED, + /** 可重试失败;允许再次抢占重跑。 */ + FAILED_RETRYABLE, + /** 终态失败;需人工介入,不再自动重试。 */ + FAILED_FINAL +} diff --git a/core/src/main/java/common/ecommerce/spi/IdempotencyStore.java b/core/src/main/java/common/ecommerce/spi/IdempotencyStore.java new file mode 100644 index 0000000..8bed7cf --- /dev/null +++ b/core/src/main/java/common/ecommerce/spi/IdempotencyStore.java @@ -0,0 +1,34 @@ +package common.ecommerce.spi; + +import common.ecommerce.model.ChannelProvider; + +import java.time.Instant; +import java.util.Optional; + +/** + * 幂等存储 SPI。宿主实现(典型 MySQL / Redis),SDK 只调用。 + * + *

实现必须保证 {@link #claim} 的原子性(唯一索引或 Redis SETNX):并发抢占同一键时 + * 只有一个调用能得到 {@link IdempotencyClaim.Outcome#ACQUIRED}。

+ */ +public interface IdempotencyStore { + + /** + * 抢占幂等键。 + * + * @param key 幂等键(业务键或 provider 请求键) + * @param owner 抢占方实例标识 + * @param provider 接入通道,写入记录用于识别跨 provider 重复 + * @param now 当前时间(UTC) + * @param ttlSeconds 抢占后无结果的最长保留时间,过期视为可重新抢占 + */ + IdempotencyClaim claim(String key, String owner, ChannelProvider provider, Instant now, long ttlSeconds); + + /** 执行成功,记录结果引用。只有当前 owner 可以写入。 */ + void complete(String key, String owner, String resultRef, Instant now); + + /** 执行失败;{@code retryable=false} 记为终态,不再自动重试。 */ + void fail(String key, String owner, boolean retryable, Instant now); + + Optional get(String key); +} diff --git a/core/src/test/java/common/ecommerce/sdk/ChannelSdkTest.java b/core/src/test/java/common/ecommerce/sdk/ChannelSdkTest.java index 1f0a2de..45f5acf 100644 --- a/core/src/test/java/common/ecommerce/sdk/ChannelSdkTest.java +++ b/core/src/test/java/common/ecommerce/sdk/ChannelSdkTest.java @@ -3,6 +3,7 @@ package common.ecommerce.sdk; import common.ecommerce.capability.CapabilityReport; import common.ecommerce.capability.PlatformAdapter; import common.ecommerce.error.ChannelException; +import common.ecommerce.idempotency.WriteResult; import common.ecommerce.model.account.AccountKey; import common.ecommerce.model.Capability; import common.ecommerce.model.account.ChannelAccount; @@ -10,7 +11,6 @@ import common.ecommerce.model.ChannelProvider; import common.ecommerce.model.support.Page; import common.ecommerce.model.Platform; import common.ecommerce.model.order.SalesOrder; -import common.ecommerce.model.order.SalesOrderRef; import common.ecommerce.model.order.SalesOrderQuery; import common.ecommerce.sdk.ChannelContext; import common.ecommerce.spi.ChannelAccountRepository; @@ -63,7 +63,7 @@ class ChannelSdkTest { } @Override - public SalesOrder get(ChannelContext ctx, SalesOrderRef ref) { + public SalesOrder get(ChannelContext ctx, common.ecommerce.model.order.SalesOrderRef ref) { return null; } } @@ -181,4 +181,69 @@ class ChannelSdkTest { .register(new FakeDirectAdapter()); assertThrows(IllegalStateException.class, () -> builder.register(new FakeDirectAdapter())); } + + @Test + void writesRequireIdempotencyStore() { + ChannelSdk sdk = sdkWith(new FakeDirectAdapter()); + IllegalStateException ex = assertThrows(IllegalStateException.class, sdk::writes); + assertTrue(ex.getMessage().contains("idempotencyStore"), ex.getMessage()); + } + + @Test + void writesUseInjectedStore() { + // core 不能依赖 testkit,这里用最小本地替身验证门面装配 + common.ecommerce.spi.IdempotencyStore store = + new common.ecommerce.spi.IdempotencyStore() { + private final java.util.Map records = + new java.util.LinkedHashMap(); + + @Override + public common.ecommerce.spi.IdempotencyClaim claim(String key, String owner, + ChannelProvider provider, java.time.Instant now, long ttlSeconds) { + common.ecommerce.spi.IdempotencyRecord existing = records.get(key); + if (existing != null && existing.status() == common.ecommerce.spi.IdempotencyStatus.SUCCEEDED) { + return common.ecommerce.spi.IdempotencyClaim.of( + common.ecommerce.spi.IdempotencyClaim.Outcome.SUCCEEDED, existing); + } + records.put(key, common.ecommerce.spi.IdempotencyRecord.of(key, + common.ecommerce.spi.IdempotencyStatus.IN_PROGRESS, provider, owner, null, now)); + return common.ecommerce.spi.IdempotencyClaim.acquire(); + } + + @Override + public void complete(String key, String owner, String resultRef, java.time.Instant now) { + common.ecommerce.spi.IdempotencyRecord current = records.get(key); + records.put(key, common.ecommerce.spi.IdempotencyRecord.of(key, + common.ecommerce.spi.IdempotencyStatus.SUCCEEDED, current.provider(), + owner, resultRef, now)); + } + + @Override + public void fail(String key, String owner, boolean retryable, java.time.Instant now) { + common.ecommerce.spi.IdempotencyRecord current = records.get(key); + records.put(key, common.ecommerce.spi.IdempotencyRecord.of(key, + common.ecommerce.spi.IdempotencyStatus.FAILED_RETRYABLE, + current.provider(), owner, null, now)); + } + + @Override + public java.util.Optional get(String key) { + return java.util.Optional.ofNullable(records.get(key)); + } + }; + + ChannelSdk sdk = ChannelSdk.builder() + .accountRepository(new FixedAccounts(walmartAccount())) + .idempotencyStore(store) + .register(new FakeDirectAdapter()) + .build(); + + common.ecommerce.idempotency.WriteScope scope = common.ecommerce.idempotency.WriteScope.of( + ChannelProvider.DIRECT, Platform.WALMART_SC, "oms-wm-001", "wm-seller-01", + "markShipped", "PO-1:pkg-1"); + assertEquals(WriteResult.Outcome.EXECUTED, + sdk.writes().execute(scope, () -> "SHIP-1", v -> v).outcome()); + assertEquals(WriteResult.Outcome.ALREADY_COMPLETED, + sdk.writes().execute(scope, () -> "SHIP-2", v -> v).outcome()); + } } diff --git a/testkit/pom.xml b/testkit/pom.xml index 96566c8..7c62040 100644 --- a/testkit/pom.xml +++ b/testkit/pom.xml @@ -29,6 +29,7 @@ org.junit.jupiter junit-jupiter + test diff --git a/testkit/src/main/java/common/ecommerce/testkit/InMemoryIdempotencyStore.java b/testkit/src/main/java/common/ecommerce/testkit/InMemoryIdempotencyStore.java new file mode 100644 index 0000000..0737f24 --- /dev/null +++ b/testkit/src/main/java/common/ecommerce/testkit/InMemoryIdempotencyStore.java @@ -0,0 +1,116 @@ +package common.ecommerce.testkit; + +import common.ecommerce.model.ChannelProvider; +import common.ecommerce.spi.IdempotencyClaim; +import common.ecommerce.spi.IdempotencyRecord; +import common.ecommerce.spi.IdempotencyStatus; +import common.ecommerce.spi.IdempotencyStore; + +import java.time.Duration; +import java.time.Instant; +import java.util.HashMap; +import java.util.Map; +import java.util.Optional; + +/** + * 内存版幂等存储,语义与宿主实现一致: + * + *
    + *
  • 无记录 / FAILED_RETRYABLE / IN_PROGRESS 超过 TTL → 抢占成功
  • + *
  • IN_PROGRESS 未过期 → 拒绝并发
  • + *
  • SUCCEEDED → 回放;FAILED_FINAL → 终态
  • + *
+ * + *

并发相关的行为只能在单 JVM 内验证;真实抢占原子性由宿主唯一索引 / Redis 保证。

+ */ +public final class InMemoryIdempotencyStore implements IdempotencyStore { + + private final Map records = new HashMap(); + private int claimAcquired; + private int claimRejected; + + @Override + public synchronized IdempotencyClaim claim(String key, String owner, ChannelProvider provider, + Instant now, long ttlSeconds) { + IdempotencyRecord existing = records.get(key); + if (existing == null || isReclaimable(existing, now, ttlSeconds)) { + records.put(key, IdempotencyRecord.of(key, IdempotencyStatus.IN_PROGRESS, provider, owner, null, now)); + claimAcquired++; + return IdempotencyClaim.acquire(); + } + claimRejected++; + switch (existing.status()) { + case SUCCEEDED: + return IdempotencyClaim.of(IdempotencyClaim.Outcome.SUCCEEDED, existing); + case FAILED_FINAL: + return IdempotencyClaim.of(IdempotencyClaim.Outcome.FAILED_FINAL, existing); + default: + return IdempotencyClaim.of(IdempotencyClaim.Outcome.IN_PROGRESS, existing); + } + } + + @Override + public synchronized void complete(String key, String owner, String resultRef, Instant now) { + IdempotencyRecord current = requireOwned(key, owner); + records.put(key, IdempotencyRecord.of(key, IdempotencyStatus.SUCCEEDED, + current.provider(), owner, resultRef, now)); + } + + @Override + public synchronized void fail(String key, String owner, boolean retryable, Instant now) { + IdempotencyRecord current = requireOwned(key, owner); + records.put(key, IdempotencyRecord.of(key, + retryable ? IdempotencyStatus.FAILED_RETRYABLE : IdempotencyStatus.FAILED_FINAL, + current.provider(), owner, current.resultRef(), now)); + } + + @Override + public synchronized Optional get(String key) { + return Optional.ofNullable(records.get(key)); + } + + /** 测试辅助:直接写入一条已完成记录,模拟「另一个 provider 早就做过」。 */ + public synchronized InMemoryIdempotencyStore seedSucceeded(String key, ChannelProvider provider, + String resultRef, Instant at) { + records.put(key, IdempotencyRecord.of(key, IdempotencyStatus.SUCCEEDED, provider, "seed", resultRef, at)); + return this; + } + + /** 测试辅助:直接写入 IN_PROGRESS 记录,模拟并发执行中。 */ + public synchronized InMemoryIdempotencyStore seedInProgress(String key, ChannelProvider provider, + String owner, Instant at) { + records.put(key, IdempotencyRecord.of(key, IdempotencyStatus.IN_PROGRESS, provider, owner, null, at)); + return this; + } + + public synchronized int claimAcquiredCount() { + return claimAcquired; + } + + public synchronized int claimRejectedCount() { + return claimRejected; + } + + public synchronized int size() { + return records.size(); + } + + private IdempotencyRecord requireOwned(String key, String owner) { + IdempotencyRecord current = records.get(key); + if (current == null) { + throw new IllegalStateException("no idempotency record for " + key); + } + if (!current.owner().equals(owner) || current.status() != IdempotencyStatus.IN_PROGRESS) { + throw new IllegalStateException("record not owned by " + owner + " in progress: " + current); + } + return current; + } + + private static boolean isReclaimable(IdempotencyRecord record, Instant now, long ttlSeconds) { + if (record.status() == IdempotencyStatus.FAILED_RETRYABLE) { + return true; + } + return record.status() == IdempotencyStatus.IN_PROGRESS + && !now.isBefore(record.updatedAt().plus(Duration.ofSeconds(ttlSeconds))); + } +} diff --git a/testkit/src/main/java/common/ecommerce/testkit/MutableClock.java b/testkit/src/main/java/common/ecommerce/testkit/MutableClock.java new file mode 100644 index 0000000..fdec95c --- /dev/null +++ b/testkit/src/main/java/common/ecommerce/testkit/MutableClock.java @@ -0,0 +1,49 @@ +package common.ecommerce.testkit; + +import java.time.Clock; +import java.time.Duration; +import java.time.Instant; +import java.time.ZoneId; +import java.time.ZoneOffset; + +/** + * 可推进的时钟。用来验证 TTL、提前续期、水位线等与时间有关的边界。 + */ +public final class MutableClock extends Clock { + + private Instant now; + private final ZoneId zone; + + public MutableClock(Instant now, ZoneId zone) { + this.now = now; + this.zone = zone; + } + + public static MutableClock atUtc(String iso) { + return new MutableClock(Instant.parse(iso), ZoneOffset.UTC); + } + + public MutableClock advance(Duration duration) { + now = now.plus(duration); + return this; + } + + public void set(Instant instant) { + this.now = instant; + } + + @Override + public ZoneId getZone() { + return zone; + } + + @Override + public Clock withZone(ZoneId zone) { + return new MutableClock(now, zone); + } + + @Override + public Instant instant() { + return now; + } +} diff --git a/testkit/src/test/java/common/ecommerce/idempotency/IdempotencyGuardTest.java b/testkit/src/test/java/common/ecommerce/idempotency/IdempotencyGuardTest.java new file mode 100644 index 0000000..699a450 --- /dev/null +++ b/testkit/src/test/java/common/ecommerce/idempotency/IdempotencyGuardTest.java @@ -0,0 +1,212 @@ +package common.ecommerce.idempotency; + +import common.ecommerce.error.ChannelException; +import common.ecommerce.error.CrossProviderConflictException; +import common.ecommerce.error.IdempotencyConflictException; +import common.ecommerce.model.ChannelProvider; +import common.ecommerce.model.Platform; +import common.ecommerce.spi.IdempotencyStatus; +import common.ecommerce.testkit.InMemoryIdempotencyStore; +import common.ecommerce.testkit.MutableClock; +import org.junit.jupiter.api.BeforeEach; +import org.junit.jupiter.api.Test; + +import java.time.Duration; +import java.time.Instant; +import java.util.concurrent.atomic.AtomicInteger; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertFalse; +import static org.junit.jupiter.api.Assertions.assertNull; +import static org.junit.jupiter.api.Assertions.assertThrows; +import static org.junit.jupiter.api.Assertions.assertTrue; + +/** + * 双锁幂等守卫的行为:回放、跨 provider 冲突、并发拒绝、可重试失败、TTL 重抢。 + */ +class IdempotencyGuardTest { + + private static final Instant T0 = Instant.parse("2026-10-29T00:00:00Z"); + private static final WriteScope MARK_SHIPPED = WriteScope.of( + ChannelProvider.LINGXING, Platform.WALMART_SC, "oms-wm-001", "1108413237731", + "markShipped", "PO-1:pkg-1"); + + private InMemoryIdempotencyStore store; + private MutableClock clock; + private IdempotencyGuard guard; + + @BeforeEach + void setUp() { + store = new InMemoryIdempotencyStore(); + clock = new MutableClock(T0, java.time.ZoneOffset.UTC); + guard = new IdempotencyGuard(store, "worker-1", clock, 60); + } + + @Test + void firstCallExecutesSecondCallReplays() { + AtomicInteger calls = new AtomicInteger(); + + WriteResult first = guard.execute(MARK_SHIPPED, () -> { + calls.incrementAndGet(); + return "SHIP-1"; + }, v -> v); + + WriteResult second = guard.execute(MARK_SHIPPED, () -> { + calls.incrementAndGet(); + return "SHIP-2"; + }, v -> v); + + assertEquals(WriteResult.Outcome.EXECUTED, first.outcome()); + assertEquals("SHIP-1", first.resultRef()); + assertEquals(WriteResult.Outcome.ALREADY_COMPLETED, second.outcome()); + assertEquals("SHIP-1", second.resultRef()); + assertNull(second.value()); + assertEquals(1, calls.get(), "platform write must happen only once"); + } + + @Test + void doubleKeysPersistedWithProviderAndRef() { + guard.execute(MARK_SHIPPED, () -> "SHIP-1", v -> v); + + assertEquals(IdempotencyStatus.SUCCEEDED, + store.get(MARK_SHIPPED.businessKey()).get().status()); + assertEquals(IdempotencyStatus.SUCCEEDED, + store.get(MARK_SHIPPED.providerKey()).get().status()); + assertEquals(ChannelProvider.LINGXING, + store.get(MARK_SHIPPED.businessKey()).get().provider()); + assertTrue(MARK_SHIPPED.providerKey().startsWith("LINGXING:WALMART_SC:1108413237731:markShipped:")); + assertTrue(MARK_SHIPPED.businessKey().startsWith("WALMART_SC:oms-wm-001:PO-1:pkg-1:")); + } + + @Test + void sameBusinessActionViaOtherProviderIsConflict() { + guard.execute(MARK_SHIPPED, () -> "SHIP-1", v -> v); + + WriteScope viaDirect = WriteScope.of(ChannelProvider.DIRECT, Platform.WALMART_SC, "oms-wm-001", + "wm-seller-01", "markShipped", "PO-1:pkg-1"); + assertEquals(MARK_SHIPPED.businessKey(), viaDirect.businessKey()); + + CrossProviderConflictException ex = assertThrows(CrossProviderConflictException.class, + () -> guard.execute(viaDirect, () -> "SHIP-2", v -> v)); + assertEquals("LINGXING", ex.completedByProvider()); + assertFalse(ex.retryable()); + } + + @Test + void concurrentAttemptRejectedWhileInProgress() { + store.seedInProgress(MARK_SHIPPED.businessKey(), ChannelProvider.LINGXING, "worker-2", T0); + + IdempotencyConflictException ex = assertThrows(IdempotencyConflictException.class, + () -> guard.execute(MARK_SHIPPED, () -> "SHIP-1", v -> v)); + assertEquals(MARK_SHIPPED.businessKey(), ex.idempotencyKey()); + } + + @Test + void retryableFailureAllowsRerun() { + ChannelException failure = ChannelException.builder() + .message("http 503") + .operation("markShipped") + .retryable(true) + .build(); + + assertThrows(ChannelException.class, () -> guard.execute(MARK_SHIPPED, () -> { + throw failure; + }, v -> v)); + + assertEquals(IdempotencyStatus.FAILED_RETRYABLE, + store.get(MARK_SHIPPED.businessKey()).get().status()); + assertEquals(IdempotencyStatus.FAILED_RETRYABLE, + store.get(MARK_SHIPPED.providerKey()).get().status()); + + WriteResult retry = guard.execute(MARK_SHIPPED, () -> "SHIP-2", v -> v); + assertEquals(WriteResult.Outcome.EXECUTED, retry.outcome()); + assertEquals("SHIP-2", retry.resultRef()); + } + + @Test + void nonRetryableFailureBlocksAutomaticRetry() { + ChannelException failure = ChannelException.builder() + .message("http 400") + .operation("markShipped") + .retryable(false) + .build(); + + assertThrows(ChannelException.class, () -> guard.execute(MARK_SHIPPED, () -> { + throw failure; + }, v -> v)); + + assertEquals(IdempotencyStatus.FAILED_FINAL, + store.get(MARK_SHIPPED.businessKey()).get().status()); + + ChannelException ex = assertThrows(ChannelException.class, + () -> guard.execute(MARK_SHIPPED, () -> "SHIP-2", v -> v)); + assertTrue(ex.getMessage().contains("manual intervention"), ex.getMessage()); + assertFalse(ex.retryable()); + } + + @Test + void staleInProgressCanBeReclaimedAfterTtl() { + store.seedInProgress(MARK_SHIPPED.businessKey(), ChannelProvider.LINGXING, "dead-worker", T0); + clock.advance(Duration.ofSeconds(61)); + + WriteResult result = guard.execute(MARK_SHIPPED, () -> "SHIP-1", v -> v); + assertEquals(WriteResult.Outcome.EXECUTED, result.outcome()); + assertEquals(IdempotencyStatus.SUCCEEDED, + store.get(MARK_SHIPPED.businessKey()).get().status()); + assertEquals("SHIP-1", store.get(MARK_SHIPPED.businessKey()).get().resultRef()); + } + + @Test + void providerKeyRecoversCrashWindowWithoutRewriting() { + // 模拟:平台已写入、provider 键已记成功,但业务键没来得及写 + store.seedSucceeded(MARK_SHIPPED.providerKey(), ChannelProvider.LINGXING, "SHIP-1", T0); + AtomicInteger calls = new AtomicInteger(); + + WriteResult result = guard.execute(MARK_SHIPPED, () -> { + calls.incrementAndGet(); + return "SHIP-2"; + }, v -> v); + + assertEquals(WriteResult.Outcome.ALREADY_COMPLETED, result.outcome()); + assertEquals("SHIP-1", result.resultRef()); + assertEquals(0, calls.get(), "must not call platform again"); + assertEquals(IdempotencyStatus.SUCCEEDED, + store.get(MARK_SHIPPED.businessKey()).get().status()); + } + + @Test + void refundKeyMustNotUseAmount() { + // 同一退款请求重复提交,金额格式变化不应产生新的业务动作 + WriteScope a = WriteScope.of(ChannelProvider.DIRECT, Platform.WALMART_SC, "oms-wm-001", + "wm-seller-01", "refund", "RET-1:ITEM-1:RFD-1"); + WriteScope b = WriteScope.of(ChannelProvider.DIRECT, Platform.WALMART_SC, "oms-wm-001", + "wm-seller-01", "refund", "RET-1:ITEM-1:RFD-1"); + assertEquals(a.businessKey(), b.businessKey()); + } + + @Test + void guardOnlyWritesPlatformOnceAcrossRetry() { + // 适配器层记录:平台写操作只应发生一次 + common.ecommerce.testkit.FakeDirectAdapter adapter = + common.ecommerce.testkit.FakeDirectAdapter.builder().build(); + + guard.execute(MARK_SHIPPED, () -> adapter.markShipped("pkg-1", "1Z-1"), v -> v); + guard.execute(MARK_SHIPPED, () -> adapter.markShipped("pkg-1", "1Z-1"), v -> v); + + assertEquals(1, adapter.writeCallCount()); + } + + @Test + void blankScopePartsRejected() { + assertThrows(IllegalArgumentException.class, () -> WriteScope.of(ChannelProvider.DIRECT, + Platform.WALMART_SC, "oms-wm-001", "wm-seller-01", "markShipped", " ")); + } + + @Test + void statusLookupForOps() { + assertFalse(guard.status(MARK_SHIPPED).isPresent()); + guard.execute(MARK_SHIPPED, () -> "SHIP-1", v -> v); + assertTrue(guard.status(MARK_SHIPPED).isPresent()); + assertTrue(IdempotencyGuard.isRetryableStatus(IdempotencyStatus.FAILED_RETRYABLE)); + } +}