从五套 if-else 到一层适配:多货源平台接入的架构演进

简介: 摘要:同时对接几个批发货源平台,第一版通常是一堆条件分支。这篇把演进过程拆成四段,每段都说明「什么时候必须进到这一步」,避免过早架构,也避免拖到重构成本无法承受。


一、第一版长什么样

先说第一版,因为它并不丢人。

业务要跑通「海外用户下单 → 系统去货源平台采购」,最先写的代码一定是这样的:

def fetch_goods(source, goods_id):
    if source == "A":
        signed = sign_a(params, secret_a)
        resp = call_a("/item/get", signed)
        return {"title": resp["item"]["subject"], "price": resp["item"]["price"], ...}
    elif source == "B":
        signed = sign_b(params, secret_b)
        resp = call_b("/product/detail", signed)
        return {"title": resp["name"], "price": resp["skuPrice"], ...}
    elif source == "C":
        ...

接第一个货源时,这段代码很好懂。接第二个开始,你会在每个方法里复制一遍结构。接第三个的时候,你发现改一个共同逻辑(比如加超时重试)要改三处,而且很容易漏。

那次我们的分水岭很具体:要给所有货源调用加「超时后重试一次 + 记录 trace_id」,结果改了六个方法,漏了一个,上线后那一类请求的日志里没有 trace_id,排查时抓瞎半天。

二、演进四段路

image.png

图:四段演进。判断该不该进下一步的标准不是「代码丑不丑」,而是「新增一个货源要改几处」。

第一段:条件分支。 判据:货源数量 ≤ 2,且你还在验证业务。这个阶段别急着抽象,抽象错了比不抽象更贵。

第二段:抽适配层。 判据:出现「同一处改动要在三个以上分支重复改」。做法是把差异收敛到适配器里,上层只认两个参数:source 和 goods_id。这一步是分水岭,做完之后新增货源只是新增一个适配器类。

第三段:配额与限流分层。 判据:开始出现「因为某个货源限流,导致整批同步全部失败」。注意是每个货源独立的令牌桶和熔断器,共用一个等于没做。

第四段:元数据配置化。 判据:适配器数量超过五个,且改动多是「字段映射变了」这类低价值变更。把它们落成数据表,接入就从「一次小项目」变成「一次配置」。

三、适配层的核心代码

这是第二段的核心,一个最小可用的适配器骨架:

from abc import ABC, abstractmethod
from dataclasses import dataclass
@dataclass
class Goods:
    """内部标准模型:上层只见这个结构,不见任何货源字段。"""
    source: str
    source_id: str
    title: str
    price_cents: int      # 一律用「分」存整数,避免浮点误差
    currency: str
    stock: int
class SourceAdapter(ABC):
    name: str = ""
    @abstractmethod
    def sign(self, params: dict) -> dict:
        """差异点一:签名规则,各家不同。"""
    @abstractmethod
    def to_goods(self, raw: dict) -> Goods:
        """差异点二:字段映射,各家命名不同。"""
    @abstractmethod
    def map_error(self, code: str) -> str:
        """差异点三:错误码翻译成内部码。"""
class AdapterRegistry:
    _adapters = {}
    @classmethod
    def register(cls, adapter: SourceAdapter):
        cls._adapters[adapter.name] = adapter
    @classmethod
    def get(cls, source: str) -> SourceAdapter:
        if source not in cls._adapters:
            raise KeyError("未注册的货源: %s" % source)
        return cls._adapters[source]
class WholesaleA(SourceAdapter):
    name = "source_a"
    def sign(self, params):
        # 示意:参数排序后拼接再哈希,细节按各家文档来
        pairs = sorted((k, str(v)) for k, v in params.pairs_iter() if k != "sign")
        raw = "&".join("%s=%s" % (k, v) for k, v in pairs)
        params["sign"] = hash_with_secret(raw, SECRET_A)
        return params
    def to_goods(self, raw):
        return Goods(
            source=self.name,
            source_id=raw["itemId"],
            title=raw["subject"],
            price_cents=int(round(float(raw["price"]) * 100)),
            currency="CNY",
            stock=int(raw.get("quantity", 0)),
        )
    def map_error(self, code):
        return {"SIGN_INVALID": "AUTH_FAILED", "FLOW_LIMIT": "RATE_LIMITED"}.get(code, "UPSTREAM_ERR")

有几个细节值得留意:

第一,price_cents 用整数分。 三家的价格字段一个是字符串、一个是浮点、一个是分。在适配器里一次性转成整数,上层永远不和浮点数打交道。

第二,map_error 必须实现。 很多团队只做字段映射不做错误码映射,结果上层要 if code == "xxx" 才能判断是否限流——差异又漏回去了。把错误码翻译成内部五六个枚举,上层只判断 RATE_LIMITED 就够了。

第三,注册表用 name 而不是类名。 这是为了让第三段的「每个货源独立限流」能按 name 找到对应的桶和熔断器,不用额外维护一张映射表。

四、第二段做完之后,数据能说明什么

改造前后的对比只统计我们自己的系统,没有外部数据:

指标 改造前(三货源分支) 改造后(适配层)
新增一个货源需要改的文件数 6 1(新增适配器)
加一条通用重试逻辑要改的位置 3 处以上,容易漏 1 处(适配层统一)
上层业务代码里出现的货源判断 40 余处 0
字段口径争议(价格单位不一致) 每月 2-3 次 基本消失

