You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

39 KiB

common-ecommerce 开发指南

面向「要接入一个新平台」和「要写业务调用」的人。 读完之后你应该能回答三个问题:SDK 的分层是什么、加一个供应商要动哪些文件、加完之后怎么测。

配套材料:README.md(架构图、包结构与调用方式速查)、D:\woker\文档\01需求分析\2026-10-28-电商平台\2026-10-26-cross-border-fulfillment-sdk-design.md(Spec 0 总体设计)。


目录

  1. 一句话心智模型
  2. 三个维度:平台、通道、店铺
  3. 核心类型速查
  4. 三条流水线逐段讲
  5. 加一个供应商:8 步
  6. 加完之后怎么测
  7. 验收清单
  8. 已知缺口与坑
  9. 上手顺序

一、一句话心智模型

这个 SDK 是一层翻译 + 三条流水线。

每个平台说话方式都不同:字段名、签名算法、分页方式、时间格式、错误码。SDK 把这些差异全部关进一个类(适配器),对外只吐统一模型 SalesOrder、ProductListing。

业务代码永远只跟统一模型打交道,不出现任何平台字段名、URL、签名。

业务代码
   │  只认 AccountKey + 统一模型
   ▼
ChannelSdk 门面 ──── 查账户 / 找适配器 / 查能力
   │
   ▼
适配器(每个平台一个模块)
   │  平台协议全在这里
   ▼
HttpTransport → 平台 API

三条流水线:

流水线 干什么 失败语义
读(单次) sdk.salesOrders(key, conn).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");

为什么要拆开

同一个沃尔玛店铺,可能既直连、又走领星。业务上它是一个店,接入上是两条路。

由此推出两条硬规则:

  1. 业务主键 canonicalKey 不带 provider 否则切换接入方式时,同一张订单会变成两行。

    CanonicalKeys.salesOrder(Platform.WALMART_SC, "oms-wm-001", "PO-123");
    // 不管从直连还是领星拉到,都是 "WALMART_SC:oms-wm-001:PO-123"
    
  2. 水位线、令牌、限流按 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 能力接口

供应商实现哪些接口,就声明哪些能力。接口都继承 PlatformAdapter:

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);
}

其余能力接口(按需实现,不实现就不声明):

接口 读/写 关键方法
SettlementCapable 读 pull(ctx, SettlementQuery)
AfterSaleCapable 读 pull(ctx, AfterSaleQuery)
OutboundOrderCapable 读 pull(ctx, OutboundOrderQuery)
ShippingLabelCapable 读 labels(ctx, LabelQuery)
OutboundCapable 写 submit(ctx, packages) / results(ctx, globalOrderNos)
ShipmentReviewCapable 写 review(ctx, globalOrderNos)
OrderEditCapable 写 edit(ctx, requests)
AggregatorCapable — listSubChannels(ctx),聚合器额外实现

为什么 get 的参数是 SalesOrderRef / ProductRef 而不是 String?

Java 擦除后两个 get(ctx, String) 是同一个签名。一个同时实现订单和商品的适配器(比如直连沃尔玛)无法同时实现,编译器直接报名称冲突。所以包成两个不同的类。对外的门面视图仍收 String(sdk.salesOrders(key, conn).get("PO-123")),由视图负责包装。

对应的 import 路径:common.ecommerce.channel.model.order.SalesOrderRef、common.ecommerce.channel.model.product.ProductRef。channel.model 按职责拆成 account / order / product / fulfillment / aftersale / settlement 六个子包;枚举在 common.ecommerce.shared.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, ChannelConnection conn);     // 订单视图
    public Products       products(AccountKey key, ChannelConnection conn);        // 商品视图
    public Settlements    settlements(AccountKey key, ChannelConnection conn);     // 账单视图(读)
    public AfterSales     afterSales(AccountKey key, ChannelConnection conn);      // 售后视图(读)
    public Outbounds      outbounds(AccountKey key, ChannelConnection conn);       // 出库/面单/审核视图
    public List<AggregatorCapable.SubChannel> subChannels(AccountKey key, ChannelConnection conn);
    public IdempotencyGuard writes();                                              // 写操作守卫
    public PlatformAdapter resolve(AccountKey key);                                // 按 key 找适配器
}

写类能力(submit / review / edit)挂在 Outbounds 视图上,仍必须经 sdk.writes() 包一层幂等再调用。

