适配器模式核心思想与实战：从支付对接看接口翻译与隔离变化

写适配器模式的文章很多，但大多数都在讲类图和代码示例，真正把"适配器模式的核心思想"讲透的并不多。我最早接触这个模式的时候也走过弯路，以为它就是给旧接口包一层新壳，直到后来做了一次老系统重构、对接了三个不同的第三方服务，才真正理解这个模式在解决什么问题，以及什么时候该用、什么时候不该用。

这个内容适合正在学设计模式的初学者，也适合工作几年、写了不少代码但总觉得"设计模式用不上"的后端工程师。我会用一个完整的支付对接案例，把适配器模式从思想到落地讲清楚，同时把和门面模式、代理模式的边界也掰开揉碎说一遍。

1. 适配器模式到底在解决什么问题

1.1 接口不匹配的典型场景

先看一个最常见的场景。你负责维护一个订单系统，系统内部有一套自己的支付接口，叫PayService，里面有一个pay(orderId, amount)方法。这个接口被订单模块、售后模块、营销模块同时调用，整个业务逻辑都依赖它。

后来公司要接入一家新的支付渠道，这个渠道提供的 SDK 接口和你们系统完全对不上。人家不叫pay，叫createPayment，参数也不是(orderId, amount)，而是(paymentRequest)，里面塞了一大堆字段，验签逻辑、回调通知也完全不同。你总不能为了接它，把所有调用PayService的地方都改一遍吧？几十个调用点，改完必然出问题。

这时候适配器模式就派上用场了。它的核心思想说白了就十二个字：不改调用方，不改被适配者，中间加一层转换。用代码来说，就是你依然让业务方调用PayService，但内部通过一个适配器，把PayService的调用转换成新渠道 SDK 的调用。

1.2 核心思想不是"封装"，而是"翻译"

很多人会把适配器模式理解成"封装一层"，这个理解不算错，但不准确。封装强调的是隐藏复杂性，而适配器强调的是接口语义的对齐。

打个比方，你去国外旅游，带了国内的两孔插头，酒店插座是三孔的。你的手机不会自己去改插头，酒店插座也不会为了你重新装修，你需要的是一个转换插头。转换插头做的事情，就是把你手机的接口形态，翻译成酒店插座的接口形态，两头都不用动。

在代码里也是这样。调用方说"我要支付 100 块，订单号是 123"，适配器需要翻译成第三方渠道听得懂的"创建一笔金额为 100 元、商户订单号为 123 的支付请求，并且按渠道要求做签名"。注意，这中间不只是字段改名，还可能涉及数据格式转换、加密签名、单位换算、时区处理，这些都属于"翻译"工作。

所以适配器模式的核心思想，往深了说，是让不兼容的双方通过一个中间层协同工作，且双方都不需要感知对方的存在。调用方只依赖自己的接口，第三方只暴露自己的接口，适配器负责把两边的语言翻译通。

1.3 适配器模式的价值在于"隔离变化"

我在实际项目里感受最深的一点是，适配器模式最大的价值不是什么代码复用，而是隔离变化。

第三方接口会变吗？太会了。你接了一个支付渠道，第二年它升级了 API，验签方式变了，字段结构调整了，回调通知的加密算法也换了。如果没有适配器这一层，这些变化会直接穿透到你的业务代码里。有了适配器，业务代码完全无感，你要做的只是修改适配器内部逻辑，然后回归测试适配器这一块就可以了。

同样，如果你的系统要从一个短信服务商切换到另一个，从一套旧的自建缓存切到云服务商，适配器模式都能帮上大忙。它把"不稳定的外部依赖"和"稳定的业务逻辑"隔离开来，这个思想本身比任何代码技巧都重要。

2. 对象适配器与类适配器：两条实现路线

2.1 对象适配器：组合优先，实战首选

