Browse Source
- IdempotencyGuard 注入 CallObserver,EXECUTED / 回放 / 崩溃窗口修复 / 并发冲突 / 终态失败 / 跨 provider 冲突 / 可重试与不可重试失败全部留痕 - 新增 WriteAudit,操作名 writes.<action>,params 带 businessKey / providerKey / stage - ChannelContext 增加 withRequestId / ofKey,门面各视图可刷新链路 ID - ChannelSdk 增加 requestIdSupplier;capabilities 纳入埋点;build 时打启动自检日志feature/supplier-lingxing
10 changed files with 393 additions and 24 deletions
@ -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 |
||||
} |
||||
} |
||||
Loading…
Reference in new issue