|
|
|
|
@ -184,7 +184,8 @@ common.ecommerce
@@ -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
@@ -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=` 会分别体现。 |
|
|
|
|
|
|
|
|
|
--- |
|
|
|
|
|
|
|
|
|
## 四、扩展方式 |
|
|
|
|
|