不能直接在构造函数里 new 第三方 SDK 客户端，因为会导致配置硬编码、无法复用单例、测试难 mock、连接泄漏，且 Hyperf 的 @Inject 机制不介入手动 new 的对象；应通过 dependencies.php 注册闭包实例或使用工厂类解决运行时参数问题。
为什么不能直接在构造函数里 new 第三方 SDK 客户端
Hyperf 的 DI 容器要求所有依赖必须可被容器管理，而很多第三方 SDK（比如 TencentCloudSDK、AliyunOpenApiClient）的客户端初始化依赖动态配置（如密钥、region、超时）、甚至内部持有连接池或全局状态。如果在业务类构造函数里 new，会导致：配置硬编码、无法复用单例、测试难 mock、连接泄漏风险——Hyperf 的 @Inject 机制也根本不会介入这种手动 new 的对象。
在 dependencies.php 中注册带参数的 SDK 实例
Hyperf 的 config/autoload/dependencies.php 是声明“容器如何构建某个接口或类”的唯一可信位置。关键不是注册类名，而是注册一个闭包，由容器调用它来获取实例：
return [
'TencentCloud\Cvm\V20170312\CvmClient' => function () {
$profile = TencentCloudCommonProfileClientProfile::newInstance();
$profile->setHttpProfile(TencentCloudCommonProfileHttpProfile::newInstance()
->setEndpoint('cvm.tencentcloudapi.com')
->setReqTimeout(30));
return new TencentCloudCvmV20170312CvmClient(
TencentCloudCommonCredential::newInstance(
config('tencent.secret_id'),
config('tencent.secret_key')
),
config('tencent.region'),
$profile
);
},
];
注意三点：
- 闭包返回值必须是目标类的**完整实例**，不是配置数组
- 所有依赖（如
config()）必须在闭包内调用，不能提前取值并捕获 —— 否则配置热更新失效 - 若 SDK 要求单例（绝大多数 HTTP 客户端都如此），Hyperf 默认会缓存该闭包首次返回值，无需额外处理
当 SDK 客户端需要运行时参数（如租户 ID）怎么办
DI 容器无法为每次注入都传参，所以不能把租户 ID 写进 dependencies.php 的闭包里。正确做法是定义一个**工厂类**，把它注册进容器，再让业务类依赖这个工厂：
// app/Factory/TencentCvmClientFactory.php
<?php
namespace AppFactory;
use TencentCloudCvmV20170312CvmClient;
use TencentCloudCommonCredential;
use TencentCloudCommonProfileClientProfile;
use TencentCloudCommonProfileHttpProfile;
class TencentCvmClientFactory
{
public function make(string $region, string $tenantId): CvmClient
{
$cred = Credential::newInstance(
config("tencent.{$tenantId}.secret_id"),
config("tencent.{$tenantId}.secret_key")
);
$profile = ClientProfile::newInstance()
->setHttpProfile(HttpProfile::newInstance()
->setEndpoint("cvm.{$region}.tencentcloudapi.com"));
return new CvmClient($cred, $region, $profile);
}
}
然后在 dependencies.php 中注册工厂本身：
return [
AppFactoryTencentCvmClientFactory::class => AppFactoryTencentCvmClientFactory::class,
];
业务中使用：
class ServerService
{
public function __construct(
private TencentCvmClientFactory $factory,
) {}
public function listInstances(string $tenantId): array
{
$client = $this->factory->make('ap-guangzhou', $tenantId);
// ...
}
}
常见陷阱：SDK 内部静态方法或全局状态破坏容器生命周期
有些 SDK（如旧版阿里云 PHP SDK）会在第一次调用时通过 setSdkCache 或静态属性缓存 credential，导致后续不同配置的实例共享同一份凭证。这类 SDK 必须确认其客户端类是**真正无状态的**，否则要在 dependencies.php 闭包中显式重置：
- 查 SDK 文档，确认
__construct是否触发全局副作用 - 运行时执行
gc_collect_cycles()无用，重点是避免多次调用静态初始化函数 - 实在无法绕过，就封装一层代理类，在
__destruct中清理静态引用（但 Hyperf 不保证__destruct一定被调用）
最稳妥的方式永远是：用最小可行闭包 + 显式传参 + 避免任何静态初始化入口点。