门面不做:不选 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(channel) 读渠道账户 ✅ ✅
ChannelSecret 凭据载体,调用时经 ChannelConnection 传入 ✅ ✅
SecretProvider 按 credentialRef 取密钥 已废弃:凭据由调用方传入 — —
TokenStore token 读写(宿主加密) ✅ ✅
LockProvider token 刷新防击穿 ✅ ✅
SyncCursorStore 水位线 批量读 —
Sink(channel) 领域对象落库 批量读 —
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, conn).pull(query)

Page<SalesOrder> page = sdk.salesOrders(key, conn).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, conn).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, conn).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 直连平台为例。核心原则:不改 channel、不改门面、不改宿主。

第 0 步:先想清楚三件事

问题 影响
它属于哪个 Platform? 枚举里有直接用;没有才加(唯一允许改 shared 的地方)
走 DIRECT 还是新聚合器? 新聚合器才加 ChannelProvider 枚举值
它会哪些能力? 只列真能做的

现有枚举(common.ecommerce.shared.model):

  • Platform:AMAZON_SC AMAZON_VC WALMART_SC WALMART_1P TIKTOK TEMU EBAY SHEIN ALIEXPRESS MIRAKL TARGET BESTBUY AEPH WAYFAIR MICHAELS ECHO LOSDLIUS CUSTOM
  • ChannelProvider:DIRECT LINGXING TEAPPLIX CUSTOM

第 1 步:建模块

pom.xml 加 <module>acme</module>,模块依赖:

<dependency>
    <groupId>ecommerce</groupId>
    <artifactId>sdk-common</artifactId>
</dependency>
<dependency>
    <groupId>ecommerce</groupId>
    <artifactId>channel-sdk-core</artifactId>
</dependency>
<dependency>
    <groupId>ecommerce</groupId>
    <artifactId>sdk-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;

// 枚举在 shared.model,渠道域模型在 channel.model
import common.ecommerce.shared.model.Capability;
import common.ecommerce.shared.model.ChannelProvider;
import common.ecommerce.shared.model.Platform;
import common.ecommerce.channel.model.account.ChannelAccount;
import common.ecommerce.channel.model.order.SalesOrder;
import common.ecommerce.channel.model.order.SalesOrderQuery;
import common.ecommerce.channel.model.order.SalesOrderRef;
import common.ecommerce.shared.support.Money;
import common.ecommerce.shared.support.Page;
import common.ecommerce.shared.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 —— 平台字段名的唯一落点

@Getter
@Setter
@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;
}

平台字段名只允许出现在 DTO 和 Mapper 里。

DTO 用 Lombok,领域模型不用。 DTO 是纯数据容器,没有不变量要保护,@Getter/@Setter 省掉全部样板;channel 的模型是不可变 + Builder,本来就没有 setter,且 channel 要尽量少依赖 编译期工具。Lombok 声明为 scope=provided,不进宿主运行时。

端点和路径写成常量,不做配置。 协议细节(URL、字段名、限流值)是代码的一部分—— 配置化会让线上和测试跑不同协议,出问题无法从代码复现。AdapterConfig 不是配置项, 它只承载「测试时替换目标地址」这一种由调用方显式传入的参数。

public final class AcmeConstants {
    /** 生产基址;仅测试/联调时由 AdapterConfig 覆盖。 */
    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;
}

SDK 不碰存储、不读配置。 账户、密钥、token、水位线、幂等记录全部经 SPI 由宿主提供; 适配器构造函数里只接收这些 SPI 与 Clock,不接收 DataSource、Properties 之类的对象。

第 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 里最容易错的三处:

  1. channelOrderId 选了会变的字段(撤销后重下、批次号)→ 每次同步产生新行
  2. 时间没转 UTC → 水位线错位
  3. 金额用了 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());
    }
};

防击穿、提前续期、日志只打指纹,模板都写好了。

要签名的,写静态工具类:

public final class AcmeSigner {
    public static String sign(Map<String, String> params, String appSecret) { ... }
}

签名实现集中在一处,联调时只改这里。

第 6 步:Adapter —— 干活的类

public final class AcmeAdapter implements SalesOrderCapable {

    private final HttpTransport transport;
    private final JacksonJsonCodec json;
    private final Clock clock;
    private final TokenManager tokenManager;
    private final AcmeOrderMapper mapper = new AcmeOrderMapper();

