Hyperf从零到一加上一个简单的 Middleware 记录耗时的庖丁解牛

它的本质是在 HTTP 请求进入业务逻辑之前Pre-processing和响应返回之后Post-processing插入一个“计时器”。通过计算两个时间点的差值得到接口的执行耗时并将其记录到日志或监控系统中。这是一种非侵入式 (Non-invasive)的代码增强技术无需修改任何 Controller 代码即可实现全局性能监控。如果把 Hyperf 的请求处理比作一条工厂流水线Request是原材料。Controller/Service是核心加工车间。Middleware是流水线上的质检员/记录仪。动作原材料进来质检员看一眼手表$start microtime(true)。放行原材料进入车间$handler-handle($request)。成品出来质检员再看一眼手表$end microtime(true)。计算耗时贴标签写 Log然后放行成品。核心逻辑别在车间里每个工位都装手表。在入口处装一个就能统计整条流水线的总耗时。一、核心原理中间件是如何工作的1. 责任链模式 (Chain of Responsibility)Hyperf 的中间件是一个链表。每个中间件持有下一个处理者 (RequestHandlerInterface) 的引用。调用$handler-handle($request)会将请求传递给下一个中间件或最终的 Controller。关键点$handler-handle()之前的代码是“前置逻辑”之后的代码是“后置逻辑”。2. PSR-15 标准Hyperf 遵循 PHP-FIG 的 PSR-15 标准。接口Psr\Http\Server\MiddlewareInterface。方法process(ServerRequestInterface $request, RequestHandlerInterface $handler): ResponseInterface。3. 协程上下文 (Coroutine Context)在 Swoole/Hyperf 中每个请求运行在独立的协程中。microtime(true)获取的是当前协程的系统时间精度极高微秒级。注意不要使用全局静态变量存储状态因为协程间是隔离的。但记录日志是安全的因为 Log 组件也是协程安全的。 核心洞察中间件是“横切关注点”的完美载体。它将日志、鉴权、限流等与业务无关的逻辑从业务代码中剥离出来保持 Controller 的纯净。二、代码实现从零编写Step 1: 创建中间件类在终端运行php bin/hyperf.php gen:middleware App/Middleware/PerformanceMonitorMiddleware或者手动创建文件app/Middleware/PerformanceMonitorMiddleware.php?phpdeclare(strict_types1);namespaceApp\Middleware;useHyperf\Contract\ConfigInterface;usePsr\Http\Message\ResponseInterface;usePsr\Http\Message\ServerRequestInterface;usePsr\Http\Server\MiddlewareInterface;usePsr\Http\Server\RequestHandlerInterface;useHyperf\Logger\LoggerFactory;usePsr\Log\LoggerInterface;classPerformanceMonitorMiddlewareimplementsMiddlewareInterface{privateLoggerInterface$logger;// 注入 Logger用于记录耗时publicfunction__construct(LoggerFactory$loggerFactory){// 创建一个名为 performance 的日志通道$this-logger$loggerFactory-get(performance);}publicfunctionprocess(ServerRequestInterface$request,RequestHandlerInterface$handler):ResponseInterface{// 1. 【前置】记录开始时间$startTimemicrotime(true);// 获取请求信息方便后续日志分析$method$request-getMethod();$uri$request-getUri()-getPath();try{// 2. 【核心】将请求传递给下一个节点 (Controller 或其他 Middleware)// 这一步是阻塞的直到业务逻辑执行完毕并返回 Response$response$handler-handle($request);return$response;}finally{// 3. 【后置】记录结束时间并计算耗时// 使用 finally 确保即使发生异常也能记录耗时可选视需求而定$endTimemicrotime(true);$duration($endTime-$startTime)*1000;// 转换为毫秒// 4. 【记录】只记录慢请求避免日志爆炸// 阈值设为 100ms可根据项目调整if($duration100){$this-logger-warning(Slow API Detected,[method$method,uri$uri,duration_msround($duration,2),status$response-getStatusCode(),trace_id$request-getAttribute(trace_id)??uniqid()// 如果有链路追踪ID]);}// 也可以在 Header 中返回耗时供前端调试// $response $response-withHeader(X-Response-Time, round($duration, 2) . ms);}}}关键细节解析try...finally确保即使业务代码抛出异常耗时也能被记录。这对于排查“为什么这个接口报错且慢”非常有用。阈值过滤if ($duration 100)。全量记录会产生海量日志拖慢磁盘 IO。只记录慢请求是最佳实践。Logger 注入使用LoggerFactory获取独立的日志通道便于后续单独分析性能日志。三、配置注册如何让它生效中间件写好了必须告诉 Hyperf 在什么时候使用它。场景 A全局中间件 (Global Middleware)适用于所有 HTTP 请求。编辑config/autoload/middlewares.php?phpreturn[http[\App\Middleware\PerformanceMonitorMiddleware::class,// 其他全局中间件...],];顺序数组前面的先执行。通常性能监控应该放在较前的位置以包含更多中间件的耗时如鉴权、参数校验。场景 B路由级中间件 (Route Middleware)只适用于特定接口。在config/routes.php中Router::addRoute([GET,POST],/api/slow-test,App\Controller\TestControllerindex,[middleware[\App\Middleware\PerformanceMonitorMiddleware::class]]);场景 C控制器级中间件在 Controller 类上使用注解useHyperf\HttpServer\Annotation\Middleware;#[Middleware(\App\Middleware\PerformanceMonitorMiddleware::class)]classTestController{// ...} 推荐对于性能审计建议使用全局中间件以便捕捉所有接口的表现。四、验证与测试1. 启动服务php bin/hyperf.php start2. 模拟慢请求创建一个测试 Controllerapp/Controller/TestController.php?phpnamespaceApp\Controller;useHyperf\HttpServer\Annotation\Controller;useHyperf\HttpServer\Annotation\GetMapping;#[Controller(prefix:/api)]classTestController{#[GetMapping(path:/slow)]publicfunctionslow(){// 模拟耗时操作睡眠 0.2 秒usleep(200000);return[messageHello World];}#[GetMapping(path:/fast)]publicfunctionfast(){return[messageFast];}}3. 发起请求curlhttp://127.0.0.1:9501/api/slowcurlhttp://127.0.0.1:9501/api/fast4. 查看日志查看runtime/logs/performance.log(假设你配置了 performance channel)。你应该能看到类似这样的日志{message:Slow API Detected,context:{method:GET,uri:/api/slow,duration_ms:205.12,status:200},level:200,datetime:2026-05-06T10:00:0008:00}而/api/fast因为低于 100ms不会被记录。五、认知跃迁从“记录”到“治理”1. 避免日志风暴 (Log Storm)问题如果 QPS 很高即使只有 1% 的慢请求日志量也可能巨大。优化采样率只记录 10% 的慢请求。异步写入Hyperf 的 Logger 默认是异步的基于 Swoole Coroutine但确保不要阻塞主流程。外部存储将日志推送到 ELK (Elasticsearch, Logstash, Kibana) 或 Prometheus Grafana而不是存在本地文件。2. 区分“真慢”与“假慢”真慢CPU 计算密集、DB 查询慢、代码逻辑复杂。假慢网络延迟、客户端断开连接、GC 暂停。对策结合 APM 工具如 SkyWalking查看 Trace 链路确定慢在哪一层DB? Redis? External API?。3. 响应头反馈在开发环境可以将耗时放入 Response HeaderX-Response-Time。前端开发者可以直接在浏览器 Network 面板看到后端耗时便于联调。4. 协程安全提醒严禁在中间件中使用全局静态变量存储请求级数据如$staticData[$fd] $startTime。正确使用局部变量或 Hyperf 的Context组件如果需要跨函数传递。 总结原子化“Hyperf 耗时中间件”全景图维度关键点本质基于责任链模式的非侵入式性能监控核心逻辑Pre: Start Timer - Handle - Post: Calc Log关键技术PSR-15, microtime(true), LoggerFactory最佳实践阈值过滤、Finally 块、异步日志、全局注册常见陷阱日志爆炸、阻塞 IO、协程数据污染PHP 隐喻Aspect-Oriented Programming (AOP) Lite公式Duration End_Time - Start_Time终极心法中间件的本质是“对流程的优雅介入”。别污染业务代码让监控像空气一样无处不在却又无形。记录耗时只是第一步治理缓慢才是终点。于切入中见解耦于计时见真相以非侵入为尺解耦合之牛于系统观测中求透明之真。行动指令复制代码将上面的PerformanceMonitorMiddleware复制到你的项目。配置日志在config/autoload/logger.php中添加performance通道。注册中间件在middlewares.php中启用它。压测观察用ab或wrk压测你的接口观察日志输出。思维升级记住可观测性是系统的眼睛。没有监控的优化就是盲人摸象。