适配器模式有两种经典实现方式，第一种是对象适配器。它的做法是，适配器类持有被适配者（第三方接口）的一个实例，然后实现目标接口（你的业务接口），把业务接口的调用转发给被适配者。

用代码来表示会更直观。假设你的业务接口长这样：

class PayService: def pay(self, order_id: str, amount: float): raise NotImplementedError

第三方渠道的接口长这样：

class ThirdPartyPayClient: def create_payment(self, request: dict) -> dict: # 真实调用第三方 HTTP 接口 # 需要 request 里包含 out_trade_no、total_amount、sign 等字段 pass

对象适配器就是这样：

class ThirdPartyPayAdapter(PayService): def __init__(self, client: ThirdPartyPayClient, config: dict): self.client = client self.config = config # 包含 app_id、secret_key、notify_url 等配置 def pay(self, order_id: str, amount: float): # 单位转换：内部按元存储，渠道要求分 amount_in_fen = int(round(amount * 100)) # 构造请求参数 request = { "out_trade_no": order_id, "total_amount": amount_in_fen, "subject": "商品订单", "notify_url": self.config["notify_url"], } # 签名 request["sign"] = self._sign(request) # 转发给第三方 resp = self.client.create_payment(request) return self._parse_response(resp) def _sign(self, data: dict) -> str: # 按第三方要求的规则对参数排序、拼装、加盐做摘要 return "signed_string"

你看，业务层拿到的还是PayService，调用方式没有变，但内部已经完全转向了第三方渠道的 SDK。这个适配器负责了单位转换、参数组装、签名、响应解析，这些都是"翻译"工作。

对象适配器之所以是首选，是因为它基于组合，耦合度低，只依赖被适配者公开的接口，不碰人家的内部结构。而且被适配者的子类变化也不影响适配器。日常开发里，95% 以上的适配器场景用对象适配器就够了。

2.2 类适配器：多继承下的特例

类适配器是另一种实现，它通过继承同时获得"目标接口"和"被适配者"的能力。在 Java 这种单继承语言里，实际是让适配器继承被适配者，同时实现目标接口。在 Python 里可以更直接，多继承就行了：

class ThirdPartyPayAdapter(PayService, ThirdPartyPayClient): def __init__(self, config: dict): self.config = config def pay(self, order_id: str, amount: float): # 因为继承了 ThirdPartyPayClient，可以直接调用其方法 request = self._build_request(order_id, amount) return self.create_payment(request)

看起来代码更少，但这个方案的问题在于，你同时继承了目标和被适配者，如果两边有同名方法、同名属性，就会非常头疼。而且类适配器是静态绑定的，被适配者一旦变化，适配器必须跟着变，不够灵活。

所以类适配器在实际项目中非常少见，通常只用在被适配者无法通过组合方式获取的极特殊场景，比如被适配者是某个重框架里难以剥离的类。我个人的经验是：能组合就不要继承。面试的时候能讲清楚类适配器的原理就够了，项目里能不用就不用。

2.3 怎么选：一张表说清楚

我整理了一个选型对照，方便你根据自己的场景快速做判断：

这里多说一句，有些同学会在适配器里又继承目标接口又继承被适配者，然后方法和字段一多，代码就成了一锅粥。遇到这种问题，回头检查一下是不是用了类适配器。换成组合方式，用self.client去调第三方，问题立刻清爽很多。

3. 一次真实的适配器落地：第三方支付对接

3.1 业务背景与原始接口

理论讲再多，不如看一个完整的实战案例。我去年做过一个电商项目的支付模块重构，当时的情况是这样的：

项目里原来的支付接口是：

class PaymentService: def create_order_payment(self, order_no: str, pay_amount: float, user_id: str): # 各种本地业务逻辑校验 # 调起支付 pass

公司原来一直用渠道 A 的支付，后来渠道 A 的费率涨了，老板决定接入渠道 B，两边并行一段时间再平滑切换。渠道 B 的 SDK 接口风格和渠道 A 完全不同。渠道 B 提供的类叫BChannelApi，方法签名是：