    // 适配器只持有协议与基础设施:端点与凭据随每次调用的 ChannelContext 进来
    public AcmeAdapter(HttpTransport transport, JacksonJsonCodec json,
                       TokenStore tokenStore, LockProvider lockProvider, Clock clock) {
        this.transport = transport;
        this.json = json;
        this.clock = clock;
        final AcmeTokenClient tokenClient = new AcmeTokenClient(transport, json, clock);
        this.tokenManager = new TokenManager(tokenStore, lockProvider, clock, 600) {
            @Override
            protected AccessToken refresh(ChannelSecret secret, AccessToken previous) {
                return tokenClient.fetch(secret.endpointBaseUrl(), 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(ctx.endpointBaseUrl() + AcmeConstants.PATH_ORDERS)   // ★ 端点来自 ctx
                .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();
        // 凭据由调用方经 ChannelConnection 传入,适配器不自己去找
        AccessToken token = tokenManager.getOrRefresh("acme:" + account.externalStoreId(), ctx.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 的四条规矩:

  1. Responses.throwIfNotSuccess 必须调 —— 否则 500 会被当成功解析,报错信息全错。
  2. 不自己造 ChannelContext —— 由门面传入,里面有 requestId 和可测试时钟。
  3. 不用 Instant.now(),用 ctx.clock() 或注入的 clock,否则测试无法固定时间。
  4. 不支持的方法显式抛异常,不返回 null、不返回空 Page。

第 7 步:Factory —— 注册入口

public final class AcmeAdapterFactory implements AdapterFactory {

    private final TokenStore tokenStore;
    private final LockProvider lockProvider;
    private final Clock clock;

    public AcmeAdapterFactory(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) {
        // 生产端点由调用方的 ChannelConnection 提供;config 只用于测试/联调时覆盖目标地址
        return new AcmeAdapter(new OkHttpTransport("common-ecommerce/1.0.0 (acme)"),
                new JacksonJsonCodec(), tokenStore, lockProvider, clock);
    }
}

工厂的意义:把「怎么 new」和「业务怎么用」隔开。宿主只注册工厂,不需要知道构造参数。 工厂不持有凭据——凭据随每次调用的 ChannelConnection 进来。

第 8 步:接进门面

ChannelSdk sdk = ChannelSdk.builder()
        .accountRepository(accountRepo)
        .idempotencyStore(idempotencyStore)      // 要写操作就必须
        .idempotencyOwner(hostName)              // 多实例时区分抢占方
        .register(new AcmeAdapterFactory(tokenStore, lockProvider, clock))
        .build();

AccountKey key = AccountKey.of(ChannelProvider.DIRECT, Platform.AMAZON_SC, "oms-amz-001");
Page<SalesOrder> page = sdk.salesOrders(key, conn).pull(query);

如果你发现要改 ChannelSdk 或 SyncEngine 才能加进去,说明走歪了。

聚合器的额外差异

聚合器(领星这类)与直连只差两点:

  1. 实现 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;
}
  1. 实现 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 层:契约测试(主力)

用 RecordingTransport + 夹具断言「请求怎么拼、响应怎么解」,不联网:

RecordingTransport transport = new RecordingTransport()
        .tokenResponse("{\"data\":{\"access_token\":\"t-1\",\"expires_in\":7200}}")
        .route("/v1/orders", "POST",
                r -> Responses.ok(JsonFixture.load("fixtures/acme/orderList/success.json")));

AcmeAdapter adapter = new AcmeAdapter(transport, json, new InMemoryTokenStore(), locks, fixedClock);
ChannelContext ctx = ChannelContext.of(account, connection, "req-1", fixedClock);

Page<SalesOrder> page = adapter.pull(ctx, query);

HttpRequest last = transport.lastRequest();
assertTrue(last.body().contains("\"updated_after\""));
assertEquals("ACME-1001", page.items().get(0).channelOrderId());

夹具按 src/test/resources/fixtures/{platform}/{operation}/{case}.json 存放,每个平台至少「正常 + 异常」两套。 真实报文跑通后存成新夹具,以后改代码不用再连真实环境。

第 3 层:真实环境冒烟(手动,不进 CI)

做法:凭据用系统属性传入(不要写成常量提交),未提供时用 Assumptions 跳过:

mvn -pl lingxing -am test -Dtest=AcmeLiveSmokeTest \
    -Dacme.probe.appKey=xxx -Dacme.probe.appSecret=yyy
class AcmeLiveSmokeTest {

    private static final String APP_KEY = System.getProperty("acme.probe.appKey", "");
    private static final String APP_SECRET = System.getProperty("acme.probe.appSecret", "");

    private final HttpTransport transport = new OkHttpTransport("common-ecommerce-smoke");

    @Test
    void tokenCanBeFetched() {
        Assumptions.assumeTrue(!APP_KEY.isEmpty() && !APP_SECRET.isEmpty(), "未提供凭据,跳过");
        AccessToken token = new AcmeTokenClient(transport, json, Clock.systemUTC())
                .fetch(BASE_URL, APP_KEY, APP_SECRET);
        assertNotNull(token.value());
    }
}

联调时把请求和响应打出来(token 打码),签名或字段名不对时靠日志定位。 凭证不要提交到仓库(提交历史里的密钥要轮换),联调完重置。

领星尤其注意:真实环境只跑查询类接口。出库、审核发货这类写接口没有测试环境,误操作不可回滚。

第 4 层:分页与水位线

@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

第 5 层:门面 + 能力

@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 结果不同。


七、验收清单

加完一个供应商,逐条打勾:

# 检查项 怎么验
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 channel / shared 零改动 git diff channel/ shared/ 应只有 shared/model/Platform 枚举

八、已知缺口与坑

当前实现状态(2026-11-06)

模块 状态
shared 枚举、异常、SPI 契约、幂等守卫、审计、水位线通用类型全部可用
channel 领域模型、能力接口、门面、SyncEngine、账户/落库 SPI 全部可用
http OkHttp 传输、Jackson 编解码、签名接口、TokenManager 模板可用
testkit InMemory SPI、FakeDirectAdapter、MutableClock 可用
lingxing 16 个子平台:订单 / 店铺全量;商品 8 个平台;结算、售后目前只有亚马逊 SC;出库单 / 面单 / 审核发货 / 订单编辑为 ERP 级、全平台共用
其它平台 未开始

编码坑(按踩到概率排序)

  1. 字段名对不上:DTO 的 @JsonProperty 和真实报文不一致 → 解析出 null。用真实报文做夹具最能防。
  2. capabilities() 写多了:声明 PRODUCT 但没实现 ProductCapable → 门面 ClassCastException。
  3. get 用裸 String:同时实现订单 + 商品就编译不过。用 SalesOrderRef / ProductRef。
  4. 忘记 Responses.throwIfNotSuccess:500 被当成功解析,报错变成「字段为 null」,排查方向全错。
  5. 用了 Instant.now() 而不是 clock:测试无法固定时间,水位线断言随机失败。
  6. canonicalKey 用了会变的字段:同一订单每次同步产生新行。
  7. Responses import 错:http.Responses(状态码→异常)和 testkit.Responses(造响应)是两个类。
  8. UnsupportedCapabilityException 单独 import:它是 ChannelException 的静态内部类,必须写全名。

设计层面的已知缺口

缺口 影响 建议
SalesOrder 没有 platform 字段 Sink 算 canonicalKey 时要额外查平台 给模型加 platform,或让 Sink 接收上下文
适配器不重试 401/429/5xx 只分类不重试 宿主在调用层包退避,或补通用重试器
RawPayloadStore 未实现 原始报文无留痕 新增 SPI + 脱敏
RefundLedger 未实现 无超退校验 与 IdempotencyGuard 配合
DuplicateOrderGuard 未实现 跨 provider 重复订单无告警 新增 SPI
领星时间窗超 31 天被静默截断 水位线落后太多会漏中间段 调用方分段补拉
领星单订单详情未实现 除亚马逊 SC / VC 外的子平台 get() 直接抛异常 用 pull + 时间窗捞
领星限流器用 Thread.sleep 多店并发时按实例数放大 按账户拆适配器实例,或换通用限流器

九、上手顺序

  1. 读三个文件:PlatformAdapter、SalesOrderCapable、ChannelSdk。不到 150 行,看懂这三个就懂一半。
  2. 跑一遍现有测试:mvn -pl lingxing -am test,对照看 LingxingSdkListingCallTest(门面 + 契约)与 LingxingAfterSaleListSourceTest(Source + 夹具)—— 它们就是「加一个供应商」的完整范例。
  3. 抄领星的结构建新模块:Constants → Dto → Mapper → Adapter → Factory → Test。
  4. 先用夹具跑通,再连真实环境。 不要反过来。

常用命令

mvn clean test                                    # 全部
mvn -pl lingxing -am test                         # 单模块(含依赖)
mvn -pl lingxing -am test -Dtest=LingxingSdkListingCallTest    # 单个测试类
mvn -pl lingxing -am test -Dtest=LingxingLiveSmokeTest  # 真实环境冒烟(需环境变量)