重构PHP业务代码时,如何通过接口拆分组件并替换外部依赖?
替换PHP外部依赖时,先让业务依赖一份由自己定义的接口,再由适配器把接口调用转换成供应商要求的格式。这样更换SDK时,修改集中在适配器和组装入口,业务服务不必跟着修改供应商字段、异常类和客户端对象。
下面以短信通知为例,使用PHP 8.1及以上语法说明接口、适配器和构造注入。示例中的供应商响应字段是为了演示转换关系,不对应某家真实SDK。
把业务需要的能力写成小接口
业务只需要知道通知是否被接受以及消息ID,不应直接拿到第三方完整响应。接口也不必包含供应商提供的所有查询、撤回和批量管理功能。
<?php
declare(strict_types=1);
final class SendResult
{
public function __construct(public readonly string $messageId) {}
}
interface SmsSender
{
public function send(string $phone, string $content): SendResult;
}
final class SmsDeliveryFailed extends RuntimeException {}
final class AccountAlertService
{
public function __construct(private SmsSender $sender) {}
public function notify(string $phone, string $orderId): SendResult
{
if (trim($phone) === '' || trim($orderId) === '') {
throw new InvalidArgumentException('号码和订单编号不能为空');
}
return $this->sender->send($phone, "订单{$orderId}已完成");
}
}
这份契约约定:返回包含非空消息ID的 SendResult 表示供应商接受了请求;发送失败抛出 SmsDeliveryFailed。它不等于收件人已经收到短信,投递状态查询是另一种能力。先把成功和失败的含义说清楚,比单纯把SDK类名换成接口名更有用。
在适配器内转换字段和错误
下列适配器接收一个调用外部SDK的函数。函数返回示例数组,适配器负责将其转换成应用自己的返回值和异常。Closure 是PHP原生类型;VendorSmsClient 是本文可运行的离线占位客户端,用来表现图中的外部SDK位置,VendorSmsSender 是应用自己的适配器。接入真实SDK时换掉占位客户端及其方法映射,不要把这些示例类名当成现成库。
// 本文的离线客户端占位,接入时换为真实SDK及对应调用。
final class VendorSmsClient
{
public function __construct(private Closure $request) {}
public function sendMessage(string $phone, string $content): mixed
{
return ($this->request)($phone, $content);
}
}
final class VendorSmsSender implements SmsSender
{
public function __construct(private VendorSmsClient $client) {}
public function send(string $phone, string $content): SendResult
{
try {
$response = $this->client->sendMessage($phone, $content);
} catch (Throwable $error) {
throw new SmsDeliveryFailed('短信请求失败', 0, $error);
}
if (!is_array($response)
|| ($response['code'] ?? null) !== 'OK'
|| !is_string($response['message_id'] ?? null)
|| $response['message_id'] === '') {
throw new SmsDeliveryFailed('短信请求未被接受');
}
return new SendResult($response['message_id']);
}
}
实际项目只在这个调用函数中接入已安装SDK的真实方法,并按真实响应修改映射;不要照抄示例中的 code 和 message_id 去假设任意服务商都使用这些字段。供应商异常保留为前一个异常,便于内部排查,业务层则只依赖应用定义的失败类型。
组装处选择实现,业务代码保持不变
把前面的声明放在同一文件中,就可以追加以下离线示例,观察注入关系。这里明确使用模拟响应,不发送真实短信。
$adapter = new VendorSmsSender(new VendorSmsClient(
fn(string $phone, string $content): array => [
'code' => 'OK', 'message_id' => 'demo-001',
]
));
$service = new AccountAlertService($adapter);
echo $service->notify('13800000000', 'ORDER-001')->messageId;
业务服务调用接口,适配器实现接口;应用的组装入口把两者连接起来。如果项目已有依赖注入容器,就在容器配置中绑定 SmsSender 与具体实现;没有容器时,构造方法传入对象即可,不需要为了这次重构安装一个容器。

更换供应商时,新建另一个实现 SmsSender 的适配器,并在同一组装入口替换对象。新适配器可以使用不同SDK和响应格式,但返回值及失败含义必须继续符合上面的契约。不要把业务代码里的依赖又改成新供应商具体类,否则下一次替换仍要改业务。
验证替换是否保留了原行为
业务层测试注入一个记录号码和正文的替身,检查订单通知内容与调用次数;适配器测试则分别让调用函数返回成功、拒绝、缺少消息ID以及抛出异常,核对消息ID或 SmsDeliveryFailed。两类测试关注不同边界,单测通过也不代表真实服务商网络已经接通。
真实接入还应核对超时、重复请求和重试归属。特别是超时后服务商可能已经接受请求,不应在适配器和业务层各自无条件重试。只有新SDK确实改变PHP版本或依赖要求时,才需要额外处理兼容问题;接口拆分本身不要求先升级整个项目环境。
A5idc数据提供用于PHP业务应用、接口服务及数据服务部署的物理服务器资源,涵盖至强、AMD EPYC与SSD/NVMe存储组合。中国香港、美国、日本等地区及不同网络方案,可为采用组件拆分的业务系统组织独立应用节点与数据资源,适配不同地区的应用运行需求。
本文由A5数据原创发布,转载请注明出处:https://www.a5idc.com/helpcontent/9863.html

