Browse Source

feat(observability): 增加 SDK 调用日志与审计扩展点

- 新增 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
lml 2 weeks ago
parent
commit
cb9c04c80f
  1. 29
      core/src/main/java/common/ecommerce/audit/CallObserver.java
  2. 13
      core/src/main/java/common/ecommerce/audit/CallOutcome.java
  3. 278
      core/src/main/java/common/ecommerce/audit/CallRecord.java
  4. 104
      core/src/main/java/common/ecommerce/audit/Slf4jCallObserver.java
  5. 27
      core/src/main/java/common/ecommerce/capability/AfterSales.java
  6. 74
      core/src/main/java/common/ecommerce/capability/Outbounds.java
  7. 38
      core/src/main/java/common/ecommerce/capability/Products.java
  8. 56
      core/src/main/java/common/ecommerce/capability/SalesOrders.java
  9. 30
      core/src/main/java/common/ecommerce/capability/Settlements.java
  10. 136
      core/src/main/java/common/ecommerce/sdk/CallSupport.java
  11. 55
      core/src/main/java/common/ecommerce/sdk/ChannelSdk.java

29
core/src/main/java/common/ecommerce/audit/CallObserver.java

@ -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);
}

13
core/src/main/java/common/ecommerce/audit/CallOutcome.java

@ -0,0 +1,13 @@ @@ -0,0 +1,13 @@
package common.ecommerce.audit;
/**
* 一次 SDK 调用的结果状态。
*/
public enum CallOutcome {
/** 调用成功(适配器没有抛异常)。 */
SUCCESS,
/** 调用失败(能力不支持、参数校验、平台返回错误、网络异常等)。 */
FAILURE
}

278
core/src/main/java/common/ecommerce/audit/CallRecord.java

@ -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);
}
}
}

104
core/src/main/java/common/ecommerce/audit/Slf4jCallObserver.java

@ -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);
}
}

27
core/src/main/java/common/ecommerce/capability/AfterSales.java

@ -1,11 +1,13 @@ @@ -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 { @@ -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<AfterSale> pull(AfterSaleQuery query) {
requireAfterSaleCapable();
return ((AfterSaleCapable) adapter).pull(ctx, query);
public Page<AfterSale> 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() {

74
core/src/main/java/common/ecommerce/capability/Outbounds.java

@ -1,5 +1,6 @@ @@ -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; @@ -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 { @@ -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<OutboundPackage> packages) {
requireOutboundCapable();
return ((OutboundCapable) adapter).submit(ctx, packages);
public boolean submit(final List<OutboundPackage> 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<String> globalOrderNos) {
requireOutboundCapable();
return ((OutboundCapable) adapter).results(ctx, globalOrderNos);
public OutboundResult results(final List<String> 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<OutboundOrder> pull(OutboundOrderQuery query) {
require(Capability.OUTBOUND_ORDER, OutboundOrderCapable.class);
return ((OutboundOrderCapable) adapter).pull(ctx, query);
public Page<OutboundOrder> 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<ShippingLabel> labels(LabelQuery query) {
require(Capability.LABEL, ShippingLabelCapable.class);
return ((ShippingLabelCapable) adapter).labels(ctx, query);
public List<ShippingLabel> 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<String> globalOrderNos) {
require(Capability.SHIPMENT_REVIEW, ShipmentReviewCapable.class);
return ((ShipmentReviewCapable) adapter).review(ctx, globalOrderNos);
public ShipmentReviewResult review(final List<String> 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() {

38
core/src/main/java/common/ecommerce/capability/Products.java

@ -1,5 +1,6 @@ @@ -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; @@ -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 { @@ -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<ProductListing> pull(ProductQuery query) {
requireProductCapable();
return ((ProductCapable) adapter).pull(ctx, query);
public Page<ProductListing> 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() {

56
core/src/main/java/common/ecommerce/capability/SalesOrders.java

@ -1,49 +1,81 @@ @@ -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;
/**
* 门面持有的销售订单视图。调用前做能力检查,缺失时显式拒绝。
*
* <p>每次调用都会生成一条 {@code CallRecord} 交给 {@link CallObserver},
* 默认是空实现,注入方式见 {@code ChannelSdk.Builder#callObserver}。</p>
*/
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<SalesOrder> pull(SalesOrderQuery query) {
requireSalesOrderCapable();
return ((SalesOrderCapable) adapter).pull(ctx, query);
public Page<SalesOrder> 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<OrderEditRequest> 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<OrderEditRequest> 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() {

30
core/src/main/java/common/ecommerce/capability/Settlements.java

@ -1,11 +1,13 @@ @@ -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 { @@ -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<SettlementTransaction> pull(SettlementQuery query) {
requireSettlementCapable();
return ((SettlementCapable) adapter).pull(ctx, query);
public Page<SettlementTransaction> 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() {

136
core/src/main/java/common/ecommerce/sdk/CallSupport.java

@ -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);
}
}
}

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

@ -1,6 +1,7 @@ @@ -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 { @@ -86,6 +87,14 @@ public final class ChannelSdk implements ProviderResolver {
*/
private final IdempotencyGuard idempotencyGuard;
/**
* 调用观察者(操作日志)。
*
* <p>默认 {@link CallObserver#NOOP};注入后每次门面调用结束都会回调一条
* {@code CallRecord},成功与失败都记。</p>
*/
private final CallObserver callObserver;
private ChannelSdk(Builder b) {
this.adapters = Collections.unmodifiableMap(new LinkedHashMap<String, PlatformAdapter>(b.adapters));
this.accountRepository = b.accountRepository;
@ -93,6 +102,7 @@ public final class ChannelSdk implements ProviderResolver { @@ -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 { @@ -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 { @@ -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 { @@ -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 { @@ -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 { @@ -172,11 +182,17 @@ public final class ChannelSdk implements ProviderResolver {
*/
public List<AggregatorCapable.SubChannel> 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 { @@ -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 { @@ -292,6 +311,22 @@ public final class ChannelSdk implements ProviderResolver {
}
/**
* 注入调用观察者(操作日志 / 审计日志)。
*
* <p>每次门面调用结束回调一次 {@code CallRecord},成功与失败都记;
* 不注入时为空实现,不做任何记录。SDK 不落盘、不起线程,
* 落库 / MQ / 监控由宿主在 {@link CallObserver#onCall} 里实现。</p>
*
* <p>最省事的写法是 {@code callObserver(new Slf4jCallObserver())};
* 需要审计时实现自己的 {@link CallObserver}。观察者抛出的异常会被吞掉并打 WARN,
* 不会影响业务调用。</p>
*/
public Builder callObserver(CallObserver callObserver) {
this.callObserver = callObserver;
return this;
}
/**
* 注册适配器工厂。
*
* <p>生产推荐这种写法:工厂在 {@link #build()} 时调用 {@code create(...)},

Loading…
Cancel
Save