Browse Source
- GUIDE.md:心智模型、基接口逐个讲、三条流水线、接入新平台 8 步、5 层测试、验收清单 - LingxingLiveSmokeTest:未配置环境变量时整类跳过,先验认证再验报文,打印脱敏请求响应 Co-Authored-By: Claude <noreply@anthropic.com>feature/supplier-lingxing
2 changed files with 1137 additions and 0 deletions
@ -0,0 +1,984 @@
@@ -0,0 +1,984 @@
|
||||
# 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 步](#五加一个供应商8-步) |
||||
6. [加完之后怎么测](#六加完之后怎么测) |
||||
7. [验收清单](#七验收清单) |
||||
8. [已知缺口与坑](#八已知缺口与坑) |
||||
9. [上手顺序](#九上手顺序) |
||||
|
||||
--- |
||||
|
||||
## 一、一句话心智模型 |
||||
|
||||
这个 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`,是所有调用的隔离维度: |
||||
|
||||
```java |
||||
AccountKey key = AccountKey.of(ChannelProvider.LINGXING, Platform.WALMART_SC, "oms-wm-001"); |
||||
``` |
||||
|
||||
### 为什么要拆开 |
||||
|
||||
同一个沃尔玛店铺,可能**既直连、又走领星**。业务上它是一个店,接入上是两条路。 |
||||
|
||||
由此推出两条硬规则: |
||||
|
||||
1. **业务主键 `canonicalKey` 不带 provider** |
||||
否则切换接入方式时,同一张订单会变成两行。 |
||||
|
||||
```java |
||||
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 个问题。 |
||||
|
||||
```java |
||||
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 能力接口 |
||||
|
||||
供应商实现哪些接口,就声明哪些能力。目前有两个: |
||||
|
||||
```java |
||||
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` |
||||
|
||||
```java |
||||
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)` |
||||
|
||||
```java |
||||
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` |
||||
|
||||
```java |
||||
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) | |
||||
|
||||
**首次全量**要自己回填水位线: |
||||
|
||||
```java |
||||
if (cursorStore.get(provider, accountKey, stream) == null) { |
||||
cursorStore.advance(provider, accountKey, stream, Instant.parse("2026-01-01T00:00:00Z")); |
||||
} |
||||
``` |
||||
|
||||
**`Sink` 怎么写**:SDK 只给 `Page<SalesOrder>`,upsert 的键要自己算: |
||||
|
||||
```java |
||||
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` |
||||
|
||||
```java |
||||
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_SC` `AMAZON_VC` `WALMART_SC` `WALMART_1P` `TIKTOK` `TEMU` `EBAY` `SHEIN` `MIRAKL` `TARGET` `BESTBUY` `AEPH` `CUSTOM` |
||||
- `ChannelProvider`:`DIRECT` `LINGXING` `TEAPPLIX` `CUSTOM` |
||||
|
||||
### 第 1 步:建模块 |
||||
|
||||
`pom.xml` 加 `<module>acme</module>`,模块依赖: |
||||
|
||||
```xml |
||||
<dependency> |
||||
<groupId>apelet</groupId> |
||||
<artifactId>common-ecommerce-core</artifactId> |
||||
</dependency> |
||||
<dependency> |
||||
<groupId>apelet</groupId> |
||||
<artifactId>common-ecommerce-http</artifactId> |
||||
</dependency> |
||||
<dependency> |
||||
<groupId>apelet</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 步:常量类 |
||||
|
||||
```java |
||||
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 —— 平台字段名的唯一落点 |
||||
|
||||
```java |
||||
@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 → 统一模型 |
||||
|
||||
```java |
||||
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 的逻辑: |
||||
|
||||
```java |
||||
TokenManager tm = new TokenManager(tokenStore, lockProvider, clock, 600) { |
||||
@Override |
||||
protected AccessToken refresh(ChannelSecret secret, AccessToken previous) { |
||||
return tokenClient.fetch(secret.appKey(), secret.appSecret()); |
||||
} |
||||
}; |
||||
``` |
||||
|
||||
防击穿、提前续期、日志只打指纹,模板都写好了。 |
||||
|
||||
**要签名的**,实现 `Signer` 或写静态工具类: |
||||
|
||||
```java |
||||
public final class AcmeSigner { |
||||
public static String sign(Map<String, String> params, String appSecret) { ... } |
||||
} |
||||
``` |
||||
|
||||
签名实现集中在一处,联调时只改这里。 |
||||
|
||||
### 第 6 步:Adapter —— 干活的类 |
||||
|
||||
```java |
||||
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 的四条规矩**: |
||||
|
||||
1. `Responses.throwIfNotSuccess` 必须调 —— 否则 500 会被当成功解析,报错信息全错。 |
||||
2. 不自己造 `ChannelContext` —— 由门面传入,里面有 requestId 和可测试时钟。 |
||||
3. 不用 `Instant.now()`,用 `ctx.clock()` 或注入的 `clock`,否则测试无法固定时间。 |
||||
4. 不支持的方法显式抛异常,不返回 `null`、不返回空 `Page`。 |
||||
|
||||
### 第 7 步:Factory —— 注册入口 |
||||
|
||||
```java |
||||
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 步:接进门面 |
||||
|
||||
```java |
||||
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` 才能加进去,说明走歪了。** |
||||
|
||||
### 聚合器的额外差异 |
||||
|
||||
聚合器(领星这类)与直连只差两点: |
||||
|
||||
1. 实现 `AggregatorCapable`,覆写 `supports(account, capability)`,按子平台细化: |
||||
|
||||
```java |
||||
@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; |
||||
} |
||||
``` |
||||
|
||||
2. 实现 `listSubChannels(account)` 列出子渠道。 |
||||
|
||||
**不要为每个子平台建模块** —— 子平台是配置(`platformCode + externalStoreId`),不是代码。 |
||||
|
||||
--- |
||||
|
||||
## 六、加完之后怎么测 |
||||
|
||||
五层,按成本从低到高。**前四层必须全绿才能进真实环境。** |
||||
|
||||
### 第 1 层:纯计算单测(毫秒级) |
||||
|
||||
测 Mapper 和签名器,性价比最高。 |
||||
|
||||
```java |
||||
@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()); |
||||
} |
||||
``` |
||||
|
||||
签名器用**固定向量**: |
||||
|
||||
```java |
||||
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 |
||||
``` |
||||
|
||||
读法: |
||||
|
||||
```java |
||||
String orderJson = Fixtures.load(AcmeAdapterTest.class, "acme", "orderList", "success"); |
||||
``` |
||||
|
||||
测试骨架: |
||||
|
||||
```java |
||||
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 层:分页与水位线 |
||||
|
||||
```java |
||||
@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 层:门面 + 能力 |
||||
|
||||
```java |
||||
@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`:没配环境变量时整类跳过。 |
||||
|
||||
```java |
||||
@EnabledIfEnvironmentVariable(named = "ACME_APP_KEY", matches = ".+") |
||||
class AcmeLiveSmokeTest { |
||||
|
||||
@Test |
||||
void tokenCanBeFetched() { ... } // 先验认证 |
||||
|
||||
@Test |
||||
void pullsOnePage() { ... } // 再验报文 |
||||
} |
||||
``` |
||||
|
||||
包一层 `LoggingTransport` 打印请求响应(Authorization 打码、body 截断)。 |
||||
|
||||
**排错顺序**: |
||||
|
||||
1. 401 / 403 → 先单独跑 token 测试;还失败就查出口 IP 白名单。 |
||||
2. token 通了但接口报签名错 → 只改 `Signer`,跑已知向量。 |
||||
3. 200 但 0 条 → 查时间窗、`platform_code`、`store_id` 是否属于同一店铺。 |
||||
4. 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 | 订单列表拉取可用;商品、履约、面单、账单、售后未实现 | |
||||
| 其它平台 | 未开始 | |
||||
|
||||
### 编码坑(按踩到概率排序) |
||||
|
||||
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 天被静默截断 | 水位线落后太多会漏中间段 | 调用方分段补拉 | |
||||
| 领星单订单详情未实现 | `get()` 直接抛异常 | 用 `pull` + 时间窗捞 | |
||||
| 领星限流器用 `Thread.sleep` | 多店并发时按实例数放大 | 按账户拆适配器实例,或换通用限流器 | |
||||
|
||||
--- |
||||
|
||||
## 九、上手顺序 |
||||
|
||||
1. **读三个文件**:`PlatformAdapter`、`SalesOrderCapable`、`ChannelSdk`。不到 150 行,看懂这三个就懂一半。 |
||||
2. **跑一遍现有测试**:`mvn -pl lingxing -am test`,对照看 `LingxingAdapterTest` —— 它就是「加一个供应商」的完整范例。 |
||||
3. **抄领星的结构**建新模块:`Constants → Dto → Mapper → Adapter → Factory → Test`。 |
||||
4. **先用夹具跑通,再连真实环境。** 不要反过来。 |
||||
|
||||
### 常用命令 |
||||
|
||||
```bash |
||||
mvn clean test # 全部 |
||||
mvn -pl lingxing -am test # 单模块(含依赖) |
||||
mvn -pl lingxing -am test -Dtest=LingxingAdapterTest # 单个测试类 |
||||
mvn -pl lingxing -am test -Dtest=LingxingLiveSmokeTest # 真实环境冒烟(需环境变量) |
||||
``` |
||||
@ -0,0 +1,153 @@
@@ -0,0 +1,153 @@
|
||||
package common.ecommerce.lingxing; |
||||
|
||||
import common.ecommerce.http.HttpRequest; |
||||
import common.ecommerce.http.HttpResponse; |
||||
import common.ecommerce.http.HttpTransport; |
||||
import common.ecommerce.http.JacksonJsonCodec; |
||||
import common.ecommerce.http.OkHttpTransport; |
||||
import common.ecommerce.model.account.AccountKey; |
||||
import common.ecommerce.model.account.ChannelAccount; |
||||
import common.ecommerce.model.ChannelProvider; |
||||
import common.ecommerce.model.support.Page; |
||||
import common.ecommerce.model.Platform; |
||||
import common.ecommerce.model.order.SalesOrder; |
||||
import common.ecommerce.model.order.SalesOrderQuery; |
||||
import common.ecommerce.sdk.ChannelContext; |
||||
import common.ecommerce.spi.AccessToken; |
||||
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 org.junit.jupiter.api.condition.EnabledIfEnvironmentVariable; |
||||
|
||||
import java.time.Clock; |
||||
import java.time.Duration; |
||||
import java.time.Instant; |
||||
import java.time.ZoneOffset; |
||||
|
||||
import static org.junit.jupiter.api.Assertions.assertFalse; |
||||
import static org.junit.jupiter.api.Assertions.assertNotNull; |
||||
import static org.junit.jupiter.api.Assertions.assertTrue; |
||||
|
||||
/** |
||||
* 领星真实环境冒烟测试。未配置凭证时整类跳过。 |
||||
* |
||||
* <pre> |
||||
* export LINGXING_APP_KEY=xxx |
||||
* export LINGXING_APP_SECRET=xxx |
||||
* export LINGXING_STORE_ID=1108413237731 |
||||
* export LINGXING_PLATFORM_CODE=10008 # 可选,默认 Walmart |
||||
* export LINGXING_BASE_URL=https://openapi.lingxing.com # 可选
|
||||
* mvn -pl lingxing -am test -Dtest=LingxingLiveSmokeTest |
||||
* </pre> |
||||
* |
||||
* <p>调用前确认出口 IP 已加入领星白名单,否则会直接 401/403。</p> |
||||
*/ |
||||
@EnabledIfEnvironmentVariable(named = "LINGXING_APP_KEY", matches = ".+") |
||||
class LingxingLiveSmokeTest { |
||||
|
||||
private static final String APP_KEY = System.getenv("LINGXING_APP_KEY"); |
||||
private static final String APP_SECRET = System.getenv("LINGXING_APP_SECRET"); |
||||
private static final String STORE_ID = System.getenv().getOrDefault("LINGXING_STORE_ID", ""); |
||||
private static final int PLATFORM_CODE = Integer.parseInt( |
||||
System.getenv().getOrDefault("LINGXING_PLATFORM_CODE", "10008")); |
||||
private static final String BASE_URL = System.getenv().getOrDefault( |
||||
"LINGXING_BASE_URL", LingxingConstants.DEFAULT_BASE_URL); |
||||
|
||||
private final JacksonJsonCodec json = new JacksonJsonCodec(); |
||||
private final LoggingTransport transport = new LoggingTransport(new OkHttpTransport("common-ecommerce-smoke")); |
||||
private final InMemoryTokenStore tokenStore = new InMemoryTokenStore(); |
||||
private final InMemoryLockProvider locks = new InMemoryLockProvider(); |
||||
private final InMemoryAccounts accounts = new InMemoryAccounts(); |
||||
|
||||
/** 第 1 步:只验证认证。失败说明 appId/appSecret 字段名或环境不对,与订单接口无关。 */ |
||||
@Test |
||||
void tokenCanBeFetched() { |
||||
AccessToken token = new LingxingTokenClient(transport, json, BASE_URL).fetch(APP_KEY, APP_SECRET); |
||||
System.out.println("[token] " + token.fingerprint() + " expiresAt=" + token.expiresAt()); |
||||
assertNotNull(token.value()); |
||||
} |
||||
|
||||
/** 第 2 步:拉一页订单,打印请求与解析结果,人工核对字段映射。 */ |
||||
@Test |
||||
void pullsOnePageOfOrders() { |
||||
LingxingAdapter adapter = adapter(); |
||||
ChannelContext ctx = ChannelContext.of(account(), "smoke-" + System.currentTimeMillis(), |
||||
Clock.systemUTC()); |
||||
|
||||
Instant to = Instant.now(); |
||||
Instant from = to.minus(Duration.ofDays(2)); |
||||
|
||||
Page<SalesOrder> page = adapter.pull(ctx, SalesOrderQuery.builder() |
||||
.updatedAfter(from) |
||||
.updatedBefore(to) |
||||
.pageSize(5) |
||||
.build()); |
||||
|
||||
System.out.println("[orders] window=" + from + " .. " + to |
||||
+ " items=" + page.size() + " nextCursor=" + page.nextCursor()); |
||||
for (SalesOrder o : page.items()) { |
||||
System.out.println(" " + o.channelOrderId() |
||||
+ " status=" + o.status() |
||||
+ " total=" + o.totalAmount() |
||||
+ " country=" + o.shipToCountryCode() |
||||
+ " lines=" + o.lines().size() |
||||
+ " utc=" + o.occurredAt().utc()); |
||||
} |
||||
assertFalse(page.size() > 5, "pageSize 未被平台遵守"); |
||||
} |
||||
|
||||
// ---------------------------------------------------------------- helpers
|
||||
|
||||
private LingxingAdapter adapter() { |
||||
accounts.put(account()).putSecret("smoke", ChannelSecret.builder() |
||||
.appKey(APP_KEY).appSecret(APP_SECRET).build()); |
||||
return new LingxingAdapter(BASE_URL, transport, json, accounts, tokenStore, locks, Clock.systemUTC()); |
||||
} |
||||
|
||||
private ChannelAccount account() { |
||||
return ChannelAccount.builder() |
||||
.key(AccountKey.of(ChannelProvider.LINGXING, Platform.WALMART_SC, "oms-smoke-001")) |
||||
.externalStoreId(STORE_ID) |
||||
.platformCode(PLATFORM_CODE) |
||||
.credentialRef("smoke") |
||||
.marketplaceZone("America/Los_Angeles") |
||||
.currency("USD") |
||||
.build(); |
||||
} |
||||
|
||||
/** 打印真实请求与响应,签名/字段名不对时靠这个定位。Authorization 只打指纹。 */ |
||||
static final class LoggingTransport implements HttpTransport { |
||||
|
||||
private static final int MAX_BODY = 2000; |
||||
|
||||
private final HttpTransport delegate; |
||||
|
||||
LoggingTransport(HttpTransport delegate) { |
||||
this.delegate = delegate; |
||||
} |
||||
|
||||
@Override |
||||
public HttpResponse execute(HttpRequest request) { |
||||
System.out.println("--> " + request.method() + " " + request.url()); |
||||
System.out.println(" headers " + mask(request.headers().toString())); |
||||
System.out.println(" body " + truncate(request.body())); |
||||
HttpResponse response = delegate.execute(request); |
||||
System.out.println("<-- " + response.statusCode() + " (" + response.latencyMillis() + " ms) " |
||||
+ truncate(response.body())); |
||||
return response; |
||||
} |
||||
|
||||
private static String mask(String headers) { |
||||
return headers.replaceAll("(?i)(bearer\\s+)[^,\\]]+", "$1***"); |
||||
} |
||||
|
||||
private static String truncate(String body) { |
||||
if (body == null) { |
||||
return "null"; |
||||
} |
||||
return body.length() <= MAX_BODY ? body : body.substring(0, MAX_BODY) + "...(" + body.length() + " chars)"; |
||||
} |
||||
} |
||||
} |
||||
Loading…
Reference in new issue