5.8 KiB
通用注意事项
跨仓通用的约定与踩过的坑。运去哪专属的见 yqn/README.md。
1. 写操作
所有写操作强制幂等
门面层拦截,调用方无法绕过。未注入 IdempotencyStore 时直接抛异常,不提供「无幂等」的降级路径。
原因:出库重复下发 = 重复发货;调拨重复下发 = 搬两次货;销毁重复下发 = 报废两次。
销毁 / 退货按明细行做键
// 退货条目处理:一张单的多行可以分别上架 / 销毁
warehouseCode + providerReturnNo + lineId + process
按整单做键会把「第二行上架」误判成重复。
联调时不要随便跑写接口
写接口会真实创建单据。没有 Testing 环境时,只跑查询类探针。运去哪的 PR 环境可以走单,但创建的单据要能识别(探针用 PROBE-<时间戳> 前缀)。
2. 状态与原始值
rawStatus 必须落库
// 模型的固定搭配
OutboundStatus status; // 归一化,给代码判断
String rawStatus; // 仓方原话,给展示和排查
WarehouseProvider sourceProvider; // 解释 rawStatus 的前提
rawStatus 必须与 sourceProvider 成对保存——同一个数字在不同仓含义不同。 它是映射调整后唯一能重跑、修正历史数据的依据;只存枚举则改映射等于污染存量。
认不出的状态归 UNKNOWN,不猜
反例(已修):
// 之前:contains("SHIP") 把 UNSHIPPED 判成 SHIPPED
// 后果:未发货被判已交运,取消被锁
正确做法:按完整值精确匹配,未收录归 UNKNOWN,原值留在 rawStatus。
底层枚举只追加,不合并
合并了就分不出「待审核」和「审核中」。加新仓时只加值,不改已有值的语义。
3. 时区
仓方给的时间不带时区
yyyy-MM-dd HH:mm:ss 需要知道它属于哪个地方。由调用方经 WarehouseConnection 传:
WarehouseConnection.of(baseUrl, secret, ZoneId.of("America/New_York"))
未指定时按 UTC 解释,不猜成北京时间。 美国仓猜错会整体平移 13–16 小时。
SDK 不读系统时钟
- 普通调用:
WarehouseContext.clock() - 回调时间戳校验:
nowMillis由宿主传入
4. 单位
单位写进字段名,不靠注释约定:
double weightGrams; // 不是 weight
double lengthCm; // 不是 length
Double totalVolumeCbm;
Double totalWeightKg;
换算在适配器里做
仓方给的单位不同(oz / inch / lb / in³),适配器统一换算后落模型,宿主不用各仓处理。
例:运去哪轨迹的 parcel.weight(oz)→ TrackingInfo.parcelWeightGrams()(g)。
单位未核实时要标注
/**
* <b>单位待核实</b>:文档未标单位,这里按 kg 原样透传;
* 若确认是 lb,数值会偏大约 2.2 倍。
*/
5. 字段口径
同一个名字在不同接口含义可能不同
| 字段 | 含义 |
|---|---|
OutboundOrder.providerOrderId |
仓侧单号 |
OutboundQuery.outboundRequestNo |
我们下发的来源单号(原名 providerOrderId 有误导,已改) |
FeeQuery.saleOrderNo |
运去哪要数字单号(providerOrderId),不是来源单号 |
ReturnProcessCommand.lineId |
来自退货查询接口,不是回调 |
传出去了不等于查得回来
下单发的字段,查详情时不一定返回。例:
- 运去哪订单详情不回传
orderRef(平台单号)和requestedAt - 宿主需要这些值时自行保存映射
6. 能力与降级
能力缺失显式抛异常
throw new WarehouseUnsupportedCapabilityException(WarehouseCapability.TRACKING);
不静默返回空集合 / 空列表——调用方分不清「不支持」和「没数据」。
不静默降级
例:平台面单要求仓声明 PLATFORM_LABEL_DELIVERY,缺失时拒绝,不自动退回仓自有面单——面单归属影响标发方式。
能力位要与实现一致
反例(已修):声明了 SPLIT 但接口没有拆单字段。调用方看能力位会以为能用。
7. 校验的位置
跨仓共有的约束放模型构造期
if (b.inventoryType != 0 && b.inventoryType != 1) {
throw new IllegalArgumentException("inventoryType must be 0 or 1");
}
仓方协议特有的约束放适配器
// 尺寸与每页数量联动(运去哪箱标)
if (perPage == 1 && !size.singlePerPage()) { throw ... }
原因:TransferCommand 这类模型承载多家仓字段的并集,在模型里加强制校验会让另一家仓用不了。
8. 回调
见 callback.md。三个要点:
@RequestBody String—— 必须拿原文,反序列化会破坏签名- 验签失败返回 4xx —— 不要吞
Boolean inbound()是三态 —— 不能if (!inbound)
9. 测试
契约测试用 RecordingTransport
RecordingTransport.create().route(PATH, req -> Responses.ok("..."))
验证「按文档构造的报文能正确映射」,不打真实接口。
真机探针默认跳过
@EnabledIfSystemProperty(named = "yqn.probe", matches = "true")
真机验证不能省——运去哪有 4 处文档与实际不符(参数名、成功码、字段缺失),只有真跑才能发现。
10. PII
ShipTo / WarehouseInfo 含联系人、电话、邮箱:
- 不打印完整报文(探针只打字段摘要)
- 落库与日志按宿主安全策略处理
- 异常信息里
safeRelay()只保留前 300 字节
11. 已发现但未修的问题
| 项 | 说明 |
|---|---|
InboundCommand 请求侧部分字段 |
已补,但运去哪对 lineCode 有「项目必须存在」的约束 |
出库 declaredTotal |
运去哪无落点,不影响(行级 skuAmount 已覆盖) |