From ee75c199b36282f525e8f3a194a5a719a482da14 Mon Sep 17 00:00:00 2001 From: chenchuchuan <13554600537@163.com> Date: Wed, 4 Nov 2026 09:41:15 +0800 Subject: [PATCH] =?UTF-8?q?docs(sdk):=20=E8=A1=A5=E9=BD=90=20ChannelSdk=20?= =?UTF-8?q?/=20ChannelConnection=20/=20ChannelSecret=20=E5=AD=97=E6=AE=B5?= =?UTF-8?q?=E6=B3=A8=E9=87=8A=EF=BC=9B=E6=96=B0=E5=A2=9E=E6=8B=89=E5=95=86?= =?UTF-8?q?=E5=93=81=E7=A4=BA=E4=BE=8B?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ChannelSdk: - 类注释改成「构建需要三样 + 每次调用需要两样」+ 调用链图 - 每个字段、每个 Builder 方法、每个门面方法补注释(含异常说明) - 明确能力检查发生在 pull() 调用时,不是取视图时 - 明确 clock 的作用(查询终点 + 幂等时间戳)与生产是否要传 ChannelConnection / ChannelSecret: - endpointBaseUrl / appKey / appSecret / clientId / clientSecret / refreshToken 逐个注明是哪个平台用 新增 ProductCallExampleTest(拉商品): - 三段配置分别是什么、拼出的请求长什么样、结果如何映射 - 传输层返回一页固定响应,不联网 Co-Authored-By: Claude --- .../common/ecommerce/sdk/ChannelConnection.java | 3 + .../main/java/common/ecommerce/sdk/ChannelSdk.java | 153 ++++++++++++++--- .../java/common/ecommerce/spi/ChannelSecret.java | 14 ++ .../ecommerce/lingxing/ProductCallExampleTest.java | 182 +++++++++++++++++++++ 4 files changed, 331 insertions(+), 21 deletions(-) create mode 100644 lingxing/src/test/java/common/ecommerce/lingxing/ProductCallExampleTest.java diff --git a/core/src/main/java/common/ecommerce/sdk/ChannelConnection.java b/core/src/main/java/common/ecommerce/sdk/ChannelConnection.java index 3d30508..baa6501 100644 --- a/core/src/main/java/common/ecommerce/sdk/ChannelConnection.java +++ b/core/src/main/java/common/ecommerce/sdk/ChannelConnection.java @@ -15,7 +15,10 @@ import java.util.Objects; */ public final class ChannelConnection { + /** 目标基址,如 {@code https://openapi.lingxing.com};末尾斜杠会被去掉。 */ private final String endpointBaseUrl; + + /** 凭据;端点会被写回其中,供 token 刷新回调使用。 */ private final ChannelSecret secret; private ChannelConnection(String endpointBaseUrl, ChannelSecret secret) { diff --git a/core/src/main/java/common/ecommerce/sdk/ChannelSdk.java b/core/src/main/java/common/ecommerce/sdk/ChannelSdk.java index 3429374..8599d67 100644 --- a/core/src/main/java/common/ecommerce/sdk/ChannelSdk.java +++ b/core/src/main/java/common/ecommerce/sdk/ChannelSdk.java @@ -29,23 +29,60 @@ import java.util.Objects; import java.util.UUID; /** - * 渠道 SDK 统一门面。 + * 渠道 SDK 统一门面。业务层只依赖本类。 * - *

业务层只依赖本类,不直接感知平台协议。所有外部副作用经 SPI 注入, - * SDK 自身不访问数据库 / Redis / MQ,也不持有线程或定时器。

+ *

构建它需要三样东西

+ *
    + *
  1. 账户仓库({@link ChannelAccountRepository}):按 AccountKey 找到账户配置。 + * 必需。SDK 不碰数据库,由宿主实现。
  2. + *
  3. 适配器({@link PlatformAdapter} 或 {@link AdapterFactory}):真正干活的实现。 + * 至少注册一个。注册的维度是 {@code provider + platform}。
  4. + *
  5. 幂等存储({@link IdempotencyStore}):只有写操作需要。不注入时 + * {@link #writes()} 会直接失败。
  6. + *
* - *

provider 由调用方在 {@link AccountKey} 中显式指定,SDK 不推荐、 - * 不自动选路、不自动兜底;能力缺失时抛 - * {@code ChannelException.UnsupportedCapabilityException}。

+ *

每次调用还需要两样东西

+ * * - *

连接信息由调用方每次传入,见 {@link ChannelConnection}:SDK 不保存端点、 - * 不读配置、不读环境变量。门面只负责按 {@link AccountKey} 找账户与适配器。

+ *

调用链

+ *
+ * AccountKey ──→ 账户仓库找 ChannelAccount ──┐
+ *                                           ├──→ ChannelContext ──→ 适配器方法
+ * ChannelConnection ────────────────────────┘
+ * 
+ * + *

SDK 不访问数据库 / Redis / MQ,也不持有线程或定时器。

*/ public final class ChannelSdk implements ProviderResolver { + /** + * 已注册的适配器。 + * + *

键是 {@code "PROVIDER|PLATFORM"},如 {@code "LINGXING|WALMART_SC"}。 + * 同一组合只能有一个适配器。

+ */ private final Map adapters; + + /** 账户仓库:把 AccountKey 解析成 ChannelAccount。宿主实现(典型 MySQL)。 */ private final ChannelAccountRepository accountRepository; + + /** + * 时钟。 + * + *

生产用默认 {@link Clock#systemUTC()} 即可;测试注入固定时钟, + * 让「不传 updatedBefore 时终点取现在」这类逻辑可重复断言。

+ */ private final Clock clock; + + /** + * 写操作幂等守卫。 + * + *

只有在 {@code Builder.idempotencyStore(...)} 注入后才有值; + * 否则为 {@code null},{@link #writes()} 直接抛异常。

+ */ private final IdempotencyGuard idempotencyGuard; private ChannelSdk(Builder b) { @@ -63,19 +100,35 @@ public final class ChannelSdk implements ProviderResolver { // ------------------------------------------------------------------ 门面方法 - /** 能力矩阵,只读,不触发任何真实 API。 */ + /** + * 能力矩阵:这个账户支持哪些能力。 + * + *

只读,不触发任何真实 API。聚合器(如领星)会按子平台细化, + * 例如领星下 eBay 只有订单、沃尔玛有订单和商品。

+ * + * @param key 账户标识;账户未配置时抛 {@link IllegalStateException} + * @throws IllegalStateException 账户未配置,或该 provider+platform 没有适配器 + */ public CapabilityReport capabilities(AccountKey key) { ChannelAccount account = requireAccount(key); return new AdapterCapabilityReport(resolve(key), account); } - /** 3P 销售订单视图。 */ + /** + * 3P 销售订单视图。 + * + *

能力检查发生在 {@code pull()} 调用时,不是取视图时。

+ */ public SalesOrders salesOrders(AccountKey key, ChannelConnection connection) { ChannelAccount account = requireAccount(key); return new SalesOrders(resolve(key), account, newContext(account, connection)); } - /** 商品 / Listing 视图。 */ + /** + * 商品 / Listing 视图。 + * + *

能力检查发生在 {@code pull()} 调用时,不是取视图时。

+ */ public Products products(AccountKey key, ChannelConnection connection) { ChannelAccount account = requireAccount(key); return new Products(resolve(key), account, newContext(account, connection)); @@ -87,7 +140,11 @@ public final class ChannelSdk implements ProviderResolver { return new Settlements(resolve(key), account, newContext(account, connection)); } - /** 履约 / 出库视图。 */ + /** + * 履约 / 出库视图。 + * + *

写操作:会改变平台数据。领星没有测试环境,验证阶段禁止调用。

+ */ public Outbounds outbounds(AccountKey key, ChannelConnection connection) { ChannelAccount account = requireAccount(key); return new Outbounds(resolve(key), account, newContext(account, connection)); @@ -96,9 +153,10 @@ public final class ChannelSdk implements ProviderResolver { /** * 聚合器的子店铺列表(如领星下已授权的亚马逊 / 沃尔玛店铺)。 * - *

调用方拿到 {@code platformCode + externalStoreId} 后,用来构造 - * {@link ChannelAccount},业务调用仍走 {@link AccountKey}。 - * 非聚合器适配器会抛 {@code UnsupportedCapabilityException}。

+ *

典型用途是首次接入:把 platformCode + externalStoreId 拉下来, + * 落成 {@link ChannelAccount} 配置。日常业务调用不需要它。

+ * + * @throws IllegalStateException 该 provider 的适配器不是聚合器(未实现 AggregatorCapable) */ public List subChannels(AccountKey key, ChannelConnection connection) { ChannelAccount account = requireAccount(key); @@ -122,7 +180,11 @@ public final class ChannelSdk implements ProviderResolver { return idempotencyGuard; } - /** 按 AccountKey 解析适配器;不自动选路、不自动兜底。 */ + /** + * 按 AccountKey 解析适配器;不自动选路、不自动兜底。 + * + * @throws IllegalStateException 该 provider + platform 没有注册适配器 + */ @Override public PlatformAdapter resolve(AccountKey key) { PlatformAdapter adapter = adapters.get(registryKey(key)); @@ -135,11 +197,13 @@ public final class ChannelSdk implements ProviderResolver { // ------------------------------------------------------------------ internals + /** 按 provider + platform + omsStoreId 找账户;找不到就是配置缺失,不是运行时错误。 */ private ChannelAccount requireAccount(AccountKey key) { return accountRepository.findByKey(key.provider().name(), key.platform().name(), key.omsStoreId()) .orElseThrow(() -> new IllegalStateException("channel account not configured: " + key)); } + /** 组装单次调用的上下文:账户 + 连接 + 链路 ID + 时钟。 */ private ChannelContext newContext(ChannelAccount account, ChannelConnection connection) { return ChannelContext.of(account, connection, UUID.randomUUID().toString(), clock); } @@ -151,28 +215,59 @@ public final class ChannelSdk implements ProviderResolver { // ------------------------------------------------------------------ builder + /** + * 门面构建器。 + * + *

最少配置:{@code accountRepository(...)} + 至少一个 {@code register(...)}。

+ */ public static final class Builder { + /** 适配器注册表,键为 provider|platform。 */ private final Map adapters = new LinkedHashMap(); + + /** 待创建的工厂;{@link #build()} 时统一 create 并注册。 */ private final List factories = new ArrayList(); + + /** 账户仓库,必需。 */ private ChannelAccountRepository accountRepository; + + /** 幂等存储,写操作需要;只读场景可以不注入。 */ private IdempotencyStore idempotencyStore; + + /** 幂等抢占方标识,多实例部署时应能区分;缺省随机 UUID。 */ private String idempotencyOwner = UUID.randomUUID().toString(); + + /** 时钟,默认 UTC;测试注入固定时钟。 */ private Clock clock = Clock.systemUTC(); - /** 注入账户仓库;宿主实现。 */ + /** + * 注入账户仓库。必需。 + * + *

SDK 用它把 {@link AccountKey} 解析成 {@link ChannelAccount}; + * 没注入时 {@link #build()} 直接失败。

+ */ public Builder accountRepository(ChannelAccountRepository accountRepository) { this.accountRepository = accountRepository; return this; } - /** 注入时钟;测试可给固定时间。 */ + /** + * 注入时钟,默认 {@link Clock#systemUTC()}。 + * + *

作用:查询未传 {@code updatedBefore} 时的终点时间,以及幂等记录的时间戳。 + * 生产一般不用传;测试传 {@code Clock.fixed(...)} 让断言可重复。

+ */ public Builder clock(Clock clock) { this.clock = clock; return this; } - /** 注入幂等存储;不注入时调用 {@link ChannelSdk#writes()} 会失败。 */ + /** + * 注入幂等存储。只有写操作需要。 + * + *

不注入时 {@link ChannelSdk#writes()} 直接抛异常; + * 只做查询的场景可以不注入。

+ */ public Builder idempotencyStore(IdempotencyStore idempotencyStore) { this.idempotencyStore = idempotencyStore; return this; @@ -184,12 +279,19 @@ public final class ChannelSdk implements ProviderResolver { return this; } - /** 注册适配器工厂;工厂覆盖的平台会在 build 时创建并注册。 */ + /** + * 注册适配器工厂。 + * + *

生产推荐这种写法:工厂在 {@link #build()} 时调用 {@code create(...)}, + * 适配器需要的基础设施(传输层、编解码、token 存储)由工厂自己装配, + * 宿主不用关心构造参数。

+ */ public Builder register(AdapterFactory factory) { this.factories.add(Objects.requireNonNull(factory, "factory")); return this; } + /** 批量注册工厂。 */ public Builder registerAll(Collection factories) { if (factories != null) { for (AdapterFactory f : factories) { @@ -199,7 +301,12 @@ public final class ChannelSdk implements ProviderResolver { return this; } - /** 直接注册适配器实例,主要用于测试替身。 */ + /** + * 直接注册适配器实例。 + * + *

主要用于测试替身、或需要替换传输层的场景。 + * 生产优先用 {@link #register(AdapterFactory)}。

+ */ public Builder register(PlatformAdapter adapter) { Objects.requireNonNull(adapter, "adapter"); for (Platform p : adapter.platforms()) { @@ -212,6 +319,9 @@ public final class ChannelSdk implements ProviderResolver { * 构建门面。 * *

缺必需配置时立刻失败,而不是返回一个不可用的空对象。

+ * + * @throws IllegalStateException 缺 accountRepository、缺时钟、 + * 一个适配器都没注册、或同一 provider+platform 注册两次 */ public ChannelSdk build() { if (accountRepository == null) { @@ -230,6 +340,7 @@ public final class ChannelSdk implements ProviderResolver { return new ChannelSdk(this); } + /** 注册单个适配器,键为 provider|platform;重复注册不同实例直接失败。 */ private void put(String key, PlatformAdapter adapter) { PlatformAdapter previous = adapters.put(key, adapter); if (previous != null && previous != adapter) { diff --git a/core/src/main/java/common/ecommerce/spi/ChannelSecret.java b/core/src/main/java/common/ecommerce/spi/ChannelSecret.java index b1c9d2b..87bbde5 100644 --- a/core/src/main/java/common/ecommerce/spi/ChannelSecret.java +++ b/core/src/main/java/common/ecommerce/spi/ChannelSecret.java @@ -4,14 +4,28 @@ import java.util.Objects; /** * 凭证内容。按 provider 需要取用,未使用的字段为 null。 + * + *

整体由调用方在每次调用时通过 {@code ChannelConnection} 传入,SDK 不落盘。 + * 日志只能用 {@link #fingerprint()},禁止打印原始值。

*/ public final class ChannelSecret { + /** 目标基址;由 ChannelConnection 构造时写回,供 TokenManager 的刷新回调使用。 */ private final String endpointBaseUrl; + + /** 应用标识。领星:appId(同时作为签名 AES 密钥,长度须为 16/24/32 字节)。 */ private final String appKey; + + /** 应用密钥。领星:appSecret;用于换 token 与签名。 */ private final String appSecret; + + /** OAuth 客户端 ID。亚马逊 LWA、沃尔玛使用。 */ private final String clientId; + + /** OAuth 客户端密钥。亚马逊 LWA、沃尔玛使用。 */ private final String clientSecret; + + /** 长期刷新令牌。亚马逊 LWA、TikTok 使用。 */ private final String refreshToken; private ChannelSecret(Builder b) { diff --git a/lingxing/src/test/java/common/ecommerce/lingxing/ProductCallExampleTest.java b/lingxing/src/test/java/common/ecommerce/lingxing/ProductCallExampleTest.java new file mode 100644 index 0000000..8567e14 --- /dev/null +++ b/lingxing/src/test/java/common/ecommerce/lingxing/ProductCallExampleTest.java @@ -0,0 +1,182 @@ +package common.ecommerce.lingxing; + +import common.ecommerce.http.HttpResponse; +import common.ecommerce.http.HttpTransport; +import common.ecommerce.lingxing.adapter.LingxingAdapter; +import common.ecommerce.model.ChannelProvider; +import common.ecommerce.model.Platform; +import common.ecommerce.model.account.AccountKey; +import common.ecommerce.model.account.ChannelAccount; +import common.ecommerce.model.product.ProductListing; +import common.ecommerce.model.product.ProductQuery; +import common.ecommerce.model.support.Page; +import common.ecommerce.sdk.ChannelConnection; +import common.ecommerce.sdk.ChannelSdk; +import common.ecommerce.spi.ChannelSecret; +import common.ecommerce.testkit.InMemoryAccounts; +import common.ecommerce.testkit.InMemoryLockProvider; +import common.ecommerce.testkit.InMemoryTokenStore; +import org.junit.jupiter.api.Test; + +import java.time.Clock; +import java.time.Instant; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertNotNull; + +/** + * 从 ChannelSdk 拉商品的完整示例。 + * + *

这是用法文档,不是契约测试。传输层返回一页固定的领星 Listing 响应, + * 目的是让你看清:三段配置分别是什么、拼出来的请求长什么样、结果如何映射成统一模型。

+ */ +class ProductCallExampleTest { + + /** 领星生产域名。SDK 不保存它,每次调用通过 ChannelConnection 传入。 */ + private static final String ENDPOINT = "https://openapi.lingxing.com"; + + // ==================== 第 1 段:账户 ==================== + + /** 你自己的店铺 ID,业务归属维度。 */ + private static final String OMS_STORE_ID = "oms-wm-001"; + + /** 领星侧的店铺 ID(store_id)。 */ + private static final String LINGXING_STORE_ID = "1108413237731"; + + /** 领星平台码:10008 = Walmart,10001 = Amazon SC。 */ + private static final int PLATFORM_CODE = 10008; + + /** + * 领星 AppID。同时作为签名用的 AES 密钥,长度必须是 16/24/32 字节, + * 否则 LingxingSigner 会直接拒绝。 + */ + private static final String APP_KEY = "test-app-id-1234"; + + /** 领星 AppSecret。 */ + private static final String APP_SECRET = "test-app-secret"; + + /** 账户:告诉 SDK「这是哪个店铺」,SDK 用它校验归属、拼请求参数。 */ + private static ChannelAccount account() { + return ChannelAccount.builder() + // provider + platform + omsStoreId:三个一起决定用哪个适配器 + .key(AccountKey.of(ChannelProvider.LINGXING, Platform.WALMART_SC, OMS_STORE_ID)) + // 领星 store_id,会拼进请求体的 store_ids + .externalStoreId(LINGXING_STORE_ID) + // 领星 platform_code,会拼进请求体的 platform_code + .platformCode(PLATFORM_CODE) + // 密钥引用;本 SDK 目前不使用(密钥从 ChannelConnection 传) + .credentialRef("kms://test/lingxing") + // 市场时区,必须能被 ZoneId.of 解析;影响返回时间的当地视图 + .marketplaceZone("America/Los_Angeles") + // 店铺币种 + .currency("USD") + .build(); + } + + // ==================== 第 2 段:连接 ==================== + + /** 连接:告诉 SDK「这次连哪里、用谁的身份」。每次调用都可以不同(换环境、换 app)。 */ + private static ChannelConnection connection() { + return ChannelConnection.of(ENDPOINT, ChannelSecret.builder() + .appKey(APP_KEY) // 领星 AppID + .appSecret(APP_SECRET) // 领星 AppSecret + .build()); + } + + // ==================== 第 3 段:构建 SDK ==================== + + /** 构建 SDK:账户仓库 + 适配器。写操作才需要幂等存储。 */ + private static ChannelSdk buildSdk(HttpTransport transport) { + InMemoryAccounts accounts = new InMemoryAccounts().put(account()); + + // 生产写法是 .register(new LingxingAdapterFactory(tokenStore, lockProvider, clock)), + // 工厂内部会 new OkHttpTransport;这里为了接管网络层,直接注册适配器实例。 + LingxingAdapter adapter = new LingxingAdapter(transport, + new common.ecommerce.http.JacksonJsonCodec(), + new InMemoryTokenStore(), new InMemoryLockProvider(), Clock.systemUTC()); + + return ChannelSdk.builder() + .accountRepository(accounts) // 必需:按 AccountKey 找账户 + .register(adapter) // 必需:至少一个适配器 + .build(); + } + + // ==================== 调用 ==================== + + @Test + void pullProductsThroughSdk() { + FixedResponseTransport transport = new FixedResponseTransport(); + ChannelSdk sdk = buildSdk(transport); + + // 每次调用都传 AccountKey + ChannelConnection + AccountKey key = AccountKey.of(ChannelProvider.LINGXING, Platform.WALMART_SC, OMS_STORE_ID); + + Page page = sdk.products(key, connection()).pull(ProductQuery.builder() + .updatedAfter(Instant.parse("2026-11-01T00:00:00Z")) // 可选 + .updatedBefore(Instant.parse("2026-11-04T00:00:00Z")) // 可选,不传则用 SDK 时钟 + .pageSize(20) // 平台上限内自动截断 + .build()); + + // 解析结果:领星字段 → 统一模型 + assertEquals(1, page.size()); + ProductListing p = page.items().get(0); + assertEquals("wal-0726-102", p.platformSku()); // ← msku + assertEquals("FBSPORT Round Inflatable", p.title()); // ← title + assertEquals(Platform.WALMART_SC, p.platform()); + assertEquals(OMS_STORE_ID, p.omsStoreId()); + assertEquals("USD", p.currency()); // ← currency_icon "$" 映射 + assertEquals("139.90", p.price().amount().toPlainString()); + assertNotNull(p.attributes().get("store_name")); // 未标准化的原始字段 + } + + @Test + void requestBodyCarriesAccountParameters() { + FixedResponseTransport transport = new FixedResponseTransport(); + ChannelSdk sdk = buildSdk(transport); + AccountKey key = AccountKey.of(ChannelProvider.LINGXING, Platform.WALMART_SC, OMS_STORE_ID); + + sdk.products(key, connection()).pull(ProductQuery.builder().pageSize(20).build()); + + // 第一次是换 token,第二次是拉商品 + assertEquals(2, transport.requests.size()); + String productBody = transport.requests.get(1).body(); + + // 账户里的四个参数分别落到请求里 + assertTrueContains(productBody, "\"store_ids\":[\"" + LINGXING_STORE_ID + "\"]"); + assertTrueContains(productBody, "\"offset\":0"); + assertTrueContains(productBody, "\"length\":20"); + // 时间窗按 UTC 日期发送 + assertTrueContains(transport.requests.get(1).url(), "/basicOpen/multiplatform/walmart/list"); + } + + private static void assertTrueContains(String haystack, String needle) { + org.junit.jupiter.api.Assertions.assertTrue(haystack.contains(needle), + "期望包含 " + needle + ",实际:" + haystack); + } + + /** + * 固定响应传输层:令牌请求返回最小 token 响应,商品请求返回一页沃尔玛 Listing。 + */ + static final class FixedResponseTransport implements HttpTransport { + + final java.util.List requests = + new java.util.ArrayList(); + + @Override + public HttpResponse execute(common.ecommerce.http.HttpRequest request) { + requests.add(request); + if (request.url().contains("/oauth/access-token")) { + return HttpResponse.of(200, java.util.Collections.emptyMap(), + "{\"code\":\"200\",\"msg\":\"OK\",\"data\":{\"access_token\":\"tok-1\"," + + "\"refresh_token\":\"ref-1\",\"expires_in\":7199}}", 1); + } + return HttpResponse.of(200, java.util.Collections.emptyMap(), + "{\"code\":0,\"message\":\"success\",\"total\":1,\"data\":{\"list\":[{" + + "\"item_id\":\"wal-0726-102\",\"msku\":\"wal-0726-102\"," + + "\"title\":\"FBSPORT Round Inflatable\",\"picture_url\":\"\"," + + "\"status_name\":\"PUBLISHED\",\"store_id\":\"" + LINGXING_STORE_ID + "\"," + + "\"store_name\":\"测试店铺\",\"currency_icon\":\"$\",\"price\":\"139.90\"," + + "\"gtin\":\"00723849594300\"}]}}", 1); + } + } +}