API调用调度层设计：如何用Handler分组管理十几个电商平台

折哥|智能物流与Java实战

949人浏览 · 2026-06-30 08:00:00

折哥|智能物流与Java实战 · 2026-06-30 08:00:00 发布

API调用调度层设计：如何用Handler分组管理十几个电商平台

摘要：在多平台电子面单架构中，API调用调度层承担着将统一请求分发到不同平台API的职责。面对奇门、抖音、京东等十几个平台的调用方式差异，我们设计了基于“复合Key路由+Handler分组”的调度方案——核心平台独立Handler，其余平台按调用方式复用，既避免了类爆炸，又保证了灵活性。本文完整拆解了 ApiInvoker 的设计思路、路由机制与工程权衡。

📖 系列导航

系列开篇：从“能跑就行”到“整洁架构”

上一篇：模板方法的组合与继承抉择

本文：API调用调度层Handler分组设计

下一篇：奇门 trade_order_list 排查实录

后续：京东平台、拼多多平台、微信视频号等平台专项篇

一、问题：平台多了，API调用怎么管？

电子面单系统需要对接的电商平台越来越多——奇门（淘宝/天猫）、抖音普通、抖音代发、京东、拼多多、快手、小红书、得物、微信视频号……每个平台的API调用方式各不相同：

平台	调用方式	鉴权机制
奇门（淘宝/天猫）	淘宝SDK	sessionKey
抖音普通	HTTP + 签名	accessToken
抖音代发	HTTP + 签名	代发专属token
京东	HTTP + 签名	accessToken
拼多多	HTTP + 签名	accessToken
微信视频号	HTTP + OAuth2	accessToken（需刷新）

如果每个平台都写一套独立的调用代码，很快就会陷入“类爆炸”——十几个 XxxHandler 内部类，每个类只有几十行代码，维护成本极高。

但如果不加区分地全部塞进一个“万能调用器”里，又会导致超长的 if-else 分支，每次新增平台都要修改核心代码，违反开闭原则。

如何在“类爆炸”和“超长分支”之间找到平衡？我们设计了 “核心独立 + 分组共用”的Handler路由方案。

二、设计思路：按调用方式分组，复合Key路由

2.1 调用方式归纳

仔细分析十几个平台后，我们发现它们其实只属于四种调用方式：

调用类型	典型平台	特征
SDK调用	奇门（淘宝/天猫）	使用平台提供的SDK，需管理sessionKey
HTTP + 简单签名	抖音、京东、拼多多、快手、小红书、得物	JSON请求 + MD5/自定义签名
HTTP + OAuth2	微信视频号	需要token刷新机制
独立核心	抖音普通、京东	高频业务，需要独立监控和优化

2.2 复合Key路由

与策略工厂一样，API调度层使用复合Key定位Handler：

platformCode + "_" + platFormOriginal

平台	platformCode	platFormOriginal	路由Key	Handler
天猫	TM	null	TM_DEFAULT	QiMenHandler
抖音普通	DY	null	DY_DEFAULT	DouYinSampleHandler
抖音代发	DY	DF	DY_DF	SimpleHttpHandler(“douyin_daifa”)
京东	JD	null	JD_DEFAULT	JingDongHandler
拼多多	PDD	null	PDD_DEFAULT	SimpleHttpHandler(“pinduoduo”)

2.3 核心架构图

核心架构图

🏭 设计模式视角：ApiInvoker的设计体现了策略模式和工厂模式的组合——不同的Handler作为策略，由复合Key路由决定最终执行哪个策略。在《Java 23种设计模式：从踩坑到精通》系列的第22篇（策略模式） 和 第3篇（工厂模式） 中，我详细拆解了这两个模式的配合技巧与选型边界，欢迎延伸阅读。

三、核心实现

3.1 RequestHandler 接口

public interface RequestHandler {
    String handle(WaybillContext ctx, Object request, String traceId) throws IOException;
}