public class BChannelApi { public BPayResult submit(BPayRequest req) throws BChannelException; }

BPayRequest里需要填入商户号、业务订单号、金额（单位是分）、商品描述、客户端 IP、回调地址等十来个字段，其中金额必须转成分为单位的整型，而且提交前必须用 RSA 签名。渠道 B 返回的结果是一个BPayResult，里面有一个status字段，只有"SUCCESS"才代表下单成功，其他状态都要映射成我们内部的错误码。

贸易上，这就是典型的"接口不兼容"。我们的订单号字段叫order_no，渠道 B 叫merchant_order_id；我们的金额是float元，渠道 B 要long分；我们的错误处理是抛业务异常，渠道 B 是返回状态码。如果不做适配，支付模块的调用方就得为了渠道 B 写一堆判断分支，以后接渠道 C、渠道 D，就得再改一遍。

3.2 适配器代码实现

我的做法是，先定义一个内部统一的目标接口，不直接叫 PaymentService 也行，但语义要清晰：

class UnifiedPayPort: def pay(self, order_no: str, amount_yuan: float, client_ip: str = "") -> PayResult: """ amount_yuan 单位是元 返回统一结构的 PayResult """ raise NotImplementedError

然后为渠道 B 单独写一个适配器，实现这个统一接口。适配器内部做几件事：

import hashlib import json import time from urllib.parse import urlencode class BChannelPayAdapter(UnifiedPayPort): def __init__(self, api: BChannelApi, mch_id: str, secret: str, notify_url: str): self.api = api self.mch_id = mch_id self.secret = secret self.notify_url = notify_url def pay(self, order_no: str, amount_yuan: float, client_ip: str = "") -> PayResult: amount_fen = int(round(amount_yuan * 100)) if amount_fen <= 0: raise ValueError(f"invalid amount: {amount_yuan}") req = BPayRequest() req.merchant_id = self.mch_id req.merchant_order_id = order_no req.total_fee = amount_fen req.client_ip = client_ip or "127.0.0.1" req.notify_url = self.notify_url req.trade_time = int(time.time()) sign_content = urlencode({ "merchant_id": req.merchant_id, "merchant_order_id": req.merchant_order_id, "total_fee": str(req.total_fee), "trade_time": str(req.trade_time), }) sha1 = hashlib.sha1((sign_content + self.secret).encode("utf-8")).hexdigest() req.sign = sha1 try: result = self.api.submit(req) except BChannelException as e: # 第三方最怕网络超时，需要抛出可重试的错误 raise PayTransientError(str(e)) from e if result.status == "SUCCESS": return PayResult(success=True, channel_trade_no=result.channel_trade_no) elif result.status == "FAIL": # 比如余额不足、参数错误，都是不可重试的 raise PayBizError(result.error_msg) else: raise PayUnknownError(f"unexpected status: {result.status}")

这个适配器里做了几件很关键的事：

第一，单位统一。内部用元，渠道要分，适配器负责转。以后不管换哪个渠道，调用方永远不用关心单位问题。

第二，参数映射。merchant_order_id和order_no的对应关系只在这里出现一次。

第三，异常隔离。渠道 B 抛的BChannelException，被我统一转成了可重试的PayTransientError；业务上明确失败的状态码转成PayBizError；无法识别的状态转成PayUnknownError。上层逻辑只处理这三种错误，不需要了解渠道 B 的任何细节。

第四，默认兜底。client_ip为空时填127.0.0.1，避免某些渠道在参数校验阶段报错。

3.3 关键参数与边界情况

做支付对接的时候，有几个参数细节特别容易踩坑，这里单独拿出来说：

