38 KiB
common-ecommerce 开发指南
面向「要接入一个新平台」和「要写业务调用」的人。 读完之后你应该能回答三个问题:SDK 的分层是什么、加一个供应商要动哪些文件、加完之后怎么测。
配套材料:
README.md(包职责与调用方式速查)、D:\woker\文档\01需求分析\2026-10-28-电商平台\2026-10-26-cross-border-fulfillment-sdk-design.md(Spec 0 总体设计)。
目录
一、一句话心智模型
这个 SDK 是一层翻译 + 三条流水线。
每个平台说话方式都不同:字段名、签名算法、分页方式、时间格式、错误码。SDK 把这些差异全部关进一个类(适配器),对外只吐统一模型 SalesOrder、ProductListing。
业务代码永远只跟统一模型打交道,不出现任何平台字段名、URL、签名。
业务代码
│ 只认 AccountKey + 统一模型
▼
ChannelSdk 门面 ──── 查账户 / 找适配器 / 查能力
│
▼
适配器(每个平台一个模块)
│ 平台协议全在这里
▼
HttpTransport → 平台 API
三条流水线:
| 流水线 | 干什么 | 失败语义 |
|---|---|---|
| 读(单次) | sdk.salesOrders(key).pull(query) |
可重跑,靠 canonicalKey upsert 去重 |
| 批量读 | SyncEngine 翻页 + 落库 + 水位线 |
整批成功才推进,失败不推进 |
| 写 | sdk.writes().execute(...) |
必须幂等,重跑不能重复发货/退款 |
读和写没有共用执行器,因为失败语义相反:读可以放心重跑,写不能。
二、三个维度:平台、通道、店铺
这是整个设计的地基,混了后面全乱。
| 维度 | 类型 | 是什么 | 例子 |
|---|---|---|---|
| 业务平台 | Platform |
你卖货的地方 | WALMART_SC、AMAZON_SC、EBAY |
| 接入通道 | ChannelProvider |
你通过谁去连这个平台 | DIRECT(直连)、LINGXING(领星聚合) |
| 店铺 | omsStoreId |
你自己的渠道店铺 ID | oms-wm-001 |
三者拼成 AccountKey,是所有调用的隔离维度:
AccountKey key = AccountKey.of(ChannelProvider.LINGXING, Platform.WALMART_SC, "oms-wm-001");
为什么要拆开
同一个沃尔玛店铺,可能既直连、又走领星。业务上它是一个店,接入上是两条路。
由此推出两条硬规则:
-
业务主键
canonicalKey不带 provider 否则切换接入方式时,同一张订单会变成两行。CanonicalKeys.salesOrder(Platform.WALMART_SC, "oms-wm-001", "PO-123"); // 不管从直连还是领星拉到,都是 "WALMART_SC:oms-wm-001:PO-123" -
水位线、令牌、限流按 provider 分开 两条路各自维护进度,不能复用。
SyncSpec的维度是provider + accountKey + stream。
三级标识
| 标识 | 组成 | 用途 |
|---|---|---|
omsStoreId |
OMS 渠道店铺 ID | 业务归属 |
canonicalKey |
platform + omsStoreId + 平台实体 ID |
upsert、去重、状态流转 |
sourceKey |
provider + platform + externalStoreId + 平台实体 ID |
原始报文、审计、水位线 |
三、核心类型速查
3.1 基接口 PlatformAdapter
不是抽象基类,是接口。每个适配器必须回答 5 个问题。
public interface PlatformAdapter {
String adapterId(); // 我是谁:"lingxing"
ChannelProvider provider(); // 哪条通道:DIRECT / LINGXING
Set<Platform> platforms(); // 覆盖哪些平台
EnumSet<Capability> capabilities(); // 我会什么
default boolean supports(ChannelAccount a, Capability c) {
return capabilities().contains(c);
}
}
| 动作 | 谁调用 | 你要做什么 |
|---|---|---|
adapterId() |
日志、报错、注册冲突检测 | 唯一短名 |
provider() |
门面路由 | 直连固定 DIRECT |
platforms() |
门面注册、能力报告 | 列全覆盖的平台 |
capabilities() |
能力报告、门面拦截 | 只声明真实现的 |
supports(account, cap) |
每次门面调用前 | 直连不用覆写;聚合器必须覆写 |
capabilities() 是声明,不是猜测。声明了没实现,第一次调用就炸,比不声明更糟。
3.2 能力接口
供应商实现哪些接口,就声明哪些能力。目前有两个:
public interface SalesOrderCapable extends PlatformAdapter {
Page<SalesOrder> pull(ChannelContext ctx, SalesOrderQuery query);
SalesOrder get(ChannelContext ctx, SalesOrderRef ref);
default void requireCapability(); // 未声明即抛 UnsupportedCapabilityException
}
public interface ProductCapable extends PlatformAdapter {
ProductSyncStrategy syncStrategy(); // INCREMENTAL_TIME_WINDOW / FULL_PULL_DIFF / REPORT
Page<ProductListing> pull(ChannelContext ctx, ProductQuery query);
ProductListing get(ChannelContext ctx, ProductRef ref);
}
为什么 get 的参数是 SalesOrderRef / ProductRef 而不是 String?
Java 擦除后两个 get(ctx, String) 是同一个签名。一个同时实现订单和商品的适配器(比如直连沃尔玛)无法同时实现,编译器直接报名称冲突。所以包成两个不同的类。
对应的 import 路径:
common.ecommerce.model.order.SalesOrderRef、common.ecommerce.model.product.ProductRef。model包按职责拆成account/order/product/support四个子包,枚举留在model根包。
为什么 pull 返回 Page<T> 而不是 List<T>?
Page 带 nextCursor,null 表示没有下一页。翻页方式各平台不同(offset / cursor / pageToken),差异留在适配器里,SDK 只认这个统一信封。
3.3 门面 ChannelSdk
public final class ChannelSdk implements ProviderResolver {
public CapabilityReport capabilities(AccountKey key); // 只读,不发请求
public SalesOrders salesOrders(AccountKey key); // 订单视图
public Products products(AccountKey key); // 商品视图
public IdempotencyGuard writes(); // 写操作守卫
public PlatformAdapter resolve(AccountKey key); // 按 key 找适配器
}
门面不做:不选 provider、不自动兜底、不重试、不缓存。
每次调用固定三步:
key → accountRepository.findByKey(provider, platform, omsStoreId)
→ adapters.get(provider|platform)
→ adapter.supports(account, capability)
→ 交给适配器
build() 会立刻失败的情况:
| 缺失 | 异常 |
|---|---|
accountRepository |
ChannelSdk requires an accountRepository |
| 一个适配器都没注册 | ChannelSdk requires at least one adapter or adapter factory |
同一 provider + platform 注册两次 |
duplicate adapter for ... |
能力不够不会自动换 provider。 换路意味着可能重复发货,必须业务代码显式决定。
3.4 存量 SPI(宿主必须实现)
| SPI | 作用 | 读要用 | 写要用 |
|---|---|---|---|
ChannelAccountRepository |
读渠道账户 | ✅ | ✅ |
SecretProvider |
按 credentialRef 取密钥 |
✅ | ✅ |
TokenStore |
token 读写(宿主加密) | ✅ | ✅ |
LockProvider |
token 刷新防击穿 | ✅ | ✅ |
SyncCursorStore |
水位线 | 批量读 | — |
Sink |
领域对象落库 | 批量读 | — |
IdempotencyStore |
幂等键抢占与结果 | — | ✅ |
3.5 错误类型
全部继承 ChannelException,字段:platform / provider / omsStoreId / operation / requestId / platformCode / retryable / rawResponse。
| 异常 | 触发 | 可重试 |
|---|---|---|
AuthException |
401 / 403 | 刷新后 1 次 |
RateLimitException |
429,带 retryAfterMillis() |
是 |
TransientException |
5xx / 网络 / 超时 | 是 |
ValidationException |
其它 4xx | 否 |
PlatformBusinessException |
平台业务错误码 | 视码 |
ChannelException.UnsupportedCapabilityException |
能力缺失 | 否 |
IdempotencyConflictException |
并发重复写 | 否 |
CrossProviderConflictException |
已由另一 provider 完成 | 否,人工确认 |
UnsupportedCapabilityException是ChannelException的静态内部类,必须写全名。
四、三条流水线逐段讲
4.1 单次读:sdk.salesOrders(key).pull(query)
Page<SalesOrder> page = sdk.salesOrders(key).pull(SalesOrderQuery.builder()
.updatedAfter(Instant.parse("2026-10-25T00:00:00Z")) // 必填,UTC
.updatedBefore(Instant.parse("2026-10-26T00:00:00Z")) // 可选,缺省取 now
.pageSize(100) // 会被截到平台上限
.build());
while (page.nextCursor() != null) {
page = sdk.salesOrders(key).pull(
SalesOrderQuery.builder()...cursor(page.nextCursor()).build());
}
SalesOrderQuery 有 toBuilder(),翻页时直接改游标。
内部发生了什么:
ChannelSdk
→ requireAccount(找不到抛 IllegalStateException)
→ resolve(找不到适配器抛 IllegalStateException)
→ SalesOrders.requireSalesOrderCapable(能力缺失抛 UnsupportedCapabilityException)
→ adapter.pull(ctx, query)
├─ 取 token(TokenManager)
├─ 签名
├─ transport.execute(req)
├─ Responses.throwIfNotSuccess(resp, "salesOrders.pull")
└─ Mapper → Page<SalesOrder>
4.2 批量读:SyncEngine
SyncSpec spec = SyncSpec.of(
ChannelProvider.LINGXING, "oms-wm-001",
SyncSpec.STREAM_SALES_ORDERS,
Duration.ofMinutes(10)); // 重叠窗口
Instant to = Instant.now();
SyncResult r = new SyncEngine(cursorStore, sink).syncSalesOrders(spec, to,
(from, cursor) -> sdk.salesOrders(key).pull(SalesOrderQuery.builder()
.updatedAfter(from).updatedBefore(to)
.cursor(cursor).build()));
r.pages(); // 拉了几页
r.items(); // 落了几条
r.watermarkAdvanced(); // 是否推进
引擎做的事就一个循环:
watermark = cursorStore.get(provider, accountKey, stream)
from = watermark - overlap // 回退重叠窗口
loop:
page = fetch(from, cursor)
if page 空: break
sink.upsertSalesOrders(page) // 落库
cursor = page.nextCursor()
if cursor == null: break
cursorStore.advance(provider, accountKey, stream, to) // 全成功才推进
| 关键点 | 原因 |
|---|---|
起点回退 overlap |
平台有延迟、时钟有偏差,边界那一秒的单可能上一轮没拉到 |
终点是传入的 to,不是 now() |
拉取可能持续几分钟,用 now() 会越拉越远 |
| 中途抛异常 → 水位线不动 | 安全重跑,靠 upsert 去重 |
没有水位线 → 抛 IllegalStateException |
逼迫先做全量建底,不偷偷丢数据 |
| 不持有线程 | 调度归宿主(Quartz / XXL-Job / Spring Scheduler) |
首次全量要自己回填水位线:
if (cursorStore.get(provider, accountKey, stream) == null) {
cursorStore.advance(provider, accountKey, stream, Instant.parse("2026-01-01T00:00:00Z"));
}
Sink 怎么写:SDK 只给 Page<SalesOrder>,upsert 的键要自己算:
public void upsertSalesOrders(Page<SalesOrder> page) {
for (SalesOrder o : page.items()) {
String key = CanonicalKeys.salesOrder(platform, o.omsStoreId(), o.channelOrderId());
// INSERT ... ON DUPLICATE KEY UPDATE,唯一索引建在 canonicalKey 上
// sourceProvider / sourceAccountId 只更新来源字段,不产生新行
}
}
4.3 写:IdempotencyGuard
WriteScope scope = WriteScope.of(
ChannelProvider.LINGXING, Platform.WALMART_SC,
"oms-wm-001", // 业务店铺
"1108413237731", // 平台店铺 ID,只用于 provider 请求键
"markShipped",
"PO-1:pkg-1"); // 业务自然键
WriteResult<ShipResult> r = sdk.writes().execute(scope,
() -> adapter.markShipped(ctx, cmd), // 真正打平台
ShipResult::shipmentId); // 结果引用,回放时返回
if (r.alreadyCompleted()) {
// 之前已发过,用 r.resultRef() 返回给上游,不算失败
}
内部是两把锁:
1. 抢业务键(不带 provider) → 已成功?→ 回放 / 别的 provider 做的?→ 冲突
2. 抢 provider 键(带 provider)→ 已成功?→ 平台写过但没记账 → 回放
3. 执行
4. 先记 provider 键成功,再记业务键成功
| 情形 | 结果 |
|---|---|
| 首次调用 | EXECUTED |
| 同 provider 重复 | ALREADY_COMPLETED,不调平台 |
| 另一 provider 重复 | CrossProviderConflictException |
| 并发 | IdempotencyConflictException |
抛 retryable=true 异常 |
两把锁记 FAILED_RETRYABLE,可重跑 |
抛 retryable=false 异常 |
记 FAILED_FINAL,之后拒绝,等人工 |
| 崩溃窗口(平台已写、业务键未记) | provider 键命中,回放,不重复写 |
业务键规则:
- 退款用
returnId:itemId:refundRequestId,禁止用金额(金额只做校验)。 IdempotencyStore.claim必须原子(唯一索引 / Redis SETNX),否则并发语义不成立。- 不注入
idempotencyStore时sdk.writes()直接抛异常,没有「无幂等」降级路径。
五、加一个供应商:8 步
以新增 acme 直连平台为例。核心原则:不改 core、不改门面、不改宿主。
第 0 步:先想清楚三件事
| 问题 | 影响 |
|---|---|
它属于哪个 Platform? |
枚举里有直接用;没有才加(唯一允许改 core 的地方) |
走 DIRECT 还是新聚合器? |
新聚合器才加 ChannelProvider 枚举值 |
| 它会哪些能力? | 只列真能做的 |
现有枚举:
Platform:AMAZON_SCAMAZON_VCWALMART_SCWALMART_1PTIKTOKTEMUEBAYSHEINMIRAKLTARGETBESTBUYAEPHCUSTOMChannelProvider:DIRECTLINGXINGTEAPPLIXCUSTOM
第 1 步:建模块
pom.xml 加 <module>acme</module>,模块依赖:
<dependency>
<groupId>ecommerce</groupId>
<artifactId>common-ecommerce-core</artifactId>
</dependency>
<dependency>
<groupId>ecommerce</groupId>
<artifactId>common-ecommerce-http</artifactId>
</dependency>
<dependency>
<groupId>ecommerce</groupId>
<artifactId>common-ecommerce-testkit</artifactId>
<scope>test</scope>
</dependency>
<dependency>
<groupId>org.junit.jupiter</groupId>
<artifactId>junit-jupiter</artifactId>
<scope>test</scope>
</dependency>
红线:适配器模块里不许出现 Spring / JDBC / Redis / MQ。
第 2 步:常量类
package common.ecommerce.acme;
// model 包按职责分了子包,import 时注意:
import common.ecommerce.model.Capability;
import common.ecommerce.model.ChannelProvider;
import common.ecommerce.model.Platform;
import common.ecommerce.model.account.ChannelAccount;
import common.ecommerce.model.order.SalesOrder;
import common.ecommerce.model.order.SalesOrderQuery;
import common.ecommerce.model.order.SalesOrderRef;
import common.ecommerce.model.support.Money;
import common.ecommerce.model.support.Page;
import common.ecommerce.model.support.PlatformTime;
public final class AcmeConstants {
public static final String ADAPTER_ID = "acme";
public static final String DEFAULT_BASE_URL = "https://api.acme.example.com";
public static final String PATH_TOKEN = "/oauth/token";
public static final String PATH_ORDERS = "/v1/orders";
public static final int MAX_PAGE_SIZE = 100;
public static final int MAX_QUERY_DAYS = 31;
private AcmeConstants() {
}
}
平台端点必须是代码,不是配置表:配置化会让线上和测试跑不同协议,出问题查不出来。
第 3 步:DTO —— 平台字段名的唯一落点
@JsonIgnoreProperties(ignoreUnknown = true)
public final class AcmeOrderDto {
@JsonProperty("order_sn") private String orderSn;
@JsonProperty("order_status") private String orderStatus;
@JsonProperty("buyer_country") private String buyerCountry;
@JsonProperty("total_amount") private String totalAmount;
@JsonProperty("currency") private String currency;
@JsonProperty("created_at") private Long createdAt; // 注意秒/毫秒
@JsonProperty("lines") private List<AcmeOrderLineDto> lines;
// getters / setters
}
平台字段名只允许出现在 DTO 和 Mapper 里。
第 4 步:Mapper —— DTO → 统一模型
public final class AcmeOrderMapper {
/**
* @param externalStoreId 平台店铺 ID,写入 sourceAccountId 供追溯(不进业务主键)
*/
public SalesOrder toSalesOrder(AcmeOrderDto dto, String omsStoreId, String externalStoreId, ZoneId zone) {
String currency = dto.getCurrency() == null ? "USD" : dto.getCurrency();
List<OrderLine> lines = new ArrayList<OrderLine>();
for (AcmeOrderLineDto l : safe(dto.getLines())) {
lines.add(OrderLine.builder()
.lineId(l.getLineId())
.platformSku(l.getSku())
.quantity(l.getQty() == null ? 0 : l.getQty())
.unitPrice(moneyOrNull(l.getPrice(), currency))
.build());
}
return SalesOrder.builder()
.omsStoreId(omsStoreId)
.channelOrderId(dto.getOrderSn()) // ★ 平台自己的稳定单号
.status(dto.getOrderStatus())
.buyerName(dto.getBuyerName())
.shipToCountryCode(dto.getBuyerCountry())
.lines(lines)
.totalAmount(moneyOrNull(dto.getTotalAmount(), currency))
.occurredAt(PlatformTime.of(Instant.ofEpochSecond(dto.getCreatedAt()), zone))
.sourceProvider(ChannelProvider.DIRECT) // ★ 只标来源,不进主键
.sourceAccountId(externalStoreId)
.build();
}
private static <T> List<T> safe(List<T> in) {
return in == null ? Collections.<T>emptyList() : in;
}
private static Money moneyOrNull(String value, String currency) {
if (value == null || value.trim().isEmpty()) {
return null;
}
return Money.of(value.trim(), currency);
}
}
Mapper 里最容易错的三处:
channelOrderId选了会变的字段(撤销后重下、批次号)→ 每次同步产生新行- 时间没转 UTC → 水位线错位
- 金额用了
double→ 精度丢失(Money只接受BigDecimal或字符串)
第 5 步:认证与签名
只用 token 的(像领星),继承 TokenManager 只写换 token 的逻辑:
TokenManager tm = new TokenManager(tokenStore, lockProvider, clock, 600) {
@Override
protected AccessToken refresh(ChannelSecret secret, AccessToken previous) {
return tokenClient.fetch(secret.appKey(), secret.appSecret());
}
};
防击穿、提前续期、日志只打指纹,模板都写好了。
要签名的,实现 Signer 或写静态工具类:
public final class AcmeSigner {
public static String sign(Map<String, String> params, String appSecret) { ... }
}
签名实现集中在一处,联调时只改这里。
第 6 步:Adapter —— 干活的类
public final class AcmeAdapter implements SalesOrderCapable {
private final String baseUrl;
private final HttpTransport transport;
private final JacksonJsonCodec json;
private final SecretProvider secretProvider;
private final Clock clock;
private final TokenManager tokenManager;
private final AcmeOrderMapper mapper = new AcmeOrderMapper();
public AcmeAdapter(String baseUrl, HttpTransport transport, JacksonJsonCodec json,
SecretProvider secretProvider, TokenStore tokenStore,
LockProvider lockProvider, Clock clock) {
this.baseUrl = baseUrl;
this.transport = transport;
this.json = json;
this.secretProvider = secretProvider;
this.clock = clock;
final AcmeTokenClient tokenClient = new AcmeTokenClient(transport, json, baseUrl);
this.tokenManager = new TokenManager(tokenStore, lockProvider, clock, 600) {
@Override
protected AccessToken refresh(ChannelSecret secret, AccessToken previous) {
return tokenClient.fetch(secret.appKey(), secret.appSecret());
}
};
}
@Override public String adapterId() { return AcmeConstants.ADAPTER_ID; }
@Override public ChannelProvider provider() { return ChannelProvider.DIRECT; }
@Override public Set<Platform> platforms() { return EnumSet.of(Platform.AMAZON_SC); }
@Override
public EnumSet<Capability> capabilities() {
return EnumSet.of(Capability.SALES_ORDER);
}
@Override
public Page<SalesOrder> pull(ChannelContext ctx, SalesOrderQuery query) {
requireCapability(); // 自己再兜一层
ChannelAccount account = ctx.account();
int size = Math.min(query.pageSize() <= 0 ? 100 : query.pageSize(),
AcmeConstants.MAX_PAGE_SIZE);
HttpRequest req = HttpRequest.builder()
.method("POST")
.url(baseUrl + AcmeConstants.PATH_ORDERS)
.header("Content-Type", "application/json")
.header("Authorization", authHeader(ctx))
.header("X-Request-Id", ctx.requestId())
.body(buildBody(account, query, size))
.operation("salesOrders.pull")
.build();
HttpResponse resp = transport.execute(req);
Responses.throwIfNotSuccess(resp, "salesOrders.pull"); // ★ 必须调
List<AcmeOrderDto> dtos = json.listAt(resp.body(), "data.orders", AcmeOrderDto.class);
List<SalesOrder> out = new ArrayList<SalesOrder>(dtos.size());
for (AcmeOrderDto dto : dtos) {
out.add(mapper.toSalesOrder(dto, account.omsStoreId(), account.externalStoreId(),
ZoneId.of(account.marketplaceZone())));
}
return Page.of(out, json.stringAt(resp.body(), "data.next_cursor"));
}
@Override
public SalesOrder get(ChannelContext ctx, SalesOrderRef ref) {
// 没有详情接口就显式抛,不要返回 null
throw ChannelException.builder()
.message("acme order detail is not implemented yet")
.operation("salesOrders.get")
.provider(provider().name())
.omsStoreId(ctx.omsStoreId())
.requestId(ctx.requestId())
.platformCode(ref.channelOrderId())
.build();
}
// ---------------------------------------------------------------- internals
private String authHeader(ChannelContext ctx) {
ChannelAccount account = ctx.account();
ChannelSecret secret = secretProvider.get(account.credentialRef());
AccessToken token = tokenManager.getOrRefresh("acme:" + account.externalStoreId(), secret);
return token.tokenType() + " " + token.value();
}
private String buildBody(ChannelAccount account, SalesOrderQuery query, int size) {
Map<String, Object> body = new LinkedHashMap<String, Object>();
body.put("store_id", account.externalStoreId());
body.put("page_size", size);
if (query.cursor() != null) {
body.put("cursor", query.cursor());
}
body.put("updated_after", query.updatedAfter().getEpochSecond());
Instant to = query.updatedBefore() != null ? query.updatedBefore() : Instant.now(clock);
body.put("updated_before", to.getEpochSecond());
return json.toJson(body);
}
}
Adapter 的四条规矩:
Responses.throwIfNotSuccess必须调 —— 否则 500 会被当成功解析,报错信息全错。- 不自己造
ChannelContext—— 由门面传入,里面有 requestId 和可测试时钟。 - 不用
Instant.now(),用ctx.clock()或注入的clock,否则测试无法固定时间。 - 不支持的方法显式抛异常,不返回
null、不返回空Page。
第 7 步:Factory —— 注册入口
public final class AcmeAdapterFactory implements AdapterFactory {
private final SecretProvider secretProvider;
private final TokenStore tokenStore;
private final LockProvider lockProvider;
private final Clock clock;
public AcmeAdapterFactory(SecretProvider secretProvider, TokenStore tokenStore,
LockProvider lockProvider, Clock clock) { ... }
@Override public String adapterId() { return AcmeConstants.ADAPTER_ID; }
@Override public ChannelProvider provider() { return ChannelProvider.DIRECT; }
@Override public EnumSet<Platform> platforms() { return EnumSet.of(Platform.AMAZON_SC); }
@Override
public PlatformAdapter create(AdapterConfig config) {
String baseUrl = config.endpointBaseUrl() == null
? AcmeConstants.DEFAULT_BASE_URL : config.endpointBaseUrl();
return new AcmeAdapter(baseUrl,
new OkHttpTransport("common-ecommerce/1.0.0 (acme)"),
new JacksonJsonCodec(),
secretProvider, tokenStore, lockProvider, clock);
}
}
工厂的意义:把「怎么 new」和「业务怎么用」隔开。宿主只注册工厂,不需要知道构造参数。
第 8 步:接进门面
ChannelSdk sdk = ChannelSdk.builder()
.accountRepository(accountRepo)
.idempotencyStore(idempotencyStore) // 要写操作就必须
.idempotencyOwner(hostName) // 多实例时区分抢占方
.register(new AcmeAdapterFactory(secretProvider, tokenStore, lockProvider, clock))
.build();
AccountKey key = AccountKey.of(ChannelProvider.DIRECT, Platform.AMAZON_SC, "oms-amz-001");
Page<SalesOrder> page = sdk.salesOrders(key).pull(query);
如果你发现要改 ChannelSdk 或 SyncEngine 才能加进去,说明走歪了。
聚合器的额外差异
聚合器(领星这类)与直连只差两点:
- 实现
AggregatorCapable,覆写supports(account, capability),按子平台细化:
@Override
public boolean supports(ChannelAccount account, Capability capability) {
if (!capabilities().contains(capability)) {
return false;
}
Platform p = toPlatform(account.platformCode());
if (p == Platform.EBAY) {
return capability == Capability.SALES_ORDER; // eBay 只有订单
}
return true;
}
- 实现
listSubChannels(account)列出子渠道。
不要为每个子平台建模块 —— 子平台是配置(platformCode + externalStoreId),不是代码。
六、加完之后怎么测
五层,按成本从低到高。前四层必须全绿才能进真实环境。
第 1 层:纯计算单测(毫秒级)
测 Mapper 和签名器,性价比最高。
@Test
void mapsAcmeOrder() {
AcmeOrderDto dto = json.fromJson(fixtureJson, AcmeOrderDto.class);
SalesOrder o = mapper.toSalesOrder(dto, "oms-amz-001", ZoneId.of("America/Los_Angeles"));
assertEquals("ACME-1001", o.channelOrderId());
assertEquals("59.97 USD", o.totalAmount().toString());
assertEquals(1793001600L, o.occurredAt().utc().getEpochSecond()); // 秒级时间没转错
assertEquals(ChannelProvider.DIRECT, o.sourceProvider());
}
签名器用固定向量:
assertEquals(md5Hex("secretapp_keyk1"), AcmeSigner.sign(params, "secret"));
时间相关的用 DST 边界:2026-03-08 美国太平洋时区进入夏令时,前后各测一次。
第 2 层:契约测试(主力,不碰网络)
这是整个项目最核心的测试方式。不用 Mockito,不用 WireMock:FakeTransport 按 URL 子串直接返回磁盘上的录制 JSON。
夹具路径约定:
acme/src/test/resources/fixtures/acme/orderList/success.json
acme/src/test/resources/fixtures/acme/orderList/page2.json
acme/src/test/resources/fixtures/acme/orderList/empty.json
acme/src/test/resources/fixtures/acme/token/success.json
读法:
String orderJson = Fixtures.load(AcmeAdapterTest.class, "acme", "orderList", "success");
测试骨架:
class AcmeAdapterTest {
private FakeTransport transport;
private AcmeAdapter adapter;
private ChannelContext ctx;
@BeforeEach
void setUp() {
transport = FakeTransport.create();
transport.route(AcmeConstants.PATH_TOKEN, "POST", r -> Responses.ok(tokenJson));
transport.route(AcmeConstants.PATH_ORDERS, "POST", r -> Responses.ok(orderJson));
Clock clock = Clock.fixed(Instant.parse("2026-10-29T00:00:00Z"), ZoneOffset.UTC);
adapter = new AcmeAdapter(BASE_URL, transport, new JacksonJsonCodec(),
accounts, tokenStore, locks, clock);
ctx = ChannelContext.of(account, "req-1", clock);
}
@Test
void requestIsBuiltCorrectly() {
adapter.pull(ctx, query);
HttpRequest last = transport.lastRequest();
assertTrue(last.url().contains("sign="));
assertEquals("Bearer acme-token", last.headers().get("Authorization"));
assertEquals("req-1", last.headers().get("X-Request-Id"));
assertTrue(last.body().contains("\"page_size\":100"));
assertTrue(last.body().contains("\"store_id\":\"store-1\""));
}
@Test
void responseIsParsedCorrectly() {
Page<SalesOrder> page = adapter.pull(ctx, query);
assertEquals(3, page.size());
assertEquals("ACME-1001", page.items().get(0).channelOrderId());
assertNull(page.nextCursor()); // total 已到,应该结束
}
}
为什么拆成「请求对不对」和「解析对不对」两个测试? 出问题时:请求错 → 平台报错但看不到为什么;解析错 → 请求成功但字段全是 null。分开测,一眼定位。
必测的错误路径(各一个夹具 + 一个断言):
| 夹具 | 断言 |
|---|---|
401.json |
AuthException |
429.json(带 Retry-After: 3) |
RateLimitException.retryAfterMillis() == 3000 |
500.json |
TransientException.retryable() == true |
400.json |
ValidationException |
第 3 层:分页与水位线
@Test
void pagesThroughAllOrdersAndAdvancesWatermarkOnce() {
transport.route(AcmeConstants.PATH_ORDERS, "POST", r ->
r.body().contains("\"cursor\":\"c1\"")
? Responses.ok(page2Json)
: Responses.ok(page1Json));
InMemoryCursorStore cursors = new InMemoryCursorStore();
InMemorySink sink = new InMemorySink();
cursors.seed(ChannelProvider.DIRECT, "oms-amz-001",
SyncSpec.STREAM_SALES_ORDERS, Instant.parse("2026-10-28T00:00:00Z"));
SyncSpec spec = SyncSpec.of(ChannelProvider.DIRECT, "oms-amz-001",
SyncSpec.STREAM_SALES_ORDERS, Duration.ofMinutes(10));
Instant to = Instant.parse("2026-10-29T00:00:00Z");
SyncResult r = new SyncEngine(cursors, sink).syncSalesOrders(spec, to,
(from, cursor) -> adapter.pull(ctx, SalesOrderQuery.builder()
.updatedAfter(from).updatedBefore(to).cursor(cursor).build()));
assertEquals(2, r.pages());
assertEquals(5, r.items());
assertTrue(r.watermarkAdvanced());
assertEquals(to, cursors.watermark(ChannelProvider.DIRECT, "oms-amz-001",
SyncSpec.STREAM_SALES_ORDERS));
assertEquals(5, sink.salesOrders().size());
}
必测的失败路径:
- 第二页返回 500 → 抛异常,水位线不推进
- 返回空页 → 立刻结束,不无限循环
- 没有水位线 → 抛
IllegalStateException
第 4 层:门面 + 能力
@Test
void facadeRejectsUnsupportedCapability() {
ChannelSdk sdk = ChannelSdk.builder()
.accountRepository(inMemoryAccounts)
.register(adapter)
.build();
assertTrue(sdk.capabilities(key).supports(Capability.SALES_ORDER));
assertFalse(sdk.capabilities(key).supports(Capability.REFUND));
assertThrows(ChannelException.UnsupportedCapabilityException.class,
() -> sdk.products(key).pull(ProductQuery.builder().build()));
}
聚合器还要额外测:同一适配器,Walmart 账户和 eBay 账户的 supports 结果不同。
第 5 层:真实冒烟(手动,不进 CI)
参考 lingxing/src/test/java/common/ecommerce/lingxing/LingxingLiveSmokeTest.java:没配环境变量时整类跳过。
@EnabledIfEnvironmentVariable(named = "ACME_APP_KEY", matches = ".+")
class AcmeLiveSmokeTest {
@Test
void tokenCanBeFetched() { ... } // 先验认证
@Test
void pullsOnePage() { ... } // 再验报文
}
包一层 LoggingTransport 打印请求响应(Authorization 打码、body 截断)。
排错顺序:
- 401 / 403 → 先单独跑 token 测试;还失败就查出口 IP 白名单。
- token 通了但接口报签名错 → 只改
Signer,跑已知向量。 - 200 但 0 条 → 查时间窗、
platform_code、store_id是否属于同一店铺。 - 200 有数据但字段 null → 对照原始报文改 DTO 的
@JsonProperty,然后把真实响应存成新夹具。
真实报文转夹具:冒烟跑通后,把打印的响应存成 fixtures/acme/orderList/real-2026-10-29.json,加一个 Mapper 用例。以后改代码不用再连真实环境。
七、验收清单
加完一个供应商,逐条打勾:
| # | 检查项 | 怎么验 |
|---|---|---|
| 1 | 声明能力 = 实际实现 | 每个能力一条断言 |
| 2 | 不支持的能力抛异常 | 门面断言 UnsupportedCapabilityException |
| 3 | canonicalKey 只依赖平台单号 | 拉两次同一条,key 相同 |
| 4 | 分页能停 | 最后一页 nextCursor == null |
| 5 | 错误映射正确 | 401 / 429 / 500 / 400 各一个夹具 |
| 6 | token 只刷一次 | tokenStore.saveCount() == 1 |
| 7 | 超长时间窗会截断 | 断言 body 里的起止时间 |
| 8 | 写操作只执行一次 | adapter.writeCallCount() == 1 |
| 9 | 水位线失败不推进 | 第二页抛异常后断言水位线不变 |
| 10 | core 零改动 | git diff core/ 应只有 Platform 枚举 |
八、已知缺口与坑
当前实现状态(2026-10-29)
| 模块 | 状态 |
|---|---|
| core | 模型、能力接口、门面、SyncEngine、幂等守卫、SPI 全部可用 |
| http | OkHttp 传输、Jackson 编解码、签名接口、TokenManager 模板可用 |
| testkit | FakeTransport、InMemory SPI、FakeDirectAdapter、MutableClock、夹具加载可用 |
| lingxing | 订单列表拉取可用;商品、履约、面单、账单、售后未实现 |
| 其它平台 | 未开始 |
编码坑(按踩到概率排序)
- 字段名对不上:DTO 的
@JsonProperty和真实报文不一致 → 解析出 null。用真实报文做夹具最能防。 capabilities()写多了:声明PRODUCT但没实现ProductCapable→ 门面ClassCastException。get用裸String:同时实现订单 + 商品就编译不过。用SalesOrderRef/ProductRef。- 忘记
Responses.throwIfNotSuccess:500 被当成功解析,报错变成「字段为 null」,排查方向全错。 - 用了
Instant.now()而不是clock:测试无法固定时间,水位线断言随机失败。 - canonicalKey 用了会变的字段:同一订单每次同步产生新行。
Responsesimport 错:http.Responses(状态码→异常)和testkit.Responses(造响应)是两个类。UnsupportedCapabilityException单独 import:它是ChannelException的静态内部类,必须写全名。
设计层面的已知缺口
| 缺口 | 影响 | 建议 |
|---|---|---|
SalesOrder 没有 platform 字段 |
Sink 算 canonicalKey 时要额外查平台 |
给模型加 platform,或让 Sink 接收上下文 |
| 适配器不重试 | 401/429/5xx 只分类不重试 | 宿主在调用层包退避,或补通用重试器 |
RawPayloadStore 未实现 |
原始报文无留痕 | 新增 SPI + 脱敏 |
RefundLedger 未实现 |
无超退校验 | 与 IdempotencyGuard 配合 |
DuplicateOrderGuard 未实现 |
跨 provider 重复订单无告警 | 新增 SPI |
| 领星时间窗超 31 天被静默截断 | 水位线落后太多会漏中间段 | 调用方分段补拉 |
| 领星单订单详情未实现 | get() 直接抛异常 |
用 pull + 时间窗捞 |
领星限流器用 Thread.sleep |
多店并发时按实例数放大 | 按账户拆适配器实例,或换通用限流器 |
九、上手顺序
- 读三个文件:
PlatformAdapter、SalesOrderCapable、ChannelSdk。不到 150 行,看懂这三个就懂一半。 - 跑一遍现有测试:
mvn -pl lingxing -am test,对照看LingxingAdapterTest—— 它就是「加一个供应商」的完整范例。 - 抄领星的结构建新模块:
Constants → Dto → Mapper → Adapter → Factory → Test。 - 先用夹具跑通,再连真实环境。 不要反过来。
常用命令
mvn clean test # 全部
mvn -pl lingxing -am test # 单模块(含依赖)
mvn -pl lingxing -am test -Dtest=LingxingAdapterTest # 单个测试类
mvn -pl lingxing -am test -Dtest=LingxingLiveSmokeTest # 真实环境冒烟(需环境变量)