Hyperf中不能直接注入第三方类的非静态方法，必须封装成服务并显式注册到容器；需通过Provider手动new带参实例、封装业务语义方法、注入封装类而非原始SDK，且注册后须执行di:cache-warmup刷新缓存。
Hyperf里不能直接注入第三方类的非静态方法，必须封装成服务
Hyperf 的 DI 容器只管理对象实例，不支持注入「方法」本身。你想用 someExternalLib->doSomething()，就得先让 someExternalLib 成为容器可管理的服务——不能靠 new 实例，也不能靠静态调用，得走依赖注入流程。
常见错误是直接在 Controller 里 new SomeExternalClass()，结果导致无法 mock、无法统一配置、无法享受 AOP（比如日志、重试）；或者误以为加个 @Inject 就能绑定到某个方法上，实际会报 ClassNotFoundException 或 Cannot instantiate interface。
正确做法是：写一个封装类（如 AliyunOssClientService），在其中持有外部库实例，并把目标方法转为实例方法；再通过 Provider 显式注册该封装类及其依赖。
Provider 中注册外部库实例时，必须手动 new 并传参（不能靠自动解析）
Hyperf 默认不会自动构造带参数的第三方类（比如需要 Endpoint 和 Credentials 的 OssClient）。Provider 是唯一可控入口，必须显式 new 并注入配置。
示例 Provider 片段：
public function configure(): void
{
$this->app->singleton(AliyunOssClientService::class, function ($app) {
$config = $app->get(\Hyperf\Config\Config::class);
$client = new \OSS\OssClient(
$config->get('oss.access_key_id'),
$config->get('oss.access_key_secret'),
$config->get('oss.endpoint')
);
return new AliyunOssClientService($client);
});
}
注意点：
-
$app->singleton()必须指定完整类名，不能只写别名 - 外部类（如
\OSS\OssClient）不在容器中，不能用$app->get(OssClient::class)反向取，只能 new - 如果外部库构造耗时（如连接 Redis、初始化 SDK），建议加 lazy proxy 或延迟初始化逻辑，避免启动卡顿
封装类里不要暴露原始 SDK 对象，只暴露业务语义方法
直接返回 $this->ossClient->putObject(...) 不够干净，也违背封装意图。应该把 SDK 调用包装成更贴近业务的动作，比如 uploadAvatar(string $userId, string $fileContent)，并在其中处理异常映射、路径拼接、重试策略等。
这样做的好处：
- Controller 或 Service 层完全不知道底层是 OSS 还是本地文件系统
- 单元测试时只需 mock 封装类，不用 mock 第三方 SDK（很多 SDK 不易 mock）
- 后续切换云厂商时，只改封装类内部，上层无感
反例：public function getClient(): \OSS\OssClient { return $this->client; } —— 这等于把封装白写了。
使用时用 @Inject 注入封装类，不是注入原始 SDK 类
Controller 或其他 Service 中，注入点必须和 Provider 中注册的类一致：
class UserController
{
#[Inject]
protected AliyunOssClientService $ossService;
public function upload()
{
$this->ossService->uploadAvatar('u1001', $content);
}
}
关键检查项：
- 确认
AliyunOssClientService类有__construct()且参数类型明确（Hyperf 靠这个做自动注入） - 若封装类构造函数依赖了其他服务（比如
LoggerInterface），Provider 中注册时需手动传递，或确保该依赖已在容器中注册 - 别在封装类里用
$this->container->get(...)手动取服务，破坏注入链路，也难测
最常被忽略的是 Provider 没 reload —— 改完 Provider 后要清 config cache：php bin/hyperf.php di:cache-warmup，否则新注册的服务不可见。
