Browse Source

docs: README 补调用日志(审计)一节

新增 3.6,写清「宿主怎么配置才有日志」:

- 最省事:builder().callObserver(new Slf4jCallObserver(ZoneId.of(...)))
  两个门面(ChannelSdk / WarehouseSdk)用法一致
- 不注入 = NOOP,不产生任何日志
- 时区不传则取 systemDefault,容器里通常是 UTC,建议显式指定
- SDK 只依赖 slf4j-api,实现由宿主提供;没绑定时日志被静默丢弃,
  需注意控制台那条 NOP 警告
- 成功(INFO)/ 失败(WARN)的实际输出样式与逐字段说明
- 落库 / MQ / 监控:实现 CallObserver 的三条约束(不抛异常、要快、
  params 不含敏感信息)
- 覆盖范围:全部门面方法,含写操作与回调
- 部分成功用 observeSummary + ResultMapper 区分

顺带更新包结构里 audit 的类清单。

Co-Authored-By: Claude <noreply@anthropic.com>
feature/supplier-lingxing
chenchuchuan 1 week ago
parent
commit
5b4c22db41
  1. 105
      README.md

105
README.md

@ -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=` 会分别体现。
---
## 四、扩展方式

Loading…
Cancel
Save