diff --git a/README.md b/README.md index 94a9690..d52905e 100644 --- a/README.md +++ b/README.md @@ -184,7 +184,8 @@ common.ecommerce │ │ IdempotencyStore(+Claim/Record/Status) / SyncCursorStore / │ │ SecretProvider(已废弃) │ ├── idempotency IdempotencyGuard / WriteScope / WriteResult / WriteAudit -│ ├── audit CallObserver / CallRecord / CallOutcome / Slf4jCallObserver +│ ├── audit CallObserver / CallRecord / CallOutcome / CallSupport / +│ │ ResultSummary / Slf4jCallObserver │ ├── sync SyncSpec / SyncResult │ ├── support Money / PlatformTime / Page / CanonicalKeys │ └── testkit 测试替身(testkit 模块): @@ -774,6 +775,108 @@ result.outcome(); // EXECUTED / ALREADY_COMPLETED `IdempotencyStore.claim` 必须原子(唯一索引 / Redis SETNX),否则并发语义不成立。 `IdempotencyGuard` 不做退避重试,重试节奏由宿主调度决定。 +### 3.6 调用日志(审计) + +SDK 是纯库,**不写数据库、不写文件、不起线程**。需要调用日志时,宿主注入一个 +`CallObserver`,SDK 在**每次门面调用结束**时回调一次(成功与失败都回调)。 + +#### 最省事的写法 + +```java +ChannelSdk sdk = ChannelSdk.builder() + .accountRepository(accountRepo) + .callObserver(new Slf4jCallObserver(ZoneId.of("Asia/Shanghai"))) // ← 关键 + .register(new LingxingAdapterFactory(...)) + .build(); + +WarehouseSdk wh = WarehouseSdk.builder() + .warehouseRepository(repo) + .callObserver(new Slf4jCallObserver(ZoneId.of("Asia/Shanghai"))) + .register(new YqnWarehouseAdapterFactory()) + .build(); +``` + +两个门面的 `callObserver(...)` 用法完全一致,都来自 `common.ecommerce.shared.audit`。 + +| 项 | 说明 | +|:---|:---| +| 不注入 | 默认 `CallObserver.NOOP`,**不产生任何日志** | +| 时区 | `Slf4jCallObserver()` 用 `ZoneId.systemDefault()`;容器里通常是 **UTC**,建议显式传 | +| 日志实现 | SDK 只依赖 `slf4j-api`,**实现由宿主提供**(logback / log4j2 …) | + +> ⚠️ 宿主没有 SLF4J 绑定时,日志会被**静默丢弃**,控制台只会出现 +> `SLF4J: Defaulting to no-operation (NOP) logger implementation`。 +> 启动时建议打一行 `callObserver=...`,确认已注入。 + +#### 输出样式 + +成功打 INFO: + +``` +sdk-call at=2026-11-11 14:37:09 op=warehouse.outbound.create provider=yqn platform=null + omsStoreId=null storeId=RF_NY_US requestId=abc-123 cost=320ms + result=1 failed=0 code=200 params={outboundRequestNo=OB-1} +``` + +失败打 WARN: + +``` +sdk-call-failed at=2026-11-11 14:37:09 op=warehouse.outbound.create provider=yqn ... + requestId=abc-124 cost=210ms result=0 failed=0 code=null + params={outboundRequestNo=OB-2} retryable=false + platformCode=999999 platformRequestId=null + error=PlatformBusinessException: yqn business error: code=999999, message=库存不足 +``` + +| 字段 | 含义 | +|:---|:---| +| `at` | 调用时间(按注入的时区渲染,`CallRecord` 内部恒为 UTC) | +| `op` | 操作名,如 `warehouse.outbound.create` / `channel.salesOrder.pull` | +| `provider` / `platform` / `omsStoreId` / `storeId` | 路由维度 | +| `requestId` | 我方链路 ID,可与业务日志对齐 | +| `cost` | 耗时(ms) | +| `result` / `failed` | 返回条数 / 失败条数(`PARTIAL` 也算 INFO) | +| `code` | 平台业务码 | +| `params` | 入参摘要(**不含密钥、买家姓名、收货地址**) | +| `retryable` / `platformCode` / `platformRequestId` | 仅失败时出现 | +| `error` | 异常类型 + 消息;换行/控制字符会被替换、截断到 512 字符(防 log forging) | + +#### 落库 / 发 MQ / 接监控 + +实现 `CallObserver` 即可: + +```java +public final class DbCallObserver implements CallObserver { + + private final Executor async; + + @Override + public void onCall(CallRecord r) { + // 回调发生在业务线程上,要快;慢操作投递到宿主的异步通道 + async.execute(() -> insert(r)); + } +} +``` + +接口约束(`CallObserver` 的 Javadoc 同时写明): + +- **不要抛异常**。SDK 会兜底捕获并打 WARN,但吞掉异常会掩盖实现问题; +- 回调发生在**业务线程**上,方法应尽快返回; +- `CallRecord.params()` 只是摘要,不要补写密钥、买家姓名、收货地址等敏感信息。 + +#### 覆盖范围 + +全部门面方法都经 `CallSupport.observe`,包括: + +- 查询类(出库 / 入库 / 退货 / 库存 / 费用 / 轨迹 / 仓库目录 / 物流产品) +- **写操作**(创建、取消、审核、删除、条目处理)——失败时不记日志最难排查,已全部覆盖 +- 回调 `sdk.webhook(...)`(operation 为 `warehouse.webhook.parse`,验签失败也能进日志) + +#### 部分成功可以区分 + +需要区分「全部成功 / 部分成功 / 全部失败」时,用 `CallSupport.observeSummary(...)` +并提供 `ResultMapper` 返回 `ResultSummary`,日志里的 `result=` / `failed=` 会分别体现。 + --- ## 四、扩展方式