diff --git a/core/src/main/java/common/ecommerce/audit/CallObserver.java b/core/src/main/java/common/ecommerce/audit/CallObserver.java new file mode 100644 index 0000000..f6b0b2e --- /dev/null +++ b/core/src/main/java/common/ecommerce/audit/CallObserver.java @@ -0,0 +1,29 @@ +package common.ecommerce.audit; + +/** + * SDK 调用观察者:操作日志 / 审计日志的宿主扩展点。 + * + *

SDK 是纯库,不写数据库、不写文件、不起线程。需要把调用记录落库、发 MQ 或接监控时, + * 由宿主实现本接口并注入 {@code ChannelSdk.Builder.callObserver(...)}。

+ * + *

实现约束:

+ * + */ +public interface CallObserver { + + /** 空实现:不记录任何内容,也是默认值。 */ + CallObserver NOOP = record -> { + // 默认不做任何事 + }; + + /** + * 每次门面调用结束后回调一次;成功与失败都会回调。 + * + * @param record 不可变的调用记录 + */ + void onCall(CallRecord record); +} diff --git a/core/src/main/java/common/ecommerce/audit/CallOutcome.java b/core/src/main/java/common/ecommerce/audit/CallOutcome.java new file mode 100644 index 0000000..005e1e2 --- /dev/null +++ b/core/src/main/java/common/ecommerce/audit/CallOutcome.java @@ -0,0 +1,13 @@ +package common.ecommerce.audit; + +/** + * 一次 SDK 调用的结果状态。 + */ +public enum CallOutcome { + + /** 调用成功(适配器没有抛异常)。 */ + SUCCESS, + + /** 调用失败(能力不支持、参数校验、平台返回错误、网络异常等)。 */ + FAILURE +} diff --git a/core/src/main/java/common/ecommerce/audit/CallRecord.java b/core/src/main/java/common/ecommerce/audit/CallRecord.java new file mode 100644 index 0000000..77fdd44 --- /dev/null +++ b/core/src/main/java/common/ecommerce/audit/CallRecord.java @@ -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 调用的操作记录(不可变)。 + * + *

内容只覆盖排查所需的最小集合:调用方是谁、对哪个账户、调了哪个能力、 + * 用了什么摘要参数、耗时、结果数量、失败原因。

+ * + *

敏感信息约定:{@link #params()} 只允许放时间窗、分页、游标、 + * 单号数量这类摘要;密钥、买家姓名、收货地址、完整报文一律不放。 + * SDK 自身绝不会把 {@code ChannelSecret} 写进来。

+ */ +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 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; + } + + /** + * 按宿主时区展示的开始时间。 + * + *

{@link #occurredAt()} 是 {@link Instant},本身就是 UTC,直接 {@code toString()} + * 永远带 {@code Z};要本地时间就用这个方法,例如 + * {@code record.occurredAt(ZoneId.of("Asia/Shanghai"))}。

+ */ + 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 params() { + return params; + } + + /** 失败时的异常类名;成功为 null。 */ + public String errorType() { + return errorType; + } + + /** 失败时的异常消息;成功为 null。 */ + public String errorMessage() { + return errorMessage; + } + + /** + * 是否可重试;仅当失败异常是 {@code ChannelException} 时有值,其余为 null。 + * + *

运维可直接据此决定「重跑」还是「人工介入」。

+ */ + 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 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 params) { + this.params = params == null ? Collections.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); + } + } +} diff --git a/core/src/main/java/common/ecommerce/audit/Slf4jCallObserver.java b/core/src/main/java/common/ecommerce/audit/Slf4jCallObserver.java new file mode 100644 index 0000000..712bb66 --- /dev/null +++ b/core/src/main/java/common/ecommerce/audit/Slf4jCallObserver.java @@ -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。 + * + *

适合「先把调用链看清」的起步阶段;需要落库审计或接监控时, + * 换成一个写 {@code IdempotencyStore} / 数据库 / MQ 的 {@link CallObserver} 即可。

+ * + *

