Browse Source
- 新增 CallObserver SPI 与 CallRecord/CallOutcome:SDK 只产出结构化记录,落库/发 MQ 由宿主实现 - 新增 CallSupport:统一计时、结果数量、异常捕获;观察者异常吞掉并打 WARN,不影响业务调用 - 新增 Slf4jCallObserver:成功 INFO、失败 WARN,时间格式 yyyy-MM-dd HH:mm:ss,时区与格式可配置 - ChannelSdk.Builder 增加 callObserver(...),默认 NOOP - salesOrders / products / settlements / afterSales / outbounds / subChannels 全部埋点,能力检查失败也记录 - CallRecord 覆盖 requestId、provider/platform、omsStoreId/storeId、operation、outcome、耗时、结果数、 参数摘要、错误类型/消息、retryable、平台 request_id - 时间内部统一存 UTC,另提供 occurredAt(zone) / finishedAt(zone) 供本地展示feature/supplier-lingxing
11 changed files with 791 additions and 49 deletions
@ -0,0 +1,29 @@
@@ -0,0 +1,29 @@
|
||||
package common.ecommerce.audit; |
||||
|
||||
/** |
||||
* SDK 调用观察者:操作日志 / 审计日志的宿主扩展点。 |
||||
* |
||||
* <p>SDK 是纯库,不写数据库、不写文件、不起线程。需要把调用记录落库、发 MQ 或接监控时, |
||||
* 由宿主实现本接口并注入 {@code ChannelSdk.Builder.callObserver(...)}。</p> |
||||
* |
||||
* <p>实现约束:</p> |
||||
* <ul> |
||||
* <li><b>不要抛异常</b>。SDK 会兜底捕获,但吞掉异常会掩盖实现问题;</li> |
||||
* <li>回调发生在业务线程上,方法应尽快返回。慢操作请自行投递到宿主的异步通道;</li> |
||||
* <li>{@link CallRecord#params()} 只放摘要,不要补写密钥、买家姓名、收货地址等敏感信息。</li> |
||||
* </ul> |
||||
*/ |
||||
public interface CallObserver { |
||||
|
||||
/** 空实现:不记录任何内容,也是默认值。 */ |
||||
CallObserver NOOP = record -> { |
||||
// 默认不做任何事
|
||||
}; |
||||
|
||||
/** |
||||
* 每次门面调用结束后回调一次;成功与失败都会回调。 |
||||
* |
||||
* @param record 不可变的调用记录 |
||||
*/ |
||||
void onCall(CallRecord record); |
||||
} |
||||
@ -0,0 +1,13 @@
@@ -0,0 +1,13 @@
|
||||
package common.ecommerce.audit; |
||||
|
||||
/** |
||||
* 一次 SDK 调用的结果状态。 |
||||
*/ |
||||
public enum CallOutcome { |
||||
|
||||
/** 调用成功(适配器没有抛异常)。 */ |
||||
SUCCESS, |
||||
|
||||
/** 调用失败(能力不支持、参数校验、平台返回错误、网络异常等)。 */ |
||||
FAILURE |
||||
} |
||||
@ -0,0 +1,278 @@
@@ -0,0 +1,278 @@
|
||||
package common.ecommerce.audit; |
||||
|
||||
import common.ecommerce.error.ChannelException; |
||||
import common.ecommerce.model.ChannelProvider; |
||||
import common.ecommerce.model.Platform; |
||||
|
||||
import java.time.Instant; |
||||
import java.time.ZoneId; |
||||
import java.time.ZonedDateTime; |
||||
import java.util.Collections; |
||||
import java.util.LinkedHashMap; |
||||
import java.util.Map; |
||||
import java.util.Objects; |
||||
/** |
||||
* 一次 SDK 调用的操作记录(不可变)。 |
||||
* |
||||
* <p>内容只覆盖排查所需的最小集合:调用方是谁、对哪个账户、调了哪个能力、 |
||||
* 用了什么摘要参数、耗时、结果数量、失败原因。</p> |
||||
* |
||||
* <p><b>敏感信息约定</b>:{@link #params()} 只允许放时间窗、分页、游标、 |
||||
* 单号数量这类摘要;密钥、买家姓名、收货地址、完整报文一律不放。 |
||||
* SDK 自身绝不会把 {@code ChannelSecret} 写进来。</p> |
||||
*/ |
||||
public final class CallRecord { |
||||
|
||||
private final Instant occurredAt; |
||||
private final String requestId; |
||||
private final ChannelProvider provider; |
||||
private final Platform platform; |
||||
private final String omsStoreId; |
||||
private final String externalStoreId; |
||||
private final String operation; |
||||
private final CallOutcome outcome; |
||||
private final long durationMillis; |
||||
private final int resultCount; |
||||
private final Map<String, Object> params; |
||||
private final String errorType; |
||||
private final String errorMessage; |
||||
private final Boolean retryable; |
||||
private final String platformRequestId; |
||||
|
||||
private CallRecord(Builder b) { |
||||
this.occurredAt = Objects.requireNonNull(b.occurredAt, "occurredAt"); |
||||
this.requestId = b.requestId; |
||||
this.provider = b.provider; |
||||
this.platform = b.platform; |
||||
this.omsStoreId = b.omsStoreId; |
||||
this.externalStoreId = b.externalStoreId; |
||||
this.operation = Objects.requireNonNull(b.operation, "operation"); |
||||
this.outcome = Objects.requireNonNull(b.outcome, "outcome"); |
||||
this.durationMillis = b.durationMillis; |
||||
this.resultCount = b.resultCount; |
||||
this.params = Collections.unmodifiableMap( |
||||
new LinkedHashMap<>(b.params)); |
||||
this.errorType = b.errorType; |
||||
this.errorMessage = b.errorMessage; |
||||
this.retryable = b.retryable; |
||||
this.platformRequestId = b.platformRequestId; |
||||
} |
||||
|
||||
public static Builder builder() { |
||||
return new Builder(); |
||||
} |
||||
|
||||
/** 调用开始时间(UTC);结束时间可用 {@link #finishedAt()}。 */ |
||||
public Instant occurredAt() { |
||||
return occurredAt; |
||||
} |
||||
|
||||
/** |
||||
* 按宿主时区展示的开始时间。 |
||||
* |
||||
* <p>{@link #occurredAt()} 是 {@link Instant},本身就是 UTC,直接 {@code toString()} |
||||
* 永远带 {@code Z};要本地时间就用这个方法,例如 |
||||
* {@code record.occurredAt(ZoneId.of("Asia/Shanghai"))}。</p> |
||||
*/ |
||||
public ZonedDateTime occurredAt(ZoneId zone) { |
||||
return occurredAt.atZone(Objects.requireNonNull(zone, "zone")); |
||||
} |
||||
|
||||
/** 调用结束时间(UTC)= 开始时间 + {@link #durationMillis()}。 */ |
||||
public Instant finishedAt() { |
||||
return occurredAt.plusMillis(durationMillis); |
||||
} |
||||
|
||||
/** 按宿主时区展示的结束时间。 */ |
||||
public ZonedDateTime finishedAt(ZoneId zone) { |
||||
return finishedAt().atZone(Objects.requireNonNull(zone, "zone")); |
||||
} |
||||
|
||||
/** 链路 ID,与 HTTP 层日志、平台 request_id 关联用。 */ |
||||
public String requestId() { |
||||
return requestId; |
||||
} |
||||
|
||||
public ChannelProvider provider() { |
||||
return provider; |
||||
} |
||||
|
||||
public Platform platform() { |
||||
return platform; |
||||
} |
||||
|
||||
/** 宿主侧的店铺 ID(业务主键的一部分)。 */ |
||||
public String omsStoreId() { |
||||
return omsStoreId; |
||||
} |
||||
|
||||
/** 渠道侧店铺 ID;领星是 {@code store_id},亚马逊 SC 是 {@code sid}。 */ |
||||
public String externalStoreId() { |
||||
return externalStoreId; |
||||
} |
||||
|
||||
/** 门面操作名,如 {@code salesOrders.pull}、{@code outbounds.labels}。 */ |
||||
public String operation() { |
||||
return operation; |
||||
} |
||||
|
||||
public CallOutcome outcome() { |
||||
return outcome; |
||||
} |
||||
|
||||
/** 耗时(毫秒);测试注入固定时钟时为 0。 */ |
||||
public long durationMillis() { |
||||
return durationMillis; |
||||
} |
||||
|
||||
/** 结果条数;单对象为 1,不适用(写操作等)为 -1。 */ |
||||
public int resultCount() { |
||||
return resultCount; |
||||
} |
||||
|
||||
/** 参数摘要,只读;见类注释里的敏感信息约定。 */ |
||||
public Map<String, Object> params() { |
||||
return params; |
||||
} |
||||
|
||||
/** 失败时的异常类名;成功为 null。 */ |
||||
public String errorType() { |
||||
return errorType; |
||||
} |
||||
|
||||
/** 失败时的异常消息;成功为 null。 */ |
||||
public String errorMessage() { |
||||
return errorMessage; |
||||
} |
||||
|
||||
/** |
||||
* 是否可重试;仅当失败异常是 {@code ChannelException} 时有值,其余为 null。 |
||||
* |
||||
* <p>运维可直接据此决定「重跑」还是「人工介入」。</p> |
||||
*/ |
||||
public Boolean retryable() { |
||||
return retryable; |
||||
} |
||||
|
||||
/** |
||||
* 平台返回的 request_id / 链路 ID;仅当失败异常是 {@code ChannelException} |
||||
* 且适配器填了该字段时有值。排查时需要拿它找平台侧日志。 |
||||
*/ |
||||
public String platformRequestId() { |
||||
return platformRequestId; |
||||
} |
||||
|
||||
public boolean failed() { |
||||
return outcome == CallOutcome.FAILURE; |
||||
} |
||||
|
||||
@Override |
||||
public String toString() { |
||||
return "CallRecord{" + outcome |
||||
+ " at=" + occurredAt |
||||
+ " op=" + operation |
||||
+ " " + provider + "/" + platform |
||||
+ " omsStoreId=" + omsStoreId |
||||
+ " storeId=" + externalStoreId |
||||
+ " requestId=" + requestId |
||||
+ " cost=" + durationMillis + "ms" |
||||
+ " result=" + resultCount |
||||
+ " params=" + params |
||||
+ (failed() ? " error=" + errorType + ": " + errorMessage |
||||
+ " retryable=" + retryable |
||||
+ " platformRequestId=" + platformRequestId |
||||
: "") |
||||
+ '}'; |
||||
} |
||||
|
||||
public static final class Builder { |
||||
|
||||
private Instant occurredAt = Instant.EPOCH; |
||||
private String requestId; |
||||
private ChannelProvider provider; |
||||
private Platform platform; |
||||
private String omsStoreId; |
||||
private String externalStoreId; |
||||
private String operation; |
||||
private CallOutcome outcome = CallOutcome.SUCCESS; |
||||
private long durationMillis; |
||||
private int resultCount = -1; |
||||
private Map<String, Object> params = Collections.emptyMap(); |
||||
private String errorType; |
||||
private String errorMessage; |
||||
private Boolean retryable; |
||||
private String platformRequestId; |
||||
|
||||
public Builder occurredAt(Instant occurredAt) { |
||||
this.occurredAt = occurredAt; |
||||
return this; |
||||
} |
||||
|
||||
public Builder requestId(String requestId) { |
||||
this.requestId = requestId; |
||||
return this; |
||||
} |
||||
|
||||
public Builder provider(ChannelProvider provider) { |
||||
this.provider = provider; |
||||
return this; |
||||
} |
||||
|
||||
public Builder platform(Platform platform) { |
||||
this.platform = platform; |
||||
return this; |
||||
} |
||||
|
||||
public Builder omsStoreId(String omsStoreId) { |
||||
this.omsStoreId = omsStoreId; |
||||
return this; |
||||
} |
||||
|
||||
public Builder externalStoreId(String externalStoreId) { |
||||
this.externalStoreId = externalStoreId; |
||||
return this; |
||||
} |
||||
|
||||
public Builder operation(String operation) { |
||||
this.operation = operation; |
||||
return this; |
||||
} |
||||
|
||||
public Builder outcome(CallOutcome outcome) { |
||||
this.outcome = outcome; |
||||
return this; |
||||
} |
||||
|
||||
public Builder durationMillis(long durationMillis) { |
||||
this.durationMillis = durationMillis; |
||||
return this; |
||||
} |
||||
|
||||
public Builder resultCount(int resultCount) { |
||||
this.resultCount = resultCount; |
||||
return this; |
||||
} |
||||
|
||||
public Builder params(Map<String, Object> params) { |
||||
this.params = params == null ? Collections.<String, Object>emptyMap() : params; |
||||
return this; |
||||
} |
||||
|
||||
public Builder error(Throwable error) { |
||||
if (error != null) { |
||||
this.errorType = error.getClass().getName(); |
||||
this.errorMessage = error.getMessage(); |
||||
if (error instanceof ChannelException) { |
||||
ChannelException channelError = (ChannelException) error; |
||||
this.retryable = channelError.retryable(); |
||||
this.platformRequestId = channelError.requestId(); |
||||
} |
||||
} |
||||
return this; |
||||
} |
||||
|
||||
public CallRecord build() { |
||||
return new CallRecord(this); |
||||
} |
||||
} |
||||
} |
||||
@ -0,0 +1,104 @@
@@ -0,0 +1,104 @@
|
||||
package common.ecommerce.audit; |
||||
|
||||
import org.slf4j.Logger; |
||||
import org.slf4j.LoggerFactory; |
||||
|
||||
import java.time.Instant; |
||||
import java.time.ZoneId; |
||||
import java.time.format.DateTimeFormatter; |
||||
import java.util.Objects; |
||||
|
||||
/** |
||||
* 基于 SLF4J 的默认观察者:成功打 INFO,失败打 WARN。 |
||||
* |
||||
* <p>适合「先把调用链看清」的起步阶段;需要落库审计或接监控时, |
||||
* 换成一个写 {@code IdempotencyStore} / 数据库 / MQ 的 {@link CallObserver} 即可。</p> |
||||
* |
||||
* <p>日志里不包含凭证与报文;凭据只由 {@code ChannelConnection.toString()} 打指纹。</p> |
||||
* |
||||
* <p><b>时间显示</b>:{@link CallRecord} 内部始终是 UTC;这里只负责格式化。 |
||||
* 时区取值优先级:</p> |
||||
* <ol> |
||||
* <li>构造时显式传入的 {@link ZoneId}(推荐,由宿主从配置/环境读取);</li> |
||||
* <li>缺省用 {@link ZoneId#systemDefault()},即 JVM 默认时区 |
||||
* (受 {@code -Duser.timezone}、{@code TZ} 环境变量、容器时区影响)。</li> |
||||
* </ol> |
||||
* |
||||
* <p>注意:容器/CI 里 {@code systemDefault()} 通常是 UTC。想固定成本地时间, |
||||
* 建议显式传 {@code ZoneId.of("Asia/Shanghai")},而不是依赖运行环境。</p> |
||||
*/ |
||||
public final class Slf4jCallObserver implements CallObserver { |
||||
|
||||
private static final Logger LOG = LoggerFactory.getLogger(Slf4jCallObserver.class); |
||||
|
||||
/** 默认时间格式:24 小时制、精确到秒,例如 {@code 2026-11-05 08:00:00}。 */ |
||||
public static final String DEFAULT_TIME_PATTERN = "yyyy-MM-dd HH:mm:ss"; |
||||
|
||||
private final ZoneId zone; |
||||
private final String pattern; |
||||
private final DateTimeFormatter formatter; |
||||
|
||||
/** 使用 JVM 默认时区与默认格式 {@value #DEFAULT_TIME_PATTERN}。 */ |
||||
public Slf4jCallObserver() { |
||||
this(ZoneId.systemDefault()); |
||||
} |
||||
|
||||
/** |
||||
* @param zone 日志展示用的时区;不要传 null |
||||
*/ |
||||
public Slf4jCallObserver(ZoneId zone) { |
||||
this(zone, DEFAULT_TIME_PATTERN); |
||||
} |
||||
|
||||
/** |
||||
* @param zone 日志展示用的时区;不要传 null |
||||
* @param pattern {@link DateTimeFormatter} 格式,如 {@code yyyy-MM-dd HH:mm:ss}; |
||||
* 需要偏移量时用 {@code yyyy-MM-dd HH:mm:ss.SSSXXX} |
||||
*/ |
||||
public Slf4jCallObserver(ZoneId zone, String pattern) { |
||||
this.zone = Objects.requireNonNull(zone, "zone"); |
||||
this.pattern = Objects.requireNonNull(pattern, "pattern"); |
||||
this.formatter = DateTimeFormatter.ofPattern(pattern).withZone(zone); |
||||
} |
||||
|
||||
/** 当前使用的时区,便于启动日志里打印一次。 */ |
||||
public ZoneId zone() { |
||||
return zone; |
||||
} |
||||
|
||||
/** 当前使用的时间格式。 */ |
||||
public String pattern() { |
||||
return pattern; |
||||
} |
||||
|
||||
/** 按当前时区与格式渲染时间;包内可见,便于单测。 */ |
||||
String format(Instant instant) { |
||||
return formatter.format(instant); |
||||
} |
||||
|
||||
@Override |
||||
public void onCall(CallRecord record) { |
||||
if (record.failed()) { |
||||
LOG.warn("sdk-call-failed at={} op={} provider={} platform={} omsStoreId={} storeId={} " |
||||
+ "requestId={} cost={}ms result={} params={} retryable={} platformRequestId={} " |
||||
+ "error={}: {}", |
||||
at(record.occurredAt()), |
||||
record.operation(), record.provider(), record.platform(), |
||||
record.omsStoreId(), record.externalStoreId(), record.requestId(), |
||||
record.durationMillis(), record.resultCount(), record.params(), |
||||
record.retryable(), record.platformRequestId(), |
||||
record.errorType(), record.errorMessage()); |
||||
} else { |
||||
LOG.info("sdk-call at={} op={} provider={} platform={} omsStoreId={} storeId={} " |
||||
+ "requestId={} cost={}ms result={} params={}", |
||||
at(record.occurredAt()), |
||||
record.operation(), record.provider(), record.platform(), |
||||
record.omsStoreId(), record.externalStoreId(), record.requestId(), |
||||
record.durationMillis(), record.resultCount(), record.params()); |
||||
} |
||||
} |
||||
|
||||
private String at(Instant instant) { |
||||
return format(instant); |
||||
} |
||||
} |
||||
@ -0,0 +1,136 @@
@@ -0,0 +1,136 @@
|
||||
package common.ecommerce.sdk; |
||||
|
||||
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.Instant; |
||||
import java.util.Collections; |
||||
import java.util.LinkedHashMap; |
||||
import java.util.Map; |
||||
import java.util.function.Supplier; |
||||
|
||||
/** |
||||
* 门面埋点工具:统计耗时、结果数量与异常,生成 {@link CallRecord} 并回调 |
||||
* {@link CallObserver}。 |
||||
* |
||||
* <p>不是公开 API,只给 core 内部的门面使用。SDK 不写日志目的地, |
||||
* 落库 / 发 MQ / 接监控都交给宿主实现的 {@link CallObserver}。</p> |
||||
* |
||||
* <p><b>约定</b>:</p> |
||||
* <ul> |
||||
* <li>观察者异常一律吞掉并打 WARN,绝不影响业务调用;</li> |
||||
* <li>业务异常原样抛出,不包装、不改变类型;</li> |
||||
* <li>耗时用 {@code ChannelContext} 的时钟,测试注入固定时钟时为 0。</li> |
||||
* </ul> |
||||
*/ |
||||
public final class CallSupport { |
||||
|
||||
private static final Logger LOG = LoggerFactory.getLogger(CallSupport.class); |
||||
|
||||
/** 结果数量不适用(单对象、写操作等)。 */ |
||||
public static final int NO_COUNT = -1; |
||||
|
||||
private CallSupport() { |
||||
} |
||||
|
||||
/** |
||||
* 构造参数摘要,按 {@code key1, value1, key2, value2, ...} 传入。 |
||||
* |
||||
* <p>只放排查用的非敏感摘要(时间窗、分页、游标、数量), |
||||
* 不要放密钥、买家信息、完整报文。</p> |
||||
*/ |
||||
public static Map<String, Object> params(Object... keyValues) { |
||||
if (keyValues == null || keyValues.length == 0) { |
||||
return Collections.emptyMap(); |
||||
} |
||||
if (keyValues.length % 2 != 0) { |
||||
throw new IllegalArgumentException("params must be key/value pairs"); |
||||
} |
||||
Map<String, Object> map = new LinkedHashMap<>(); |
||||
for (int i = 0; i < keyValues.length; i += 2) { |
||||
Object key = keyValues[i]; |
||||
if (key == null) { |
||||
continue; |
||||
} |
||||
map.put(String.valueOf(key), keyValues[i + 1]); |
||||
} |
||||
return map; |
||||
} |
||||
|
||||
/** 从返回值里取结果数量;不适用时返回 {@link #NO_COUNT}。 */ |
||||
public interface ResultSize<T> { |
||||
|
||||
int sizeOf(T result); |
||||
} |
||||
|
||||
/** |
||||
* 执行一次门面调用并记录日志。 |
||||
* |
||||
* @param observer 观察者;null 等价于 {@link CallObserver#NOOP} |
||||
* @param ctx 本次调用上下文(提供账户、链路 ID、时钟) |
||||
* @param operation 操作名,如 {@code salesOrders.pull} |
||||
* @param params 参数摘要,见 {@link #params(Object...)} |
||||
* @param resultSize 结果数量提取器;不关心数量时传 {@code null} |
||||
* @param action 真正的适配器调用 |
||||
*/ |
||||
public static <T> T observe(CallObserver observer, ChannelContext ctx, String operation, |
||||
Map<String, Object> params, ResultSize<T> resultSize, |
||||
Supplier<T> action) { |
||||
CallObserver effective = observer == null ? CallObserver.NOOP : observer; |
||||
Instant startedAt = Instant.now(ctx.clock()); |
||||
long startedMillis = ctx.clock().millis(); |
||||
try { |
||||
T result = action.get(); |
||||
notifyObserver(effective, ctx, operation, params, resultSize, |
||||
result, null, startedAt, startedMillis); |
||||
return result; |
||||
} catch (RuntimeException e) { |
||||
notifyObserver(effective, ctx, operation, params, resultSize, |
||||
null, e, startedAt, startedMillis); |
||||
throw e; |
||||
} |
||||
} |
||||
|
||||
private static <T> void notifyObserver(CallObserver observer, ChannelContext ctx, String operation, |
||||
Map<String, Object> params, ResultSize<T> resultSize, |
||||
T result, RuntimeException error, |
||||
Instant startedAt, long startedMillis) { |
||||
int count = NO_COUNT; |
||||
if (error == null && result != null && resultSize != null) { |
||||
try { |
||||
count = resultSize.sizeOf(result); |
||||
} catch (RuntimeException e) { |
||||
// 提取数量失败不应该影响业务结果,按“不适用”处理
|
||||
count = NO_COUNT; |
||||
} |
||||
} |
||||
|
||||
CallRecord.Builder record = CallRecord.builder() |
||||
.occurredAt(startedAt) |
||||
.requestId(ctx.requestId()) |
||||
.provider(ctx.provider()) |
||||
.platform(ctx.platform()) |
||||
.omsStoreId(ctx.omsStoreId()) |
||||
.externalStoreId(ctx.account().externalStoreId()) |
||||
.operation(operation) |
||||
.durationMillis(Math.max(0L, ctx.clock().millis() - startedMillis)) |
||||
.resultCount(count) |
||||
.params(params); |
||||
if (error == null) { |
||||
record.outcome(CallOutcome.SUCCESS); |
||||
} else { |
||||
record.outcome(CallOutcome.FAILURE).error(error); |
||||
} |
||||
|
||||
try { |
||||
observer.onCall(record.build()); |
||||
} catch (RuntimeException e) { |
||||
// 观察者自己的问题不能影响业务调用,只在自己的日志里留痕
|
||||
LOG.warn("sdk call observer failed, record dropped: op={} requestId={}", |
||||
operation, ctx.requestId(), e); |
||||
} |
||||
} |
||||
} |
||||
Loading…
Reference in new issue