16 KiB
接入新三方仓:操作清单
按这个顺序做,每一步都有验收标准。以运去哪(YQN)和信仓(Xincang)的实践为基准。
阶段 0:先确认三件事
| 要确认 | 为什么 |
|---|---|
| 接口文档(含回调) | 没回调文档就不能接退货 / 状态同步 |
| 测试环境(域名 + 凭证 + 测试仓 + 测试 SKU) | 没有真机验证的接口一律视为未验证 |
| 能不能走写操作 | PR 环境能否真实建单,决定探针怎么设计 |
缺一项就先做只读部分,写接口留空并标注。
阶段 1:模块骨架
1.1 建模块
warehouse-sdk-<name>/
├── pom.xml 依赖 warehouse-sdk-core + sdk-common
└── src/main/java/common/ecommerce/<name>/
├── <Name>Constants.java 端点、路径、限流、固定请求头名
├── <Name>Adapter.java 实现各 capability
├── <Name>AdapterFactory.java
├── adapter/ 各接口的 Mapper(一个接口一个 Mapper)
├── dto/ 一个接口一个文件,不建大而全的 Dtos
├── enums/ 平台枚举(带仓方原值 + toCore())
├── http/ 请求构造 / 限流 / 信封校验
└── webhook/ 回调验签与解析
验收:模块能编译,mvn -pl warehouse-sdk-<name> -am install 通过。
1.2 注册
WarehouseSdk.builder()
.warehouseRepository(repo)
.callObserver(new Slf4jCallObserver(ZoneId.of("Asia/Shanghai"))) // 别漏
.register(new <Name>AdapterFactory())
.build();
阶段 2:按接口逐个接(每个接口一套动作)
以「创建出库单」为例,每个接口都要走完这 6 步:
2.1 定义 DTO
dto/<Name><Api>Dtos.java,一个接口一个文件,不塞进大 DTO。
public final class YqnCreateOrderDtos {
public static final class CreateOrderRequest { ... } // 请求
public static final class CreateOrderResponse { ... } // 响应 data
}
- 字段名照抄文档,连拼写错误也照抄(运去哪的
hopeDestroyData就是Data不是Date) - 保留
@JsonInclude(NON_NULL)——丢了会让请求多出"field": null
2.2 建 Mapper
adapter/<Name><Api>Mapper.java,只做字段搬运。
规则:
- 平台字段名只出现在 Mapper 和 DTO 里
- 单位换算在这里做(oz→g、inch→cm),宿主不用各仓处理
- 时间解析失败返回 null,不因格式问题阻断整单
2.3 定义平台枚举(有状态/码表时)
enums/<Name>XxxStatus.java:
public enum YqnOutboundStatus {
UNSHIPPED("unshipped", OutboundStatus.SUBMITTED),
SHIPPED("shipped", OutboundStatus.SHIPPED),
UNKNOWN(null, OutboundStatus.UNKNOWN); // 认不出就归 UNKNOWN,不猜
public static OutboundStatus toCore(String raw) { ... }
}
规则:
- 精确匹配,不用
contains——运去哪的UNSHIPPED曾被contains("SHIP")判成已交运 - 原值同时写进模型的
rawStatus - 底层枚举只追加不合并
2.4 实现 Capability 方法
@Override
public OutboundReceipt create(WarehouseContext ctx, OutboundCommand cmd) {
YqnCreateOrderDtos.CreateOrderRequest body = YqnOutboundMapper.toRequest(cmd, wh, zoneOf(ctx));
String raw = execute(ctx, PATH, body, "warehouse.outbound.create");
return YqnOutboundMapper.toReceipt(raw, cmd);
}
- 能力位要与实现一致(声明了
SPLIT就必须真的有拆单字段) - 未实现的能力显式抛
WarehouseUnsupportedCapabilityException,不返回空集合 - 找不到的必填字段在本地拒绝,发出去被仓方拒更难排查
2.5 门面包一层
WarehouseOperations 里:
return CallSupport.observe(observer, ctx, "warehouse.outbound.create",
CallSupport.params("outboundRequestNo", cmd.outboundRequestNo()),
r -> CallSupport.NO_COUNT,
() -> guard.execute(...)); // 写操作必须走幂等守卫
写完用脚本扫一遍:确认新方法都包了 CallSupport.observe。
2.6 写测试
<Name><Api>Test.java,用 RecordingTransport 打桩:
| 必须覆盖 | 例子 |
|---|---|
| 请求报文形状 | 断每个关键字段出现在 body 里 |
| 响应字段映射 | 逐字段断言 |
| 枚举全量映射 | 文档里每个状态值都测一遍 |
| 未知值兜底 | 未知状态 → UNKNOWN,rawStatus 保留 |
| 错误路径 | 4xx / 业务码失败 / 空 body |
阶段 2.5:出入参怎么处理(详述)
三层各管什么
仓方 JSON ──(DTO)──► 平台对象 ──(Mapper)──► 标准模型
原样照抄字段名 单位换算/码值映射 跨仓统一
只管反序列化 才允许写业务逻辑 宿主只依赖这层
| 层 | 位置 | 允许做的事 | 禁止的事 |
|---|---|---|---|
| DTO | <name>/dto/ |
字段声明、@JsonProperty 改映射 |
任何逻辑、任何默认值 |
| Mapper | <name>/adapter/ |
单位换算、码值映射、字段拼装 | 发请求、读配置 |
| 标准模型 | warehouse-sdk-core/model/ |
校验跨仓共有约束 | 认识任何仓的字段名 |
判断标准:标准模型里出现 yqn / unshipped / hopeDestroyData 这类字符串,就是泄漏了。
入参(标准 → 平台)
顺序:先看标准模型有什么 → 再看平台要什么 → 缺的补哪边。
public static YqnCreateOrderDtos.CreateOrderRequest toRequest(OutboundCommand cmd, String warehouseCode, ZoneId zone) {
YqnCreateOrderDtos.CreateOrderRequest req = new YqnCreateOrderDtos.CreateOrderRequest();
req.orderNo = cmd.outboundRequestNo(); // ① 直接搬
req.latestShipDate = formatTime(cmd.latestShipDate(), zone); // ② 需要换算
req.isPrime = isPrimeOf(cmd.sfp()); // ③ 需要映射
req.attachInfoItems = toAttachInfoItems(cmd, warehouseCode); // ④ 需要拼装
return req;
}
四种情况分别处理:
| 情况 | 做法 |
|---|---|
| 字段一一对应 | 直接赋值 |
| 需要换算(单位 / 时间格式) | 在 Mapper 里换,写明换算系数 |
| 需要码值映射 | 用平台枚举的 codeOf(),不用裸数字 |
| 平台没有该字段 | 不静默丢弃:要么在模型上标「平台不支持」,要么抛异常 |
| 平台有多余必填字段 | 标准模型必须有对应入口,别让调用方拼字符串 |
坑:
- 平台字段名有拼写错误(运去哪
hopeDestroyData)→ 照抄,加注释说明不是笔误 - 平台要求字符串但标准是数字(运去哪
qty)→ 在 Mapper 转,别改模型类型 - 平台有默认值(
currency不填默认 USD)→ 别在模型里预填,交给平台
出参(平台 → 标准)
public static OutboundOrder toOrder(YqnOrderDetailDtos.OrderDetail detail, ..., ZoneId zone) {
return OutboundOrder.builder()
.outboundRequestNo(detail.orderNo)
.status(YqnOutboundStatus.of(detail.orderStatusEnum).toCore()) // 枚举映射
.rawStatus(detail.orderStatusEnum) // 原值保留
.paidAt(parseTime(detail.paidAt, zone)) // 时间解析
.totalWeightKg(ouncesToGrams(detail.weight)) // 单位换算
.attachments(toAttachments(detail.enclosure)) // 子结构映射
.sourceProvider(WarehouseProvider.YQN) // 标记来源
.build();
}
必须做的四件事:
rawStatus/rawType一定填——它是映射出错时唯一能回滚的依据sourceProvider一定填——否则rawStatus无法解释- 认不出归 UNKNOWN,原值仍在
raw - 平台没给的字段不要伪造(别用
Instant.now()兜底时间、别用 0 兜底数量)
平台有、模型没有的字段:
| 处理 | 场景 |
|---|---|
| 加字段到模型 | 常用(附件、SN、行金额) |
| 加来源标注 | 字段名含义不同(skuAmount 是总额不是单价) |
| 丢弃并标注 | 极少用(thirdPartyAccount) |
模型有、平台没有的字段:Javadoc 写明「XX 仓不返回,恒为 null」,不要让后来人以为是漏接。
子结构别图省事复制
平台返回嵌套结构(enclosure[] / snList[] / batchInfo),标准模型要不要跟着嵌套,看用途:
// 附件:多个接口都用 → 建成通用模型
public final class WarehouseAttachment { name / type / url / packageNo; }
// 单次用的 → 用内部类
OutboundOrder.Line
运去哪退货一开始自己建了个 WarehouseReturn.Attachment,后来合并成 WarehouseAttachment——同一个概念别建两遍。
阶段 2.6:枚举怎么处理(详述)
为什么必须两层
仓方码 平台枚举 底层枚举
"unshipped" ──► YqnOutboundStatus.UNSHIPPED ──► OutboundStatus.SUBMITTED
0/1/2 XincangOrderStatus? (同一套,全仓共用)
只建一层的问题:
- 放在 core:core 认识运去哪的
"unshipped",接第二家仓就要改 core - 放在适配器:core 的
OutboundOrder.status类型没法写,宿主无法统一switch
底层枚举(core)
public enum OutboundStatus {
SUBMITTED(20, "已下发", 1),
SHIPPED(70, "已交运", 6),
UNKNOWN(0, "未知", -1);
private final int code; // SDK 自编,永不复用、永不重排
private final String label; // 中文名,可以改
private final int rank; // 推进序号,用于丢弃乱序回调
}
规则:
| 规则 | 理由 |
|---|---|
code 从 10 起、步长 10 |
中间可插入新值 |
UNKNOWN 固定 codes=0 |
不与业务值冲突 |
| 只追加不合并 | 合并了就分不出细分状态 |
| 不含任何仓方码 | 加了就是 core 认识平台 |
提供 ofCode(int) |
落库后反查 |
平台枚举(适配器)
public enum YqnOutboundStatus {
UNSHIPPED("unshipped", OutboundStatus.SUBMITTED),
SHIPPED("shipped", OutboundStatus.SHIPPED),
UNKNOWN(null, OutboundStatus.UNKNOWN);
private final String rawValue; // 仓方原值
private final OutboundStatus core;
public static YqnOutboundStatus of(String raw) { ... } // 精确匹配
public static OutboundStatus toCore(String raw) { ... }
}
规则:
| 规则 | 理由 |
|---|---|
精确匹配,不用 contains |
UNSHIPPED 会被 contains("SHIP") 误判 |
未知归 UNKNOWN,不猜 |
猜错比抛错更难查(未发货被判已交运) |
| 容器类型按仓方原样 | 数字码用 Integer,文本用 String,别强转 |
提供反向 codeOf() |
下发时要转回去 |
三套码表不能混
运去哪退货有三套:
| API 81 预约 | API 77 检验后 | API 142 回调 |
|---|---|---|
| 0 自提 / 1 拍照 / 2 销毁 / 5 仓库确认 | 0 自提 / 2 销毁 / 3 良品上架 / 4 换标 | 2 销毁 / 3 不良品 / 4 换标 / 5 良品 |
同样的 2 和 5 在不同表里含义不同。一码一表,绝不共用。
状态码依赖上下文时
运去哪 API 154 回调的 orderNoStatus 含义随 orderNoType 变化:
orderNoType=1(入库) status=5 → 审核通过
orderNoType=3(调拨) status=5 → 待审核
orderNoType=5(退货认领) status=5 → 待处理
做法:不改枚举,把 (type, status) 一起带出去:
.rawEventType("ORDER_STATUS:" + body.orderNoType)
.rawStatus(String.valueOf(body.orderNoStatus))
Javadoc 必须写明「不能脱离类型单独解释」。
什么时候不建枚举
| 情况 | 做法 |
|---|---|
| 码表 > 50 个且宿主不判断 | 透传字符串(如运去哪 29 个物流服务码 → 建常量枚举但不映射到 core) |
| 平台按中文名归类 | 在 Mapper 里用 switch(name),认不出留 null,不猜 |
| 只是展示用 | 原值放 raw* 字段 |
枚举测试必须覆盖什么
@Test
void allDocumentedValuesMap() {
// 文档里每一个值都断言一遍——错一位会静默错处理
}
@Test
void unknownIsNotGuessed() {
assertEquals(UNKNOWN, ... .toCore("某个新值"));
assertEquals("某个新值", order.rawStatus()); // 原值必须还在
}
@Test
void precisionMatters() {
// 专门测容易子串误判的:UNSHIPPED vs SHIPPED
assertEquals(SUBMITTED, YqnOutboundStatus.toCore("unshipped"));
}
阶段 3:真机验证(不可跳过)
3.1 先写只读探针
@EnabledIfSystemProperty(named = "<name>.probe", matches = "true")
class <Name>ReadOnlyProbeTest { ... }
- 默认跳过,凭据走系统属性(不入库)
- 输出打 token 掩码(
n9yc***qn),不打完整报文(可能含 PII) - 异常只打印不中断,一次跑完看全
3.2 再写全链路探针
按 @Order 串起来,创建 → 查询 → 取消,一条链验多个接口。
- 单号用
<PROBE>-<时间戳>前缀,便于识别 - 写接口只在 PR 环境跑
3.3 真机一定要做的事
| 检查项 | 为什么 |
|---|---|
| 参数名是否带前缀 | 运去哪库存查询文档写 query.warehouseCodes,实际是 warehouseCodes |
成功码是 code 还是 status |
运去哪仓库目录/运费试算没有 code,只有 status: 200 |
| 成功码的具体值 | 文档示例常是自动生成的占位符("message": "example"),不可信 |
| 单位 | 运去哪调拨 totalWeight 文档没写单位,真机验证是 kg |
| 必填字段的实际约束 | 运去哪入库的 lineCode 要项目名真实存在 |
运去哪 4 处文档与实际不符,全是靠真机才发现的。 只按文档写代码,那些接口一个都跑不通。
阶段 4:回调(如果有)
4.1 实现 WarehouseWebhookCapable
@Override
public void verify(ChannelSecret secret, Map<String,String> headers, String rawBody, long nowMillis) {
// 用 WebhookSignatures:HMAC + 恒定时间比较 + 时间窗
}
@Override
public List<WarehouseCallback> parse(WarehouseContext ctx, ChannelSecret secret,
Map<String,String> headers, String rawBody) {
// 多个回调共用一个地址时,按报文特征分派
}
4.2 声明 WEBHOOK 能力位
4.3 确认三件事
| 项 | 为什么 |
|---|---|
| 时间戳单位(秒 / 毫秒) | 文档常不写;按位数兼容,联调后收紧 |
| 回调响应体要什么 | 运去哪文档写 200 但示例是 1,回错会无限重推 |
| 是否按路径区分 | 运去哪四个回调共用一个地址,只能按报文结构分派 |
阶段 5:收尾
| 项 | 动作 |
|---|---|
| 文档 | docs-warehouse/<name>/README.md:接口清单、流程、真机结论、平台限制、字段口径、单位、探针用法 |
| 平台限制 | 每个恒 null 的字段在 Javadoc 里标注「XX 仓不返回」 |
| 单位未核实 | Javadoc 标「待核实,若为 lb 会偏大 2.2 倍」 |
| 待确认项 | 列成清单交给业务方 |
附:踩过的坑速查
| 坑 | 教训 |
|---|---|
| 子串匹配状态 | UNSHIPPED 命中 contains("SHIP") → 未发货被判已交运 |
| 状态 null 默认值 | settlementType 为 null 被当成「实际结算」 |
| 方向未知默认出库 | opLabel 缺失时库存被反向扣减 |
| 必填字段静默兜底 | 认不出就猜一个值,比报错更难查 |
| 能力位与实现不符 | 声明 SPLIT 但接口无拆单字段 |
| 枚举合并 | 把「不良品上架」和「良品上架」合并成一个 |
| 时区硬编码 | 美国仓时间整体平移 13–16 小时 |
| 只测文档 | 4 处文档与实际不符,全靠真机发现 |
| 日志漏写方法 | 出库有日志、调拨没日志,排查时误判 |
| 合并冲突取一侧 | 另一家仓的字段被静默删掉(本次 logisticsProducts 就丢过) |