3.2 ApiInvoker 实现

public class ApiInvoker {

    private final PlatformConfigCache configCache;
    private final Map<String, RequestHandler> platHandlerMap = new HashMap<>();

    public ApiInvoker(PlatformConfigCache configCache) {
        this.configCache = configCache;
        registerPlatHandlers();
    }

    private void registerPlatHandlers() {
        // 核心平台独立 Handler
        register("TM", null, new QiMenHandler());
        register("TB", null, new QiMenHandler());
        register("OTHER", null, new QiMenHandler());
        register("OTHERS", null, new QiMenHandler());
        register("DY", null, new DouYinSampleHandler());
        register("JD", null, new JingDongHandler());

        // 其他平台共用 SimpleHttpHandler
        register("DY", "DF", new SimpleHttpHandler("douyin_daifa"));
        register("PDD", null, new SimpleHttpHandler("pinduoduo"));
        register("KS", null, new SimpleHttpHandler("kuaishou"));
        register("XHS", null, new SimpleHttpHandler("xiaohongshu"));
        register("DW", null, new SimpleHttpHandler("dewu"));

        // OAuth2 独立处理
        register("WXSPHXD", null, new OAuth2RequestHandler());
    }

    private void register(String platformCode, String platFormOriginal, RequestHandler handler) {
        String key = buildKey(platformCode, platFormOriginal);
        platHandlerMap.put(key, handler);
    }

    private String buildKey(String platformCode, String platFormOriginal) {
        return TocWmsSourcePlatFormType.buildCompositeKey(platformCode, platFormOriginal);
    }

    public String invoke(WaybillContext ctx, Object request, String traceId) throws IOException {
        String platformCode = (String) ctx.getExt().get(WaybillContext.KEY_PLAT_FORM_CODE);
        String platFormOriginal = (String) ctx.getExt().get(WaybillContext.KEY_PLAT_FORM_ORIGINAL);
        String key = buildKey(platformCode, platFormOriginal);

        RequestHandler handler = platHandlerMap.get(key);
        if (handler == null) {
            throw new IOException("未找到对应的处理器: " + key);
        }
        return handler.handle(ctx, request, traceId);
    }
}

3.3 独立Handler示例：奇门

private class QiMenHandler implements RequestHandler {
    @Override
    public String handle(WaybillContext ctx, Object request, String traceId) throws IOException {
        if (!(request instanceof WaybillCloudPrintApplyNewRequest)) {
            throw new IOException("奇门请求类型错误");
        }
        TocPlatFormApp app = configCache.getPlatApp(TocWmsSourcePlatFormType.PLAT_TM_CODE);
        TaobaoClient client = new DefaultTaobaoClient(app.getUrl(), app.getAppkey(), app.getSecret());
        CainiaoWaybillIiGetRequest req = new CainiaoWaybillIiGetRequest();
        req.setParamWaybillCloudPrintApplyNewRequest((WaybillCloudPrintApplyNewRequest) request);
        String sessionKey = (String) ctx.getExt().get(WaybillContext.KEY_SESSION_KEY);
        try {
            CainiaoWaybillIiGetResponse rsp = client.execute(req, sessionKey);
            return rsp.getBody();
        } catch (ApiException e) {
            throw new IOException(e);
        }
    }
}

3.4 共用Handler示例：SimpleHttpHandler

private static class SimpleHttpHandler implements RequestHandler {
    private final String platformType;

    public SimpleHttpHandler(String platformType) {
        this.platformType = platformType;
    }