一是金额精度问题。业务层用float表示元，但真要算钱，浮点是有误差的。直接int(round(amount * 100))只能解决转换，解决不了浮点本身的问题。正确的做法是，业务层尽量用Decimal保存金额，如果历史原因用了float，至少也要在转换时用round而不是直接截断。我在代码里用int(round(amount_yuan * 100))，就是因为直接int(amount * 100)可能因为浮点误差变成1999，而不是2000。

二是签名规则。每个渠道的签名规则都不一样，有的要拼接 key，有的要排序，有的要对 URL 编码做特殊处理。适配器里一定要把签名逻辑单独抽成方法，不要散落在pay方法里。因为你接第二个渠道时，这个适配器可以整体替换，但签名逻辑很可能也想留着做对照测试。

三是回调通知。很多人只写了下单适配器，忘了写回调适配器。渠道 B 的回调报文肯定也和我们内部系统的通知结构不一样。我建议对回调也建立一个统一的处理入口，第三方请求先进入一个"回调适配器"，把它翻译成内部统一的通知对象，再分发到业务层。这样，回调验签、数据解析、幂等处理都能收敛在一个地方，不会泄漏到各处。

四是超时与重试。第三方接口经常超时，但超时不一定代表下单失败。所以适配器处理网络异常时，需要区分"可重试"和"不可重试"。PayTransientError这种语义，就是告诉上层这个错误可以重新发起流程。如果你不区分，把业务失败和网络失败混为一谈，要么会重复下单，要么会漏单，这两种后果都很严重。

3.4 原接线上的一个常见错误

有些同学会给每个渠道都写一个适配器，然后把适配器实例交给容器管理，这没问题。但有一个错误很常见：适配器里塞满了if channel == "A"这样的分支。比如：

def pay(self, order_no, amount, client_ip): if self.channel == "A": ... elif self.channel == "B": ...

这就是典型的适配器被写成了"大杂烩"。适配器的意义是每个渠道一个类，而不是一个类里塞所有渠道的分支。遇到这种情况，正确的做法是给不同渠道单独建适配器类，再通过工厂或容器根据渠道类型返回对应的适配器实例。适配器内部永远不应该出现"我是哪个渠道"的判断。

4. 适配器模式和几个"亲戚"模式的边界

4.1 适配器 vs 门面模式

这是最容易混淆的一对。有些文章会把适配器说成"为了简化接口"，但严格来说，简化接口是门面模式的事，不是适配器的主要职责。

适配器模式的目标是把接口 A 转成接口 B，让原本不兼容的双方能一起工作。门面模式的目标是把一个复杂的子系统统一成一个简单的入口，它不管接口是否兼容，它关心的是"降低使用难度"。

举例子来说，你封装了一个OrderFacade，里面把库存扣减、优惠计算、订单生成、支付发起串在一起，业务方只需要调用place_order(request)。这个类就是门面，它并没有去适配某个第三方，它只是把一个复杂流程收口了。

适配器则不同，它出现在"两端接口已经存在，且语义不匹配"的场景。门面是主动设计，适配器是被动接合。如果一个类既是门面又是适配器，通常说明你的设计职责混在一起了。我在代码评审里会格外关注这类类，一旦发现又做流程编排又做第三方转换，就建议拆开。

4.2 适配器 vs 代理模式

代理模式和适配器有一点像，它们都在中间加了一层，但意图完全不同。代理模式的目的是控制对被代理对象的访问，比如做权限校验、加缓存、做延迟加载、记录日志。代理类和被代理类实现的是同一个接口，代理对调用方是透明的。

适配器则完全不同。适配器两端的接口是不一样，代理两端的接口是一致的。你写一个LoggingProxy实现PayService，内部持有真正的PayServiceImpl，调用前打日志，这是代理。你写一个BChannelPayAdapter实现PayService，内部持有BChannelApi，调用时做参数转换，这是适配器。

这里有个实用判断标准：去掉这层包装之后，行为是否等价。代理去掉之后，底层对象的行为和原来一致，只是少了横切逻辑；适配器去掉之后，调用方直接面对第三方接口根本没法用，因为接口对不上。

