很多从 PHP-FPM 转过来的开发者第一次跑 Hyperf 项目时，会习惯性地把请求参数存进静态属性、把数据库连接对象保存到全局变量，或者继续使用 $_GET、$_POST 读取客户端输入。这些写法在传统模式下不会造成明显问题，因为每次请求结束所有内存状态都会被清空。但 Hyperf 基于 Swoole 常驻内存运行，同一个进程会连续处理大量请求，协程之间还会并发切换，旧的编码习惯会迅速转化为数据串扰、连接池耗尽、配置不生效等难以复现的问题。理解这些坑背后的运行机制，比单纯记住几个命令更重要。
协程上下文与单例对象：数据串扰的根源
传统 PHP-FPM 模式下，每次请求都会重新创建对象和变量，请求结束后自动销毁。因此很多开发者习惯用静态属性保存当前用户 ID、当前请求参数等临时数据。这种写法在 Hyperf 中非常危险，因为常驻内存进程会保留静态属性的值，下一个请求可能读到的还是上一个请求遗留的数据。更麻烦的是，Swoole 协程会在同一个进程内并发执行，多个请求可能同时修改同一个静态属性，造成数据交叉覆盖。
下面这个错误示例就演示了典型的数据串扰问题。第一个请求设置了用户 ID，还没来得及读取，第二个协程又覆盖了这个值，最终两个请求都可能拿到错误的数据。
// 错误示例：用静态属性保存当前请求数据
class UserContext
{
public static $userId;
}
UserContext::$userId = 123;
// 协程切换后，其他请求可能已经把该值改成 456
正确做法是使用 Hyperf 提供的协程上下文组件 Hyperf\Context\Context。它基于 Swoole 的协程隔离机制，每个协程有独立的数据存储空间，协程结束时自动清理，不会影响其他协程。写入和读取都要通过 Context::set 和 Context::get，不要直接操作静态变量。
// 正确示例：使用协程上下文保存请求级数据
use Hyperf\Context\Context;
Context::set('user_id', 123);
$userId = Context::get('user_id', 0);
还需要注意，Context 适合保存请求或协程生命周期内的轻量数据，但不要把数据库连接、完整模型对象等大对象长期塞进去。连接资源应当交给连接池管理，模型对象在协程结束后也应该被释放。理解协程隔离只解决数据归属问题，并不代表可以随意在内存中堆积对象。
数据库连接池与模型操作：别让连接只借不还
Hyperf 数据库组件默认使用连接池复用连接。一个 worker 进程启动时会创建若干条 MySQL 连接，业务代码需要连接时从池中取出，用完后归还，给后续协程继续使用。如果开发者按照传统思维手动获取连接，并且忘记归还，或者把连接对象保存到静态属性中长期占用，很快就会出现连接池耗尽的问题，表现为大量请求阻塞或报错提示无法获取连接。
下面这个写法就是典型错误。代码里手动调用了 Db::connection() 获取连接，执行查询后既没有归还连接，也没有在协程结束时释放引用。刚开始可能还能正常响应，一旦并发量上来，池里的连接被占满，整个服务就会卡住。
// 错误示例：手动获取连接后没有归还
use Hyperf\DbConnection\Db;
$connection = Db::connection();
$result = $connection->select('SELECT * FROM users');
// 业务处理完毕后未调用连接归还逻辑
正确做法是让框架替你管理连接生命周期。使用模型、查询构造器或者 Db::table() 等方式访问数据库时，Hyperf 会在协程结束时自动归还连接，不需要开发者手动释放。即使需要执行原生查询，也应当通过 Db::select() 这类静态方法，而不是自己持有连接对象。
// 正确示例：使用模型或查询构造器，框架自动释放连接
use App\Model\User;
$users = User::query()->where('status', 1)->get();
事务操作同样要遵循这个原则。推荐使用 Db::transaction() 闭包方式执行事务，闭包执行完毕后连接会自动归还。如果手动开始事务，一定要在 finally 中回滚或提交，并确保连接释放，否则事务持有连接的时间会非常长，直接影响连接池可用性。
// 正确示例：使用闭包事务
Db::transaction(function () {
User::query()->where('id', 1)->update(['name' => 'Hyperf']);
});
注解缓存与代理类：为什么改了配置不生效
Hyperf 大量使用注解和 AOP 来实现依赖注入、中间件、事件监听等功能。框架启动时会扫描注解并生成代理类，这些代理类通常缓存在 runtime/container 目录下。很多新手在开发环境修改了控制器注解、路由配置或者依赖注入关系后，发现服务并没有按照新的代码执行，就以为是框架出错了。实际上往往是因为旧的代理类缓存还在，框架没有重新生成。
开发阶段可以关闭注解缓存，让每次请求都重新扫描，代价是性能会下降。对应的做法是在注解配置文件里把 cacheable 设置为 false。不过更常见的处理方式是修改代码后手动清理代理类缓存，再重启服务，或者直接执行代理类生成命令。
php bin/hyperf.php di:init-proxy
如果不想执行完整生成流程，也可以直接删除运行时代理目录，让框架在下次启动时重新扫描生成。
rm -rf runtime/container
生产环境应当开启注解缓存，并且在发布流程中预先执行 di:init-proxy 生成代理类。这样服务启动后可以直接加载缓存，避免运行时反复扫描带来的性能损耗。很多运维脚本只执行了 composer install 和重启，却漏掉了代理类生成，导致上线后接口返回 500 或者依赖注入失败。这类问题在日志里通常会表现为类不存在或代理类加载失败，排查方向一定要指向注解缓存。
超全局变量与Session：传统写法如何变成隐患
在 PHP-FPM 环境中，$_GET、$_POST、$_COOKIE、$_SERVER 等超全局变量在每次请求结束后都会被销毁，不会串到下一个请求。但 Swoole 常驻内存进程会复用这些超全局变量，多个协程并发执行时，它们可能读到被其他协程修改过的值。因此直接使用 $_GET 获取参数，很容易在并发场景下拿到错误数据。
正确做法是使用 Hyperf 的请求对象。控制器方法可以通过依赖注入拿到 RequestInterface 实例，再调用 input()、query()、post() 等方法获取参数。这些方法内部已经处理了协程隔离，能保证当前协程读取到的是当前请求的数据。
// 错误示例：在协程环境直接使用超全局变量 $id = $_GET['id'] ?? 0; $page = $_POST['page'] ?? 1;
// 正确示例：通过请求对象获取参数
use Hyperf\HttpServer\Contract\RequestInterface;
class UserController
{
public function index(RequestInterface $request)
{
$id = $request->input('id', 0);
$page = $request->input('page', 1);
return ['id' => $id, 'page' => $page];
}
}
Session 的使用也需要注意。Hyperf 默认没有启用传统 Session，如果直接使用 $_SESSION，往往不会得到预期结果。正确做法是安装 hyperf/session 组件，配置 Session 中间件，并通过请求对象的 session() 方法读写会话数据。这样可以避免原生 Session 在协程环境下的文件锁和隔离问题。尤其是需要跨请求保持登录状态时，务必使用框架提供的 Session 组件，而不是依赖 PHP 原生机制。
总的来说，Hyperf 的坑大多来自运行模型的变化，而不是框架本身的缺陷。只要把思维从每次请求一个完整生命周期切换到常驻内存加协程隔离，优先使用框架注入的对象而不是全局状态，再配合正确的连接池和注解缓存处理，大部分入门阶段的问题都能顺利避开。