Hyperf 不是单体框架升级包，而是服务边界重定义起点；需按限界上下文拆分项目、隔离配置、禁用全局共享、强制协程化组件与上下文数据传递。
直接把 Laravel 或 ThinkPHP 的单体项目“套壳”进 Hyperf，99% 会卡在 MySQL server has gone away、@Inject 失效、go() 后段错误，或者请求压根不响应——这不是配置没调好，而是架构模型冲突导致的必然失败。
Hyperf 不是“升级包”，而是服务边界重定义起点
你手里的单体代码里，OrderService::create() 可能同时读用户、写订单、扣库存、发消息，还共享一个 DB::connection() 实例。Hyperf 要求每个上下文（比如“订单创建”）独立部署、独立数据库连接池、独立事务边界。强行保留这种调用链，等于用协程引擎拉一辆没拆轴的马车。
- 先识别限界上下文：电商系统中，“下单”和“支付回调”不是同一上下文——前者强一致性要求，后者需幂等+异步重试
- 每个上下文建独立 Hyperf 项目，
composer.json和config/autoload/彼此隔离 - 跨上下文通信必须走
Hyperf\RpcClient或Hyperf\HttpClient\Client，禁止use App\Service\PaymentService - 旧单体里的全局缓存（如
static $cache）必须替换为Co::getcid()+Channel或ApplicationContext::getContainer()->get(...)
协程安全不是加 go() 就完事
你在控制器里写了 go(function () { DB::table('users')->get(); });，但底层还是原生 PDO？那只会触发段错误或返回错乱数据。Hyperf 的协程能力依赖 Swoole 运行时 + 协程化组件链路对齐，缺一不可。
- 启动入口
bin/hyperf.php最顶部必须调用Swoole\Runtime::enableCoroutine(true) -
config/autoload/server.php中enable_coroutine显式设为true - 数据库必须用
hyperf/database（非PDO），Redis 必须用hyperf/redis（非phpredis） - 第三方 SDK（如微信支付 SDK）若无协程支持，必须包裹成
Hyperf\Coroutine\Waiter::run()同步调用，否则阻塞整个 Worker
PHP 8.2 + Swoole 5.x 环境验证三步法
很多团队卡在“服务能启，但 DB 查询超时”，根本原因是 PHP 扩展没装全或 swoole.use_shortname 没关——这些错误不会报错，只会让协程静默失效。
立即学习“PHP免费学习笔记（深入）”；
- 运行
php --ri swoole，确认输出含support coroutines: enabled，且版本 ≥ 5.0 - 检查
php.ini是否有swoole.use_shortname = Off；漏掉这行，go()会变成空操作 - 执行
php bin/hyperf.php start后，立刻发请求测试DB::table('users')->count()，若耗时 >500ms 或报SQLSTATE[HY000] [2002]，说明连接池未生效或协程未启用
最易被忽略的点：协程上下文无法穿透 static 变量、$_SERVER、global，哪怕只在中间件里存了个 trace_id，下游协程也拿不到。所有上下文数据必须走 Context::set() / Context::get() 或 ApplicationContext 容器注入——这不是可选项，是协程模型的硬性约束。