4.3 一句话区分方法

我后来总结了一句话，评审代码时特别好用：适配器是"接口翻译"，门面是"接口整合"，代理是"接口增强"。

• 接口翻译：两端接口不匹配，我要让它们配合工作。
• 接口整合：子系统太复杂，我提供一个简单的入口。
• 接口增强：接口匹配，但我想在调用前后加一点东西。

每次纠结一个类到底算哪种模式时，先问自己：它存在的理由是什么？是因为两边接口对不上？还是因为子系统太复杂？还是因为要在调用前后做点事？答案自然就出来了。

5. 常见问题与实操避坑

5.1 什么时候不应该用适配器

有个很经典的反模式，叫"过度适配"。我见过一些项目，内部两个服务之间明明可以统一接口，结果前面的同事图方便，写了一个适配器把 A 的接口转成 B 的接口。短期看是省事了，问题在于，每多一个这样的适配器，系统里就多一层概念。当类似的适配器达到十几个时，没有人说得清数据的真实流向到底是什么。

适配器模式不是银弹，它解决的是一种无法通过修改现有代码实现兼容的场景。如果你的内部接口设计可以重来，正确做法是直接统一接口，而不是绕一层适配。换句话说，能用重构解决的，就不要用适配器打补丁。

5.2 为什么使用了适配器后代码仍然很乱

有时候你加了适配器，代码依然乱，甚至更乱。我排查过不少这种情况，原因往往不在适配器本身，而在三个地方：

第一，适配器职责过重。它既做参数转换，又做签名，又做数据解析，还做本地缓存，甚至把业务校验也丢了进来。正确的做法是，适配器只负责"接口翻译"，其他横切逻辑交给独立组件，不要让适配器承担所有事情。

第二，缺少统一的目标接口定义。有些项目里每个渠道的适配器都实现了不同的方法签名，结果调用方在切换渠道时依然要写分支。适配器模式要生效，前提是所有适配器都实现同一个目标接口。如果目标接口不统一，适配器就退化成了一堆互不兼容的工具类。

第三，回调没有适配。很多项目只在下单时用了适配器，回调处理是直接用第三方 SDK 的数据结构透传的。等到渠道切换时，才发现回调逻辑和旧渠道深度耦合，改动面巨大。回调同样需要适配，而且最好和下单共用一套内部模型。

5.3 我的一套实操经验清单

写到这里，我把自己做适配器重构时习惯遵循的几条经验整理一下，你可以直接参考：

• 目标接口要从业务语义出发设计，不要从第三方现有接口反推。你先想清楚业务需要什么，再去考虑每个渠道怎么映射到这个目标。
• 适配器里不要写任何与具体渠道无关的业务规则，所有业务判断留在上层。
• 每个外部依赖都收敛到一个适配器，一处调用，处处生效。宁可多花半天设计目标接口，也不要在后续每个渠道接入时反复改调用方。
• 适配器的命名要体现"适配"语义，比如BChannelPayAdapter，看到名字就知道它是为了某个渠道而存在的。
• 单元测试时一定要 mock 第三方 SDK，重点测异常映射、参数组装和边界值，不要真的去调第三方接口。
• 切换渠道时，保留一段时间双跑状态，即新旧适配器同时运行，对比结果，确认一致后再摘除旧逻辑。

这几条是我踩了不少坑之后总结出来的。一开始我也觉得适配器模式就是简单加一层，后来才发现，这一层加在哪里、怎么加、目标接口怎么设计，才是真正决定成败的地方。

我个人对适配器模式的理解是：它看起来是代码结构问题，本质上是对"变化"的预判。外部接口不是你能控制的，但你可以在自己系统里划出一条稳定的边界，把外部变化全部挡在边界之外。不管以后接多少渠道，业务代码都不需要跟着动荡，这种稳定感，才是适配器模式给项目带来的最大价值。