适配器模式解决接口不兼容问题，使AlipaySdk、WechatPayV3、StripeClient等第三方支付SDK能被同一套业务逻辑统一调用，通过定义PayInterface并为各SDK编写仅做参数转换、异常映射和返回值标准化的适配器实现。
适配器模式解决什么问题
当你的 PHP 项目要对接多个第三方支付 SDK（比如 AlipaySdk、WechatPayV3、StripeClient），但它们的接口不统一——有的用 pay($order)，有的叫 createPayment($data)，还有的返回数组而另一个抛异常——这时直接写 if-else 调用会迅速失控。适配器模式不是为了“增强功能”，而是让这些不兼容的类“能被同一套业务逻辑调用”。
怎么写一个支付适配器
核心是定义统一接口，再为每个 SDK 写一个实现该接口的包装类。不要修改原 SDK 源码，也不继承它（除非 SDK 明确支持继承且无副作用）。
常见错误：把适配器写成工厂或门面；或者在适配器里加业务逻辑（比如自动重试、日志埋点），这会让适配器偏离单一职责。
- 统一接口必须只声明业务需要的操作，例如：
PayInterface::pay()和PayInterface::query() - 每个适配器构造函数接收对应 SDK 的实例（依赖注入），而不是在内部 new 它
- 适配器里只做参数转换、异常映射、返回值标准化，不处理订单状态机或金额校验
interface PayInterface
{
public function pay(array $order): array;
public function query(string $tradeNo): array;
}
class AlipayAdapter implements PayInterface
{
private $sdk;
public function __construct(\Alipay\AopClient $sdk)
{
$this->sdk = $sdk;
}
public function pay(array $order): array
{
$request = new \Alipay\Request\AlipayTradePagePayRequest();
$request->setBizContent(json_encode([
'out_trade_no' => $order['id'],
'total_amount' => $order['amount'],
'subject' => $order['title'],
]));
$result = $this->sdk->execute($request);
// 把支付宝的 stdClass / array / 异常转成统一 array 结构
return [
'success' => !empty($result->body),
'redirect_url' => $result->body ?? '',
'raw' => $result,
];
}
public function query(string $tradeNo): array
{
// 实现类似逻辑...
return ['status' => 'paid'];
}
}
什么时候不该用适配器
如果两个类差异极小（比如只是方法名大小写不同），或你只对接一个 SDK 且确定长期不会换，硬套适配器反而增加维护成本。适配器的价值出现在“变化点”上——SDK 替换、协议升级、多渠道并存。
立即学习“PHP免费学习笔记（深入）”；
容易踩的坑：
- 在适配器里调用
$sdk->init()或连接池管理——这属于基础设施层，应由 DI 容器或工厂负责 - 适配器返回对象类型不一致（比如有时返回
stdClass，有时返回ArrayObject），导致下游代码反复is_object()判断 - 把 HTTP 客户端（如 Guzzle）也塞进适配器——它应该作为依赖传入，而不是在适配器里 new
和策略模式的区别在哪
适配器解决的是“接口不兼容”，策略解决的是“算法可替换”。你不会用适配器来切换「微信扫码」和「微信公众号」支付方式——它们本就是同一 SDK 下的不同调用路径，该用策略；但当你把微信支付 SDK 和 Stripe SDK 并列支持时，就必须先用适配器抹平接口差异，再用策略选具体实现。
真实项目里，二者常嵌套使用：策略上下文持有一个 PayInterface，运行时根据渠道配置决定 new 哪个适配器实例。
最易被忽略的一点：适配器的测试不能只测 happy path。必须覆盖原 SDK 抛出的各类异常（网络超时、签名失败、无效参数），并在适配器中映射为统一的 PayException 或错误码字段——否则业务层无法稳定降级。
