Hyperf 依赖管理需严格遵循协程安全原则：必须用 create-project 创建骨架，禁用 --no-dev/--no-scripts，使用协程组件（如 hyperf/http-client），并正确配置 autoload；否则将导致类未加载、协程阻塞或进程崩溃。
Hyperf 是基于 Swoole 的协程 PHP 框架，composer 在其中的用法和传统 Laravel 或普通 PHP 项目基本一致，但有几处关键差异必须注意：Hyperf 对 PHP 版本、扩展依赖更严格，且部分组件（如数据库驱动、Redis 客户端）需选用协程兼容版本。
安装 Hyperf 项目时必须用 composer create-project
不能直接 composer require hyperf/hyperf 到已有项目——Hyperf 不是“可插拔”的包，而是一套完整骨架，依赖目录结构、配置加载顺序和启动生命周期。
正确做法：
composer create-project hyperf/hyperf-skeleton my-app cd my-app php bin/hyperf.php start
该命令会自动拉取 hyperf/hyperf-skeleton 并执行 composer install，同时确保 vendor/hyperf/* 下所有组件版本对齐。手动 require 单个 hyperf/xxx 包极易引发版本冲突或类未加载问题。
composer require 添加协程安全的第三方包
Hyperf 运行在协程环境，所有 I/O 操作（HTTP 请求、Redis、MySQL、文件读写）必须使用协程友好的客户端。直接 require guzzlehttp/guzzle 或 predis/predis 会导致协程阻塞、性能归零甚至进程崩溃。
应优先选用 Hyperf 官方维护或社区验证的协程适配包：
-
hyperf/http-client替代 Guzzle（已内置，无需额外 require） -
hyperf/redis替代 Predis（自动使用swoole_redis协程客户端） -
hyperf/database+hyperf/db-connection替代原生 PDO（支持协程 MySQL 连接池） - 若需 HTTP 调用外部服务，直接用
HyperfHttpClientHttpClientFactory，不要 new GuzzleClient
错误示例（导致协程阻塞）：
composer require guzzlehttp/guzzle // 然后在代码里： $client = new GuzzleHttpClient(); // ❌ 阻塞式，破坏协程
正确方式（使用 Hyperf 自带协程 HTTP 客户端）：
使用 JSON Schema 验证 JSON 数据，从示例 JSON 生成 schema，并将其转换为 TypeScript 接口、Python 数据类或 Markdown 文档。
$client = $this->container->get(HyperfHttpClientHttpClientFactory::class)->create(); // ✅
更新依赖时禁用 --no-dev 和跳过脚本
Hyperf 启动前会执行 HyperfDevtoolComposerScriptHandler::build 脚本，用于生成代理类、扫描注解、构建容器等。若运行 composer update --no-dev 或加 --no-scripts，会导致 runtime/container 目录缺失、注解失效、DI 容器无法解析依赖。
日常开发中应始终保留 dev 依赖并允许执行脚本：
- 运行
composer update时，不加任何跳过参数 - 生产部署若需精简，应使用
composer install --no-dev --optimize-autoloader，而非update - 确认
composer.json中"scripts"区块存在"post-autoload-dump"和"post-update-cmd"调用HyperfDevtoolComposerScriptHandler
常见报错现象：Class xxx does not exist 或 Call to undefined method HyperfContractContainerInterface::get()，大概率是脚本未执行导致代理类或容器配置未生成。
自定义组件或私有包需注意 autoload 配置
Hyperf 使用 PSR-4 自动加载，但要求命名空间与目录结构严格匹配，且必须显式声明在 composer.json 的 "autoload" 中。仅把类文件扔进 app/ 下不会被自动识别。
例如，添加一个 AppServicePaymentAlipayService，需确保：
- 类文件路径为
app/Service/Payment/AlipayService.php -
composer.json中包含："autoload": { "psr-4": { "App\": "app/" } } - 执行
composer dump-autoload（Hyperf 启动时也会触发，但手动执行可快速验证）
漏掉 dump-autoload 或命名空间写错（如写成 AppServicePayAlipayService 但目录是 Payment），都会导致 Class not found。
Hyperf 的依赖管理本身不特殊，特殊的是它对协程安全性和启动脚本的强依赖。最常出问题的地方不是 composer 命令本身，而是绕过骨架约定、混用非协程组件、或跳过 post-install 脚本——这些操作在传统框架里可能只是“慢一点”，在 Hyperf 里直接表现为功能失效或进程挂死。
