半夜两点被报警电话叫醒线上用户信息串号了A账号的请求日志里却到处是B账号的操作。这种事发生在 Hyperf 项目里十有八九是协程上下文Context被当成了普通全局变量或者静态变量在用。今天这篇就把 Hyperf 的协程上下文机制彻底聊透它到底是个什么东西、为什么能解决数据共享错乱、实际项目里怎么用才安全、出了问题又该怎么排查。适合正在用 Hyperf 写接口、做微服务、搞异步任务的 PHP 后端同学尤其是被并发问题坑过但还没系统理清原理的人。1. 协程上下文到底是什么它凭什么解决数据错乱1.1 从“一进程一请求”到“一进程多协程”的思维转变传统 PHP-FPM 模式下每个请求独占一个进程进程内的变量天然隔离。你用静态变量存当前用户IDA 请求进程里的静态变量和 B 请求进程里的静态变量互不相干虽然浪费内存但不会串数据。到了 Swoole 常驻内存模型里情况彻底变了一个 Worker 进程内可以同时并发运行成千上万个协程每个协程像一条独立的“轻量线程”都在同一份 PHP 变量空间里执行。这时候如果你还靠静态变量存“当前登录用户”所有协程读到的都是同一个变量谁最后写谁就覆盖前面的人于是就会出现开头说的“A 请求日志里出现 B 用户操作”的灵异现象。核心矛盾就在这里Swoole 让 PHP 从一个进程只能处理一个请求变成了一个进程内可以同时处理成千上万个请求但 PHP 本身并没有为“协程级隔离”提供内建的变量空间。传统思维里的静态属性、全局变量、单例对象属性在常驻内存 多协程下全都变成了公共厕所谁都能进谁都能改。要解决这个问题就必须有一种“跟着协程走”的存储机制每个协程有自己的独立空间协程销毁空间自动回收这就是 Hyperf 协程上下文存在的根本原因。1.2 协程上下文就是“每个协程专属的储物柜”我用一个生活化类比来解释协程上下文想象一艘远洋货轮Worker 进程船上有许多水手协程每个水手都在同时忙碌。如果全船只有一个公共储物柜静态变量A 水手把工具放进去B 水手马上就能拿走两个人必然打架。协程上下文相当于给每个水手发了一个带锁的专属储物柜自己的东西放自己的柜子里别人想拿也拿不到船到港后协程结束柜子自动清空。在 Hyperf 里这个“专属储物柜”的操作入口就是Hyperf\Context\Context这个静态类。注意它虽然是一个“静态类”但内部并不是用静态属性存业务数据而是通过协程 ID 把数据隔离到不同的空间里。你调用Context::set(user_id, 100)写入的数据只有当前协程能通过Context::get(user_id)读到另一个协程去Context::get(user_id)拿到的要么是 null要么是这个协程自己写入的另一个值。这个设计从根本上解决了协程之间共享状态互相污染的问题。1.3 底层实现与生命周期协程ID是关键Hyperf 协程上下文的底层实现不同版本细节略有差异但核心思想是一致的内部维护一个以协程 ID 为 key 的存储结构每个协程 ID 对应一个独立的数组或 ArrayObject 容器。当你执行Context::set(user_id, 100)时实际是先把Coroutine::id()取出来作为当前协程的 ID然后往这个 ID 对应的容器里写入user_id执行Context::get(user_id)时也是先拿当前协程 ID再从这个容器里读取。生命周期方面Hyperf 框架在协程创建时会给这个协程初始化一个空的上下文容器并在协程退出时通过底层回调把它整体清理掉。所以你用 Context 存数据不用像静态变量那样担心“上次请求残留”。这也是协程上下文和传统全局变量最本质的区别作用域和生命周期都严格绑定协程协程没了数据跟着没。2. 核心 API 速查与正确用法2.1 五个常用方法一张表看清楚Hyperf 提供的上下文 API 并不多日常开发主要用到下面这五个方法。以 Hyperf 2.2 之后的版本为例命名空间是Hyperf\Context\Context旧版本或 2.0 早期是Hyperf\Utils\Context迁移时候注意一下就行。方法签名作用返回setset(string $id, $value, ?int $coroutineId null)向当前协程上下文写入一个值返回写入的 valuegetget(string $id, $default null, ?int $coroutineId null)从当前协程上下文读取一个值不存在返回 default任意类型hashas(string $id, ?int $coroutineId null)判断当前协程上下文是否存在指定 keybooloverrideoverride(string $id, callable $callback, ?int $coroutineId null)获取旧值经过回调处理后写回返回回调处理后的新值destroydestroy(?int $coroutineId null)销毁指定协程的整个上下文void单独看这些签名可能有点抽象实际用起来很简单。set和get是最常用的一个写一个读has通常用来判断某个数据是否已经初始化过override适合做“读-改-写”的场景比如在协程上下文里维护一个计数器或者累加器destroy一般用不上框架已经帮你管理好了。2.2 从中间件写入到 Service 层读取我用一个最常见的“登录态传递”场景来演示正确用法。用户请求到达后框架会依次执行中间件在中间件里解析 Token把用户 ID 写入协程上下文后面的控制器、Service 层再去读取这个用户 ID。下面是中间件代码?php declare(strict_types1); namespace App\Middleware; use Hyperf\Context\Context; use Hyperf\HttpServer\Contract\RequestInterface; use Hyperf\HttpServer\Contract\ResponseInterface; use Psr\Container\ContainerInterface; use Psr\Http\Message\ResponseInterface as PsrResponseInterface; use Psr\Http\Server\MiddlewareInterface; use Psr\Http\Server\RequestHandlerInterface; class UserAuthMiddleware implements MiddlewareInterface { public function __construct( protected ContainerInterface $container, protected RequestInterface $request, protected ResponseInterface $response ) {} public function process(Psr\Http\Message\ServerRequestInterface $request, RequestHandlerInterface $handler): PsrResponseInterface { // 解析 token获取 userId这里省略具体解析逻辑 $userId $this-resolveUserIdFromRequest($request); if ($userId null) { return $this-response-json([code 401, message 未登录]); } // 关键把用户ID写入当前协程上下文 Context::set(user_id, $userId); return $handler-handle($request); } protected function resolveUserIdFromRequest($request): ?int { $token $request-getHeaderLine(Authorization); // 伪代码解析 token 得到 userId return 10086; } }在业务代码里不管是在控制器、Service 还是自定义组件中只要和刚才那个请求在同一个协程内执行都可以直接读取?php declare(strict_types1); namespace App\Service; use Hyperf\Context\Context; class UserService { public function getCurrentUserId(): int { // 从协程上下文读取当前请求的用户ID $userId Context::get(user_id, 0); if ($userId 0) { throw new \RuntimeException(无法获取当前用户); } return $userId; } }很多人第一次接触会问为什么不直接定义一个静态属性存 userId因为静态属性在所有协程之间是共享的而 Context 是跟随协程隔离的。中间件和 Service 只要在同一个协程里执行Context 读写就完全透明跟用全局变量一样顺手但不会互相串号。我实际项目中这个模式非常常用中间件里鉴权、写入用户身份业务层无感读取干净利落。2.3 上下文的存放原则什么该放什么不该放协程上下文虽好但不是垃圾桶什么都能往里扔。我见到的线上事故里有一半是把不该放的东西放进了 Context。首先只放请求级、链路级的数据。用户ID、租户ID、traceId、requestId、当前语言、当前请求的权限标识这些都和“当前这趟请求线索”强相关非常适合放 Context。而全局配置、数据库连接参数、Redis 地址这些属于应用级配置应该放 Config 组件里放进 Context 纯属浪费。其次不要把连接对象直接塞进 Context 并期望跨协程复用。For example你写Context::set(redis_connection, $redis)在当前协程内没问题但一旦切到另一个协程Context::get(redis_connection)大概率是 null反而造成连接反复创建。连接池该用连接池Context 不具备跨协程共享能力。最后key 一定要用常量或统一管理千万不要各写各的字符串。有人在一个 Service 里写Context::set(uid, 100)另一个 Service 里写Context::set(user_id, 200)结果就是一个协程里同时存在两个“用户ID”的 key后面读的时候全凭缘分。我建议在项目里定义一个ContextKey常量类所有 key 都从那里取这是避免混乱最便宜的办法。?php declare(strict_types1); namespace App\Constants; class ContextKey { public const USER_ID user_id; public const TRACE_ID trace_id; public const TENANT_ID tenant_id; public const REQUEST_ID request_id; }3. 从登录态到链路追踪三个实战场景一次讲清3.1 场景一用户身份从中间件贯穿到业务层这个场景在上面已经演示过代码了这里说几个执行细节。中间件写入 Context 后要确保后续业务代码确实在同一个协程内执行。在 Hyperf 的常规请求流程里中间件、控制器、Service 通常都在同一个协程中所以读写没有问题。但如果你在 Service 里用parallel()再开子协程子协程里的Context::get(user_id)就拿不到了因为子协程是一个全新的协程空间。我在实际项目里遇到过一种隐蔽问题用户在一个请求里同时调用了多个接口每个接口都有各自的协程但业务代码里有个全局单例对象缓存了当前用户信息。第一次请求把用户A的信息写进了单例属性第二次请求用户B进来单例属性还残留着用户A的数据B 的业务逻辑实际操作的是用户A的权限。这种问题很难排查因为错误是间歇性的而且看起来像是缓存问题。解决办法就是杜绝用单例/静态属性存请求级数据一律走 Context。3.2 场景二并发协程里安全地缓存当前请求内的重复查询协程上下文还有一个很实用的用法在当前请求的作用域内做“进程内短缓存”。比如一个接口里多次调用同一个方法获取用户资料如果不做缓存每次都要查一次数据库。在传统 PHP 进程里你可以用局部变量把结果存下来在协程并发场景下如果你用静态属性做这个缓存并发请求之间就会互相污染。正确做法是把结果存进 Context。我第一次获取用户资料时查库然后把结果Context::set(user_profile_ . $userId, $profile)后续再获取时先Context::get命中就直接返回。因为 Context 跟着协程走所以同一个请求里多次复用同一个数据既省了数据库查询又不会把用户A的资料带给用户B。?php declare(strict_types1); namespace App\Service; use Hyperf\Context\Context; use App\Constants\ContextKey; use App\Model\User; class UserQueryService { public function getProfile(int $userId): ?User { $cacheKey user_profile_ . $userId; if (Context::has($cacheKey)) { return Context::get($cacheKey); } $profile User::query()-find($userId); Context::set($cacheKey, $profile); return $profile; } }注意这段代码有两个关键细节第一缓存 key 里带了用户 ID表示这份缓存是“某个特定用户的数据”不会和其他协程的数据冲突第二这里仍然要求读和写在同一个协程内。如果这两个操作被拆到两个协程里第二条语句Context::get就会拿不到。这一点在使用时一定要心里有数。3.3 场景三traceId 跨协程传递与日志链路串联链路追踪是微服务、异步任务场景下的刚需。问题在于一次完整的业务请求可能涉及 RPC 调用、异步队列、定时任务这些操作往往发生在不同的协程里。如果 Context 天然隔离traceId 是怎么跨协程传递的呢答案很简单必须显式传递。一般来说外层协程在收到请求时生成一个 traceId比如用 UUID 或者雪花算法生成然后把它Context::set(trace_id, $traceId)。当需要开启子协程执行异步任务时你不能指望子协程自动继承而应该把 traceId 作为子协程的创建参数传进去在子协程内部再手动Context::set到子协程自己的空间里。?php declare(strict_types1); use Hyperf\Context\Context; use function Hyperf\Coroutine\parallel; use function Hyperf\Coroutine\go; // 外层协程设置 traceId $traceId uniqid(trace_, true); Context::set(trace_id, $traceId); // 方式一在子协程里通过参数传入并重新设置到子协程上下文 go(function () use ($traceId) { Context::set(trace_id, $traceId); // 子协程业务逻辑 var_dump(Context::get(trace_id)); // 能拿到 }); // 方式二parallel 开启并发子协程时同样传参 parallel([ function () use ($traceId) { Context::set(trace_id, $traceId); // 子协程业务逻辑 var_dump(Context::get(trace_id)); }, ]);这个传递动作是显式的代码会变得啰嗦一点但安全可靠。在日志组件里封装一个Logger::get()方法统一从 Context 中读 traceId把它追加到每一条日
Hyperf协程上下文机制详解：告别数据串号与并发污染
半夜两点被报警电话叫醒线上用户信息串号了A账号的请求日志里却到处是B账号的操作。这种事发生在 Hyperf 项目里十有八九是协程上下文Context被当成了普通全局变量或者静态变量在用。今天这篇就把 Hyperf 的协程上下文机制彻底聊透它到底是个什么东西、为什么能解决数据共享错乱、实际项目里怎么用才安全、出了问题又该怎么排查。适合正在用 Hyperf 写接口、做微服务、搞异步任务的 PHP 后端同学尤其是被并发问题坑过但还没系统理清原理的人。1. 协程上下文到底是什么它凭什么解决数据错乱1.1 从“一进程一请求”到“一进程多协程”的思维转变传统 PHP-FPM 模式下每个请求独占一个进程进程内的变量天然隔离。你用静态变量存当前用户IDA 请求进程里的静态变量和 B 请求进程里的静态变量互不相干虽然浪费内存但不会串数据。到了 Swoole 常驻内存模型里情况彻底变了一个 Worker 进程内可以同时并发运行成千上万个协程每个协程像一条独立的“轻量线程”都在同一份 PHP 变量空间里执行。这时候如果你还靠静态变量存“当前登录用户”所有协程读到的都是同一个变量谁最后写谁就覆盖前面的人于是就会出现开头说的“A 请求日志里出现 B 用户操作”的灵异现象。核心矛盾就在这里Swoole 让 PHP 从一个进程只能处理一个请求变成了一个进程内可以同时处理成千上万个请求但 PHP 本身并没有为“协程级隔离”提供内建的变量空间。传统思维里的静态属性、全局变量、单例对象属性在常驻内存 多协程下全都变成了公共厕所谁都能进谁都能改。要解决这个问题就必须有一种“跟着协程走”的存储机制每个协程有自己的独立空间协程销毁空间自动回收这就是 Hyperf 协程上下文存在的根本原因。1.2 协程上下文就是“每个协程专属的储物柜”我用一个生活化类比来解释协程上下文想象一艘远洋货轮Worker 进程船上有许多水手协程每个水手都在同时忙碌。如果全船只有一个公共储物柜静态变量A 水手把工具放进去B 水手马上就能拿走两个人必然打架。协程上下文相当于给每个水手发了一个带锁的专属储物柜自己的东西放自己的柜子里别人想拿也拿不到船到港后协程结束柜子自动清空。在 Hyperf 里这个“专属储物柜”的操作入口就是Hyperf\Context\Context这个静态类。注意它虽然是一个“静态类”但内部并不是用静态属性存业务数据而是通过协程 ID 把数据隔离到不同的空间里。你调用Context::set(user_id, 100)写入的数据只有当前协程能通过Context::get(user_id)读到另一个协程去Context::get(user_id)拿到的要么是 null要么是这个协程自己写入的另一个值。这个设计从根本上解决了协程之间共享状态互相污染的问题。1.3 底层实现与生命周期协程ID是关键Hyperf 协程上下文的底层实现不同版本细节略有差异但核心思想是一致的内部维护一个以协程 ID 为 key 的存储结构每个协程 ID 对应一个独立的数组或 ArrayObject 容器。当你执行Context::set(user_id, 100)时实际是先把Coroutine::id()取出来作为当前协程的 ID然后往这个 ID 对应的容器里写入user_id执行Context::get(user_id)时也是先拿当前协程 ID再从这个容器里读取。生命周期方面Hyperf 框架在协程创建时会给这个协程初始化一个空的上下文容器并在协程退出时通过底层回调把它整体清理掉。所以你用 Context 存数据不用像静态变量那样担心“上次请求残留”。这也是协程上下文和传统全局变量最本质的区别作用域和生命周期都严格绑定协程协程没了数据跟着没。2. 核心 API 速查与正确用法2.1 五个常用方法一张表看清楚Hyperf 提供的上下文 API 并不多日常开发主要用到下面这五个方法。以 Hyperf 2.2 之后的版本为例命名空间是Hyperf\Context\Context旧版本或 2.0 早期是Hyperf\Utils\Context迁移时候注意一下就行。方法签名作用返回setset(string $id, $value, ?int $coroutineId null)向当前协程上下文写入一个值返回写入的 valuegetget(string $id, $default null, ?int $coroutineId null)从当前协程上下文读取一个值不存在返回 default任意类型hashas(string $id, ?int $coroutineId null)判断当前协程上下文是否存在指定 keybooloverrideoverride(string $id, callable $callback, ?int $coroutineId null)获取旧值经过回调处理后写回返回回调处理后的新值destroydestroy(?int $coroutineId null)销毁指定协程的整个上下文void单独看这些签名可能有点抽象实际用起来很简单。set和get是最常用的一个写一个读has通常用来判断某个数据是否已经初始化过override适合做“读-改-写”的场景比如在协程上下文里维护一个计数器或者累加器destroy一般用不上框架已经帮你管理好了。2.2 从中间件写入到 Service 层读取我用一个最常见的“登录态传递”场景来演示正确用法。用户请求到达后框架会依次执行中间件在中间件里解析 Token把用户 ID 写入协程上下文后面的控制器、Service 层再去读取这个用户 ID。下面是中间件代码?php declare(strict_types1); namespace App\Middleware; use Hyperf\Context\Context; use Hyperf\HttpServer\Contract\RequestInterface; use Hyperf\HttpServer\Contract\ResponseInterface; use Psr\Container\ContainerInterface; use Psr\Http\Message\ResponseInterface as PsrResponseInterface; use Psr\Http\Server\MiddlewareInterface; use Psr\Http\Server\RequestHandlerInterface; class UserAuthMiddleware implements MiddlewareInterface { public function __construct( protected ContainerInterface $container, protected RequestInterface $request, protected ResponseInterface $response ) {} public function process(Psr\Http\Message\ServerRequestInterface $request, RequestHandlerInterface $handler): PsrResponseInterface { // 解析 token获取 userId这里省略具体解析逻辑 $userId $this-resolveUserIdFromRequest($request); if ($userId null) { return $this-response-json([code 401, message 未登录]); } // 关键把用户ID写入当前协程上下文 Context::set(user_id, $userId); return $handler-handle($request); } protected function resolveUserIdFromRequest($request): ?int { $token $request-getHeaderLine(Authorization); // 伪代码解析 token 得到 userId return 10086; } }在业务代码里不管是在控制器、Service 还是自定义组件中只要和刚才那个请求在同一个协程内执行都可以直接读取?php declare(strict_types1); namespace App\Service; use Hyperf\Context\Context; class UserService { public function getCurrentUserId(): int { // 从协程上下文读取当前请求的用户ID $userId Context::get(user_id, 0); if ($userId 0) { throw new \RuntimeException(无法获取当前用户); } return $userId; } }很多人第一次接触会问为什么不直接定义一个静态属性存 userId因为静态属性在所有协程之间是共享的而 Context 是跟随协程隔离的。中间件和 Service 只要在同一个协程里执行Context 读写就完全透明跟用全局变量一样顺手但不会互相串号。我实际项目中这个模式非常常用中间件里鉴权、写入用户身份业务层无感读取干净利落。2.3 上下文的存放原则什么该放什么不该放协程上下文虽好但不是垃圾桶什么都能往里扔。我见到的线上事故里有一半是把不该放的东西放进了 Context。首先只放请求级、链路级的数据。用户ID、租户ID、traceId、requestId、当前语言、当前请求的权限标识这些都和“当前这趟请求线索”强相关非常适合放 Context。而全局配置、数据库连接参数、Redis 地址这些属于应用级配置应该放 Config 组件里放进 Context 纯属浪费。其次不要把连接对象直接塞进 Context 并期望跨协程复用。For example你写Context::set(redis_connection, $redis)在当前协程内没问题但一旦切到另一个协程Context::get(redis_connection)大概率是 null反而造成连接反复创建。连接池该用连接池Context 不具备跨协程共享能力。最后key 一定要用常量或统一管理千万不要各写各的字符串。有人在一个 Service 里写Context::set(uid, 100)另一个 Service 里写Context::set(user_id, 200)结果就是一个协程里同时存在两个“用户ID”的 key后面读的时候全凭缘分。我建议在项目里定义一个ContextKey常量类所有 key 都从那里取这是避免混乱最便宜的办法。?php declare(strict_types1); namespace App\Constants; class ContextKey { public const USER_ID user_id; public const TRACE_ID trace_id; public const TENANT_ID tenant_id; public const REQUEST_ID request_id; }3. 从登录态到链路追踪三个实战场景一次讲清3.1 场景一用户身份从中间件贯穿到业务层这个场景在上面已经演示过代码了这里说几个执行细节。中间件写入 Context 后要确保后续业务代码确实在同一个协程内执行。在 Hyperf 的常规请求流程里中间件、控制器、Service 通常都在同一个协程中所以读写没有问题。但如果你在 Service 里用parallel()再开子协程子协程里的Context::get(user_id)就拿不到了因为子协程是一个全新的协程空间。我在实际项目里遇到过一种隐蔽问题用户在一个请求里同时调用了多个接口每个接口都有各自的协程但业务代码里有个全局单例对象缓存了当前用户信息。第一次请求把用户A的信息写进了单例属性第二次请求用户B进来单例属性还残留着用户A的数据B 的业务逻辑实际操作的是用户A的权限。这种问题很难排查因为错误是间歇性的而且看起来像是缓存问题。解决办法就是杜绝用单例/静态属性存请求级数据一律走 Context。3.2 场景二并发协程里安全地缓存当前请求内的重复查询协程上下文还有一个很实用的用法在当前请求的作用域内做“进程内短缓存”。比如一个接口里多次调用同一个方法获取用户资料如果不做缓存每次都要查一次数据库。在传统 PHP 进程里你可以用局部变量把结果存下来在协程并发场景下如果你用静态属性做这个缓存并发请求之间就会互相污染。正确做法是把结果存进 Context。我第一次获取用户资料时查库然后把结果Context::set(user_profile_ . $userId, $profile)后续再获取时先Context::get命中就直接返回。因为 Context 跟着协程走所以同一个请求里多次复用同一个数据既省了数据库查询又不会把用户A的资料带给用户B。?php declare(strict_types1); namespace App\Service; use Hyperf\Context\Context; use App\Constants\ContextKey; use App\Model\User; class UserQueryService { public function getProfile(int $userId): ?User { $cacheKey user_profile_ . $userId; if (Context::has($cacheKey)) { return Context::get($cacheKey); } $profile User::query()-find($userId); Context::set($cacheKey, $profile); return $profile; } }注意这段代码有两个关键细节第一缓存 key 里带了用户 ID表示这份缓存是“某个特定用户的数据”不会和其他协程的数据冲突第二这里仍然要求读和写在同一个协程内。如果这两个操作被拆到两个协程里第二条语句Context::get就会拿不到。这一点在使用时一定要心里有数。3.3 场景三traceId 跨协程传递与日志链路串联链路追踪是微服务、异步任务场景下的刚需。问题在于一次完整的业务请求可能涉及 RPC 调用、异步队列、定时任务这些操作往往发生在不同的协程里。如果 Context 天然隔离traceId 是怎么跨协程传递的呢答案很简单必须显式传递。一般来说外层协程在收到请求时生成一个 traceId比如用 UUID 或者雪花算法生成然后把它Context::set(trace_id, $traceId)。当需要开启子协程执行异步任务时你不能指望子协程自动继承而应该把 traceId 作为子协程的创建参数传进去在子协程内部再手动Context::set到子协程自己的空间里。?php declare(strict_types1); use Hyperf\Context\Context; use function Hyperf\Coroutine\parallel; use function Hyperf\Coroutine\go; // 外层协程设置 traceId $traceId uniqid(trace_, true); Context::set(trace_id, $traceId); // 方式一在子协程里通过参数传入并重新设置到子协程上下文 go(function () use ($traceId) { Context::set(trace_id, $traceId); // 子协程业务逻辑 var_dump(Context::get(trace_id)); // 能拿到 }); // 方式二parallel 开启并发子协程时同样传参 parallel([ function () use ($traceId) { Context::set(trace_id, $traceId); // 子协程业务逻辑 var_dump(Context::get(trace_id)); }, ]);这个传递动作是显式的代码会变得啰嗦一点但安全可靠。在日志组件里封装一个Logger::get()方法统一从 Context 中读 traceId把它追加到每一条日