需要注意的是,这些是我们自己的工作量统计,不代表别人的系统,但方向是通用的:适配层的收益和货源数量成正比,成本是一次性的。

五、检查清单

  • 上层业务代码里没有任何货源名称的字符串判断
  • 所有金额以整数分进入内部模型,浮点只在适配器内部出现
  • 每个适配器都实现错误码映射,内部错误码不超过十个
  • 适配器注册表以稳定标识注册,不依赖类名
  • 每个货源有独立的限流桶与熔断器,参数可配
  • 适配器有独立的契约测试:同一份样例报文,映射结果固定
  • 新增货源只需要新增一个文件 + 一段配置,不改业务代码
  • 签名逻辑只出现在适配器里,业务层永远不接触密钥
  • 适配层的每次上游调用都带 trace_id

六、一句总结

架构演进这件事,判断标准不是「看起来是否优雅」,而是「下一次同类改动要花多少时间」。当答案是「又要改六处」的时候,就该抽那一层了。

做代购、集运、转运的团队,货源平台只会越接越多,这一层迟早要建。早建不一定好,但拖到第十个货源再建,代价会高很多。

相关文章
|
26天前
|
人工智能 调度 虚拟化
OPPO Reno15 端侧多模型本地部署:选型、参数调优与功耗控制
本方案基于OPPO Reno15(骁龙8+),采用MNN引擎部署三款Qwen量化模型,构建“写作—思辨—技术”分工协作的本地AI工作流。坚持fp16精度、优先调用NPU、差异化采样与输出限制,兼顾能力、速度、发热与续航,全部配置应用内可直接启用。
275 2
|
2月前
|
人工智能 搜索推荐 JavaScript
GEO文章发布后为什么仍可能失效?
GEO文章发布后失效,常因内容无法长期存活。本文提出“六层验证模型”:Survive(存活)→Retrieve→Read→Use→Cite→Recommend,强调内容须先稳定公开、可访问、可验证,方能成为AI可信信源。官网为原始事实源,第三方平台仅作传播放大器。(239字)
367 10
|
2月前
|
人工智能
GEO虚假信源正在泛滥,我们公开了第一批疑似风险渠道
GEO行业高速增长,但“信源造假”频发:山寨域名、品牌仿冒、文档伪装媒体等乱象丛生。GEO信源网上线开源风险核验体系(GitHub:315fang/fake-geo-channels),已识别306台风险主机、951条可疑目录,全部标注“疑似风险”,支持申诉与复核,推动信源透明化、可验证、可追溯。(239字)
426 9
|
4月前
|
人工智能
Qwen3.8抢先体验!正式版即将发布并开源!
千问Qwen3.8即将开源,参数达2.4T,进化速度以“天”计,实力媲美Fable 5。预览版Qwen3.8-Max已上线阿里Token Plan等平台,限时优惠:日间Credits低至1折,夜间更优,个人/团队版月付仅35元起!
6903 233
|
22天前
异步任务查询侧的三态判定:找不到、问不到与真失败
任务号查不到,不等于任务失败。本文把「查不到」拆成四种处境,给出查询侧的三态判定(找到/明确不存在/没问成)、一张按「查询结论 × 已等时长 × 提交有无回执」落格的判定表,以及轮询密度与查询限额的定量关系。
|
1月前
|
人工智能 分布式计算 安全
周一上线 | DeepSeek 开始卷“许愿式编程”,Agent 手机来了,Character.AI 申请破产
本周AI前沿加速演进:DeepSeek发布V4.1-Flash-1017,强化“许愿式编程”与3D建模;Gemini 4 Argon、Meta Muse系列、Glimpse聚焦复杂工程与视觉推理;Anthropic自研Scion版本系统,阶跃推出Agent手机STEPX Neo。
275 0
周一上线 | DeepSeek 开始卷“许愿式编程”,Agent 手机来了,Character.AI 申请破产
|
22天前
|
测试技术
接口文档示例值的四个陷阱与上线前检查清单
文档示例是样例不是契约。照示例开发,枚举缺全集、金额单位错、错误分支无样例、示例版本滞后,四类问题全部在上线后才暴露。本文给出四陷阱成因、一段示例漂移检测代码与七项上线前检查清单。
|
22天前
|
缓存 测试技术
联调排查的五步链:现场定格、最小直连与字段二分
本文给出一套带出口判据的五步排查链:定格现场、最小直连、环境对照、字段二分、带证据提问,每步把可能原因砍掉一半。
|
23天前
|
监控 中间件 测试技术
请求头的体积预算:三道闸、四个膨胀源与两道治理动作
调用量掉零、业务日志空白、网关层只有 400——请求头越过某一层闸门时,业务侧全程失明。本文给出四个膨胀源的识别、三道闸的默认值差异、体积预算的统一口径,以及「装秤」与「挪数据」两个治理动作,附验收标准。
|
26天前
|
弹性计算 运维 监控
弹性伸缩 ESS 实践:千里达票务系统节假日自动扩缩容
最头疼的事:国庆前两周就开始加ECS,加少了怕扛不住,加多了节后闲置一个月。接入阿里云ESS弹性伸缩:最小4台/最大20台,CPU>60%持续3分钟加2台、<30%持续10分钟减1台,接ARMS接口P99>500ms也触发扩容。启动模板预装JDK/监控Agent,userdata只拉配置。踩坑复盘(冷启动JVM预热、优雅缩容、镜像版本管理、节假日定时预扩)。平峰成本降40%。
131 0

热门文章

最新文章