    @Override
    public String handle(WaybillContext ctx, Object request, String traceId) throws IOException {
        if (!(request instanceof String)) {
            throw new IOException("简单HTTP处理器需要JSON字符串请求");
        }
        String json = (String) request;

        // JDK 1.6 兼容，使用 if-else 而非 switch(String)
        if ("douyin_daifa".equals(platformType)) {
            return invokeDouyinDaifa(ctx, json, traceId);
        } else if ("pinduoduo".equals(platformType)) {
            return invokePinduoduo(ctx, json, traceId);
        } else if ("kuaishou".equals(platformType)) {
            return invokeKuaishou(ctx, json, traceId);
        } else if ("xiaohongshu".equals(platformType)) {
            return invokeXiaohongshu(ctx, json, traceId);
        } else if ("dewu".equals(platformType)) {
            return invokeDewu(ctx, json, traceId);
        }
        throw new IOException("不支持的平台类型: " + platformType);
    }
    // 各平台具体调用方法...
}

四、分组策略：为什么这样分？

4.1 核心平台独立 Handler

奇门、抖音普通、京东这三个平台被设计为独立 Handler，理由是：

高频业务：日均订单量大，独立出来方便性能监控和单独优化。
调用方式独特：奇门使用淘宝SDK，与其他平台的HTTP调用完全不同，无法复用。
问题快速定位：独立Handler意味着独立的日志和异常处理，排查问题更快。

4.2 其他平台共用 SimpleHttpHandler

拼多多、快手、小红书、得物等平台的调用方式相似（HTTP + 自定义签名），共用 SimpleHttpHandler 可以：

减少类膨胀：4_{5个平台只需一个Handler，而不是4}5个类。
统一签名逻辑：如果需要升级签名算法（如从MD5升级到HMAC），只需改一处。
快速接入：新平台只需在 SimpleHttpHandler 中增加一个 else if 分支，开发量最小。

4.3 OAuth2 独立

微信视频号使用 OAuth2 鉴权，与普通HTTP调用的签名方式完全不同，且需要token刷新机制，因此独立为 OAuth2RequestHandler。

4.4 与策略工厂的路由一致性

ApiInvoker 的路由Key与 StrategyFactory 完全一致，都使用 TocWmsSourcePlatFormType.buildCompositeKey 生成复合Key。这意味着：

策略工厂根据 platformCode + original 选择策略
API调度层根据同样的Key选择Handler
两者在路由规则上保持同步，避免“策略对了、Handler错了”的诡异Bug

五、扩展性：新增平台只需要一行注册

5.1 复用SimpleHttpHandler的场景

以新增“支付宝”平台为例，如果其调用方式也是HTTP + 签名，只需要：

在 TocWmsSourcePlatFormType 中增加平台编码常量。

在 registerPlatHandlers() 中增加一行注册：

register("ZFB", null, new SimpleHttpHandler("zhifubao"));

在 SimpleHttpHandler.handle() 中增加一个 else if 分支（短期可接受，长期建议抽成独立Handler）。

5.2 需要独立Handler的场景

如果新平台的调用方式与现有分组都不匹配（比如需要WebSocket连接、私有协议等），则新建一个独立Handler类，实现 RequestHandler 接口，并注册即可。

六、工程权衡与后续演进

当前取舍

1. SimpleHttpHandler 内部仍是超长 if-else

目前 SimpleHttpHandler.handle() 内部通过 if-else 区分各平台。随着共用平台增多，这个方法会越来越长，违反单一职责原则。

短期方案：当分支超过 8 个时，将每个平台的调用逻辑抽取为独立的私有方法，handle 方法只做路由。

长期方案：为每个平台创建独立的Handler实现类，通过 Spring 自动扫描注册，彻底消除超长分支。

2. 硬编码注册，未实现自动扫描

当前所有Handler都在 registerPlatHandlers() 中手动注册，新增平台需修改 ApiInvoker 代码。后续可升级为 Spring Bean 自动装配，实现零代码注册。

后续优化路线图

阶段	优化项	触发条件
短期	SimpleHttpHandler 分支超 8 个时抽取独立方法	渠道数量增长
中期	Handler 改为 Spring Bean，自动扫描注册	渠道稳定后统一升级
长期	引入熔断、重试、限流等容错机制	第三方API稳定性要求