日志里不包含凭证与报文;凭据只由 {@code ChannelConnection.toString()} 打指纹。

+ * + *

时间显示:{@link CallRecord} 内部始终是 UTC;这里只负责格式化。 + * 时区取值优先级:

+ *
    + *
  1. 构造时显式传入的 {@link ZoneId}(推荐,由宿主从配置/环境读取);
  2. + *
  3. 缺省用 {@link ZoneId#systemDefault()},即 JVM 默认时区 + * (受 {@code -Duser.timezone}、{@code TZ} 环境变量、容器时区影响)。
  4. + *
+ * + *

注意:容器/CI 里 {@code systemDefault()} 通常是 UTC。想固定成本地时间, + * 建议显式传 {@code ZoneId.of("Asia/Shanghai")},而不是依赖运行环境。

+ */ +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); + } +} diff --git a/core/src/main/java/common/ecommerce/capability/AfterSales.java b/core/src/main/java/common/ecommerce/capability/AfterSales.java index f932feb..7ac744f 100644 --- a/core/src/main/java/common/ecommerce/capability/AfterSales.java +++ b/core/src/main/java/common/ecommerce/capability/AfterSales.java @@ -1,11 +1,13 @@ package common.ecommerce.capability; +import common.ecommerce.audit.CallObserver; import common.ecommerce.error.ChannelException; import common.ecommerce.model.Capability; import common.ecommerce.model.account.ChannelAccount; import common.ecommerce.model.aftersale.AfterSale; import common.ecommerce.model.aftersale.AfterSaleQuery; import common.ecommerce.model.support.Page; +import common.ecommerce.sdk.CallSupport; import common.ecommerce.sdk.ChannelContext; /** @@ -16,16 +18,35 @@ public final class AfterSales { private final PlatformAdapter adapter; private final ChannelAccount account; private final ChannelContext ctx; + private final CallObserver observer; public AfterSales(PlatformAdapter adapter, ChannelAccount account, ChannelContext ctx) { + this(adapter, account, ctx, CallObserver.NOOP); + } + + public AfterSales(PlatformAdapter adapter, ChannelAccount account, ChannelContext ctx, + CallObserver observer) { this.adapter = adapter; this.account = account; this.ctx = ctx; + this.observer = observer == null ? CallObserver.NOOP : observer; } - public Page pull(AfterSaleQuery query) { - requireAfterSaleCapable(); - return ((AfterSaleCapable) adapter).pull(ctx, query); + public Page pull(final AfterSaleQuery query) { + return CallSupport.observe(observer, ctx, "afterSales.pull", + CallSupport.params( + "startDate", query.startDate(), + "endDate", query.endDate(), + "dateType", query.dateType(), + "typeCount", query.types().size(), + "channelOrderIdCount", query.channelOrderIds().size(), + "pageSize", query.pageSize(), + "cursor", query.cursor()), + page -> page.size(), + () -> { + requireAfterSaleCapable(); + return ((AfterSaleCapable) adapter).pull(ctx, query); + }); } private void requireAfterSaleCapable() { diff --git a/core/src/main/java/common/ecommerce/capability/Outbounds.java b/core/src/main/java/common/ecommerce/capability/Outbounds.java index 3984d18..8ceba1a 100644 --- a/core/src/main/java/common/ecommerce/capability/Outbounds.java +++ b/core/src/main/java/common/ecommerce/capability/Outbounds.java @@ -1,5 +1,6 @@ package common.ecommerce.capability; +import common.ecommerce.audit.CallObserver; import common.ecommerce.error.ChannelException; import common.ecommerce.model.Capability; import common.ecommerce.model.account.ChannelAccount; @@ -11,6 +12,7 @@ import common.ecommerce.model.fulfillment.OutboundResult; import common.ecommerce.model.fulfillment.ShipmentReviewResult; import common.ecommerce.model.fulfillment.ShippingLabel; import common.ecommerce.model.support.Page; +import common.ecommerce.sdk.CallSupport; import common.ecommerce.sdk.ChannelContext; import java.util.List; @@ -26,39 +28,81 @@ public final class Outbounds { private final PlatformAdapter adapter; private final ChannelAccount account; private final ChannelContext ctx; + private final CallObserver observer; public Outbounds(PlatformAdapter adapter, ChannelAccount account, ChannelContext ctx) { + this(adapter, account, ctx, CallObserver.NOOP); + } + + public Outbounds(PlatformAdapter adapter, ChannelAccount account, ChannelContext ctx, + CallObserver observer) { this.adapter = adapter; this.account = account; this.ctx = ctx; + this.observer = observer == null ? CallObserver.NOOP : observer; } - public boolean submit(List packages) { - requireOutboundCapable(); - return ((OutboundCapable) adapter).submit(ctx, packages); + public boolean submit(final List packages) { + return CallSupport.observe(observer, ctx, "outbounds.submit", + CallSupport.params("packageCount", packages == null ? 0 : packages.size()), + result -> CallSupport.NO_COUNT, + () -> { + requireOutboundCapable(); + return ((OutboundCapable) adapter).submit(ctx, packages); + }); } - public OutboundResult results(List globalOrderNos) { - requireOutboundCapable(); - return ((OutboundCapable) adapter).results(ctx, globalOrderNos); + public OutboundResult results(final List globalOrderNos) { + return CallSupport.observe(observer, ctx, "outbounds.results", + CallSupport.params("orderCount", globalOrderNos == null ? 0 : globalOrderNos.size()), + result -> CallSupport.NO_COUNT, + () -> { + requireOutboundCapable(); + return ((OutboundCapable) adapter).results(ctx, globalOrderNos); + }); } /** 销售出库单列表。 */ - public Page pull(OutboundOrderQuery query) { - require(Capability.OUTBOUND_ORDER, OutboundOrderCapable.class); - return ((OutboundOrderCapable) adapter).pull(ctx, query); + public Page pull(final OutboundOrderQuery query) { + return CallSupport.observe(observer, ctx, "outbounds.pull", + CallSupport.params( + "after", query.after(), + "before", query.before(), + "timeType", query.timeType(), + "sidCount", query.sids().size(), + "statuses", query.statuses(), + "logisticsStatuses", query.logisticsStatuses(), + "pageSize", query.pageSize(), + "cursor", query.cursor()), + page -> page.size(), + () -> { + require(Capability.OUTBOUND_ORDER, OutboundOrderCapable.class); + return ((OutboundOrderCapable) adapter).pull(ctx, query); + }); } /** 销售出库单物流面单。 */ - public List labels(LabelQuery query) { - require(Capability.LABEL, ShippingLabelCapable.class); - return ((ShippingLabelCapable) adapter).labels(ctx, query); + public List labels(final LabelQuery query) { + return CallSupport.observe(observer, ctx, "outbounds.labels", + CallSupport.params( + "woCount", query.woNumbers().size(), + "orderCount", query.orderNumbers().size()), + labels -> labels.size(), + () -> { + require(Capability.LABEL, ShippingLabelCapable.class); + return ((ShippingLabelCapable) adapter).labels(ctx, query); + }); } /** 审核发货(写操作,调用方需包在 {@code sdk.writes()} 里)。 */ - public ShipmentReviewResult review(List globalOrderNos) { - require(Capability.SHIPMENT_REVIEW, ShipmentReviewCapable.class); - return ((ShipmentReviewCapable) adapter).review(ctx, globalOrderNos); + public ShipmentReviewResult review(final List globalOrderNos) { + return CallSupport.observe(observer, ctx, "outbounds.review", + CallSupport.params("orderCount", globalOrderNos == null ? 0 : globalOrderNos.size()), + result -> CallSupport.NO_COUNT, + () -> { + require(Capability.SHIPMENT_REVIEW, ShipmentReviewCapable.class); + return ((ShipmentReviewCapable) adapter).review(ctx, globalOrderNos); + }); } private void requireOutboundCapable() { diff --git a/core/src/main/java/common/ecommerce/capability/Products.java b/core/src/main/java/common/ecommerce/capability/Products.java index 19a16fb..adb8994 100644 --- a/core/src/main/java/common/ecommerce/capability/Products.java +++ b/core/src/main/java/common/ecommerce/capability/Products.java @@ -1,5 +1,6 @@ package common.ecommerce.capability; +import common.ecommerce.audit.CallObserver; import common.ecommerce.error.ChannelException; import common.ecommerce.model.Capability; import common.ecommerce.model.account.ChannelAccount; @@ -7,6 +8,7 @@ import common.ecommerce.model.support.Page; import common.ecommerce.model.product.ProductListing; import common.ecommerce.model.product.ProductQuery; import common.ecommerce.model.product.ProductRef; +import common.ecommerce.sdk.CallSupport; import common.ecommerce.sdk.ChannelContext; /** 门面持有的商品视图。 */ @@ -15,21 +17,45 @@ public final class Products { private final PlatformAdapter adapter; private final ChannelAccount account; private final ChannelContext ctx; + private final CallObserver observer; public Products(PlatformAdapter adapter, ChannelAccount account, ChannelContext ctx) { + this(adapter, account, ctx, CallObserver.NOOP); + } + + public Products(PlatformAdapter adapter, ChannelAccount account, ChannelContext ctx, + CallObserver observer) { this.adapter = adapter; this.account = account; this.ctx = ctx; + this.observer = observer == null ? CallObserver.NOOP : observer; } - public Page pull(ProductQuery query) { - requireProductCapable(); - return ((ProductCapable) adapter).pull(ctx, query); + public Page pull(final ProductQuery query) { + return CallSupport.observe(observer, ctx, "products.pull", + CallSupport.params( + "updatedAfter", query.updatedAfter(), + "updatedBefore", query.updatedBefore(), + "pageSize", query.pageSize(), + "cursor", query.cursor(), + "searchField", query.searchField(), + "searchValue", query.searchValue(), + "searchValueCount", query.searchValues().size()), + page -> page.size(), + () -> { + requireProductCapable(); + return ((ProductCapable) adapter).pull(ctx, query); + }); } - public ProductListing get(String platformSku) { - requireProductCapable(); - return ((ProductCapable) adapter).get(ctx, ProductRef.of(platformSku)); + public ProductListing get(final String platformSku) { + return CallSupport.observe(observer, ctx, "products.get", + CallSupport.params("platformSku", platformSku), + result -> 1, + () -> { + requireProductCapable(); + return ((ProductCapable) adapter).get(ctx, ProductRef.of(platformSku)); + }); } private void requireProductCapable() { diff --git a/core/src/main/java/common/ecommerce/capability/SalesOrders.java b/core/src/main/java/common/ecommerce/capability/SalesOrders.java index fad45d2..5fcb3d3 100644 --- a/core/src/main/java/common/ecommerce/capability/SalesOrders.java +++ b/core/src/main/java/common/ecommerce/capability/SalesOrders.java @@ -1,49 +1,81 @@ package common.ecommerce.capability; +import common.ecommerce.audit.CallObserver; +import common.ecommerce.error.ChannelException; import common.ecommerce.model.Capability; import common.ecommerce.model.account.ChannelAccount; -import common.ecommerce.error.ChannelException; import common.ecommerce.model.fulfillment.OrderEditRequest; import common.ecommerce.model.fulfillment.OrderEditResult; import common.ecommerce.model.order.SalesOrder; import common.ecommerce.model.order.SalesOrderQuery; import common.ecommerce.model.order.SalesOrderRef; import common.ecommerce.model.support.Page; +import common.ecommerce.sdk.CallSupport; import common.ecommerce.sdk.ChannelContext; import java.util.List; /** * 门面持有的销售订单视图。调用前做能力检查,缺失时显式拒绝。 + * + *

每次调用都会生成一条 {@code CallRecord} 交给 {@link CallObserver}, + * 默认是空实现,注入方式见 {@code ChannelSdk.Builder#callObserver}。

*/ public final class SalesOrders { private final PlatformAdapter adapter; private final ChannelAccount account; private final ChannelContext ctx; + private final CallObserver observer; public SalesOrders(PlatformAdapter adapter, ChannelAccount account, ChannelContext ctx) { + this(adapter, account, ctx, CallObserver.NOOP); + } + + public SalesOrders(PlatformAdapter adapter, ChannelAccount account, ChannelContext ctx, + CallObserver observer) { this.adapter = adapter; this.account = account; this.ctx = ctx; + this.observer = observer == null ? CallObserver.NOOP : observer; } - public Page pull(SalesOrderQuery query) { - requireSalesOrderCapable(); - return ((SalesOrderCapable) adapter).pull(ctx, query); + public Page pull(final SalesOrderQuery query) { + return CallSupport.observe(observer, ctx, "salesOrders.pull", + CallSupport.params( + "updatedAfter", query.updatedAfter(), + "updatedBefore", query.updatedBefore(), + "pageSize", query.pageSize(), + "cursor", query.cursor()), + page -> page.size(), + () -> { + requireSalesOrderCapable(); + return ((SalesOrderCapable) adapter).pull(ctx, query); + }); } - public SalesOrder get(String channelOrderId) { - requireSalesOrderCapable(); - return ((SalesOrderCapable) adapter).get(ctx, SalesOrderRef.of(channelOrderId)); + public SalesOrder get(final String channelOrderId) { + return CallSupport.observe(observer, ctx, "salesOrders.get", + CallSupport.params("channelOrderId", channelOrderId), + result -> 1, + () -> { + requireSalesOrderCapable(); + return ((SalesOrderCapable) adapter).get(ctx, SalesOrderRef.of(channelOrderId)); + }); } /** 批量编辑订单(写操作,调用方需包在 {@code sdk.writes()} 里)。 */ - public OrderEditResult edit(List requests) { - if (!adapter.supports(account, Capability.ORDER_EDIT) || !(adapter instanceof OrderEditCapable)) { - throw new ChannelException.UnsupportedCapabilityException(Capability.ORDER_EDIT); - } - return ((OrderEditCapable) adapter).edit(ctx, requests); + public OrderEditResult edit(final List requests) { + return CallSupport.observe(observer, ctx, "salesOrders.edit", + CallSupport.params("requestCount", requests == null ? 0 : requests.size()), + result -> CallSupport.NO_COUNT, + () -> { + if (!adapter.supports(account, Capability.ORDER_EDIT) + || !(adapter instanceof OrderEditCapable)) { + throw new ChannelException.UnsupportedCapabilityException(Capability.ORDER_EDIT); + } + return ((OrderEditCapable) adapter).edit(ctx, requests); + }); } private void requireSalesOrderCapable() { diff --git a/core/src/main/java/common/ecommerce/capability/Settlements.java b/core/src/main/java/common/ecommerce/capability/Settlements.java index 9f6e110..790af8a 100644 --- a/core/src/main/java/common/ecommerce/capability/Settlements.java +++ b/core/src/main/java/common/ecommerce/capability/Settlements.java @@ -1,11 +1,13 @@ package common.ecommerce.capability; +import common.ecommerce.audit.CallObserver; import common.ecommerce.error.ChannelException; import common.ecommerce.model.Capability; import common.ecommerce.model.account.ChannelAccount; import common.ecommerce.model.settlement.SettlementQuery; import common.ecommerce.model.settlement.SettlementTransaction; import common.ecommerce.model.support.Page; +import common.ecommerce.sdk.CallSupport; import common.ecommerce.sdk.ChannelContext; /** @@ -16,16 +18,38 @@ public final class Settlements { private final PlatformAdapter adapter; private final ChannelAccount account; private final ChannelContext ctx; + private final CallObserver observer; public Settlements(PlatformAdapter adapter, ChannelAccount account, ChannelContext ctx) { + this(adapter, account, ctx, CallObserver.NOOP); + } + + public Settlements(PlatformAdapter adapter, ChannelAccount account, ChannelContext ctx, + CallObserver observer) { this.adapter = adapter; this.account = account; this.ctx = ctx; + this.observer = observer == null ? CallObserver.NOOP : observer; } - public Page pull(SettlementQuery query) { - requireSettlementCapable(); - return ((SettlementCapable) adapter).pull(ctx, query); + public Page pull(final SettlementQuery query) { + return CallSupport.observe(observer, ctx, "settlements.pull", + CallSupport.params( + "settledAfter", query.settledAfter(), + "settledBefore", query.settledBefore(), + "modifiedAfter", query.modifiedAfter(), + "modifiedBefore", query.modifiedBefore(), + "eventType", query.eventType(), + "transactionType", query.transactionType(), + "searchField", query.searchField(), + "searchValueCount", query.searchValues().size(), + "pageSize", query.pageSize(), + "cursor", query.cursor()), + page -> page.size(), + () -> { + requireSettlementCapable(); + return ((SettlementCapable) adapter).pull(ctx, query); + }); } private void requireSettlementCapable() { diff --git a/core/src/main/java/common/ecommerce/sdk/CallSupport.java b/core/src/main/java/common/ecommerce/sdk/CallSupport.java new file mode 100644 index 0000000..8300416 --- /dev/null +++ b/core/src/main/java/common/ecommerce/sdk/CallSupport.java @@ -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}。 + * + *

不是公开 API,只给 core 内部的门面使用。SDK 不写日志目的地, + * 落库 / 发 MQ / 接监控都交给宿主实现的 {@link CallObserver}。

+ * + *

约定:

+ *
    + *
  • 观察者异常一律吞掉并打 WARN,绝不影响业务调用;
  • + *
  • 业务异常原样抛出,不包装、不改变类型;
  • + *
  • 耗时用 {@code ChannelContext} 的时钟,测试注入固定时钟时为 0。
  • + *
+ */ +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, ...} 传入。 + * + *

只放排查用的非敏感摘要(时间窗、分页、游标、数量), + * 不要放密钥、买家信息、完整报文。

+ */ + public static Map 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 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 { + + 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 observe(CallObserver observer, ChannelContext ctx, String operation, + Map params, ResultSize resultSize, + Supplier 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 void notifyObserver(CallObserver observer, ChannelContext ctx, String operation, + Map params, ResultSize 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); + } + } +} diff --git a/core/src/main/java/common/ecommerce/sdk/ChannelSdk.java b/core/src/main/java/common/ecommerce/sdk/ChannelSdk.java index 47aff82..b27cd9e 100644 --- a/core/src/main/java/common/ecommerce/sdk/ChannelSdk.java +++ b/core/src/main/java/common/ecommerce/sdk/ChannelSdk.java @@ -1,6 +1,7 @@ package common.ecommerce.sdk; import common.ecommerce.model.Platform; +import common.ecommerce.audit.CallObserver; import common.ecommerce.capability.AdapterCapabilityReport; import common.ecommerce.capability.AfterSales; import common.ecommerce.capability.AggregatorCapable; @@ -86,6 +87,14 @@ public final class ChannelSdk implements ProviderResolver { */ private final IdempotencyGuard idempotencyGuard; + /** + * 调用观察者(操作日志)。 + * + *

默认 {@link CallObserver#NOOP};注入后每次门面调用结束都会回调一条 + * {@code CallRecord},成功与失败都记。

+ */ + private final CallObserver callObserver; + private ChannelSdk(Builder b) { this.adapters = Collections.unmodifiableMap(new LinkedHashMap(b.adapters)); this.accountRepository = b.accountRepository; @@ -93,6 +102,7 @@ public final class ChannelSdk implements ProviderResolver { this.idempotencyGuard = b.idempotencyStore == null ? null : new IdempotencyGuard(b.idempotencyStore, b.idempotencyOwner, b.clock, IdempotencyGuard.DEFAULT_CLAIM_TTL_SECONDS); + this.callObserver = b.callObserver == null ? CallObserver.NOOP : b.callObserver; } public static Builder builder() { @@ -122,7 +132,7 @@ public final class ChannelSdk implements ProviderResolver { */ public SalesOrders salesOrders(AccountKey key, ChannelConnection connection) { ChannelAccount account = requireAccount(key); - return new SalesOrders(resolve(key), account, newContext(account, connection)); + return new SalesOrders(resolve(key), account, newContext(account, connection), callObserver); } /** @@ -132,13 +142,13 @@ public final class ChannelSdk implements ProviderResolver { */ public Products products(AccountKey key, ChannelConnection connection) { ChannelAccount account = requireAccount(key); - return new Products(resolve(key), account, newContext(account, connection)); + return new Products(resolve(key), account, newContext(account, connection), callObserver); } /** 结算 / 账单交易明细视图。 */ public Settlements settlements(AccountKey key, ChannelConnection connection) { ChannelAccount account = requireAccount(key); - return new Settlements(resolve(key), account, newContext(account, connection)); + return new Settlements(resolve(key), account, newContext(account, connection), callObserver); } /** @@ -149,7 +159,7 @@ public final class ChannelSdk implements ProviderResolver { */ public AfterSales afterSales(AccountKey key, ChannelConnection connection) { ChannelAccount account = requireAccount(key); - return new AfterSales(resolve(key), account, newContext(account, connection)); + return new AfterSales(resolve(key), account, newContext(account, connection), callObserver); } /** @@ -159,7 +169,7 @@ public final class ChannelSdk implements ProviderResolver { */ public Outbounds outbounds(AccountKey key, ChannelConnection connection) { ChannelAccount account = requireAccount(key); - return new Outbounds(resolve(key), account, newContext(account, connection)); + return new Outbounds(resolve(key), account, newContext(account, connection), callObserver); } /** @@ -172,11 +182,17 @@ public final class ChannelSdk implements ProviderResolver { */ public List subChannels(AccountKey key, ChannelConnection connection) { ChannelAccount account = requireAccount(key); - PlatformAdapter adapter = resolve(key); - if (!(adapter instanceof AggregatorCapable)) { - throw new IllegalStateException("adapter is not an aggregator: " + key); - } - return ((AggregatorCapable) adapter).listSubChannels(newContext(account, connection)); + final PlatformAdapter adapter = resolve(key); + final ChannelContext ctx = newContext(account, connection); + return CallSupport.observe(callObserver, ctx, "subChannels.list", + CallSupport.params("endpoint", connection.endpointBaseUrl()), + channels -> channels.size(), + () -> { + if (!(adapter instanceof AggregatorCapable)) { + throw new IllegalStateException("adapter is not an aggregator: " + key); + } + return ((AggregatorCapable) adapter).listSubChannels(ctx); + }); } /** @@ -249,6 +265,9 @@ public final class ChannelSdk implements ProviderResolver { /** 幂等抢占方标识,多实例部署时应能区分;缺省随机 UUID。 */ private String idempotencyOwner = UUID.randomUUID().toString(); + /** 调用观察者,默认不记录。 */ + private CallObserver callObserver = CallObserver.NOOP; + /** 时钟,默认 UTC;测试注入固定时钟。 */ private Clock clock = Clock.systemUTC(); @@ -292,6 +311,22 @@ public final class ChannelSdk implements ProviderResolver { } /** + * 注入调用观察者(操作日志 / 审计日志)。 + * + *

每次门面调用结束回调一次 {@code CallRecord},成功与失败都记; + * 不注入时为空实现,不做任何记录。SDK 不落盘、不起线程, + * 落库 / MQ / 监控由宿主在 {@link CallObserver#onCall} 里实现。

+ * + *

最省事的写法是 {@code callObserver(new Slf4jCallObserver())}; + * 需要审计时实现自己的 {@link CallObserver}。观察者抛出的异常会被吞掉并打 WARN, + * 不会影响业务调用。

+ */ + public Builder callObserver(CallObserver callObserver) { + this.callObserver = callObserver; + return this; + } + + /** * 注册适配器工厂。 * *

生产推荐这种写法:工厂在 {@link #build()} 时调用 {@code create(...)},