Hyperf自定义中间件需三步：一、创建实现MiddlewareInterface的类（如JwtAuthMiddleware）；二、在middlewares.php中注册为全局/路由级/控制器级；三、通过路由middleware()或控制器construct()绑定启用。
Hyperf 中间件通过 PSR-15 标准实现，添加自定义中间件只需三步：定义中间件类、注册到配置、在路由或控制器中启用。
一、创建自定义中间件类
在 app/Middleware 目录下新建 PHP 类，实现 MiddlewareInterface 接口：
例如创建 App\Middleware\JwtAuthMiddleware：
namespace App\Middleware;
use Hyperf\HttpServer\Contract\RequestInterface;
use Hyperf\HttpServer\Contract\ResponseInterface as HttpResponse;
use Psr\Http\Message\ResponseInterface;
use Psr\Http\Message\ServerRequestInterface;
use Psr\Http\Server\MiddlewareInterface;
use Psr\Http\Server\RequestHandlerInterface;
class JwtAuthMiddleware implements MiddlewareInterface
{
public function process(ServerRequestInterface $request, RequestHandlerInterface $handler): ResponseInterface
{
$token = $request->getHeaderLine('Authorization');
if (empty($token)) {
return json_encode(['code' => 401, 'message' => 'Missing token'], JSON_UNESCAPED_UNICODE);
}
// 此处可加入 JWT 解析与校验逻辑
return $handler->handle($request);
}
}
二、注册中间件到配置
打开 config/autoload/middlewares.php，按作用范围注册：
-
全局中间件（所有 HTTP 请求生效）：添加到
'http' => [...]数组中 - 路由级中间件（仅特定路由生效）：不在此文件注册，改用路由定义时链式调用
-
控制器级中间件（仅某控制器生效）：在控制器构造函数中使用
$this->middleware(...)
示例（全局注册）：
return [
'http' => [
\App\Middleware\JwtAuthMiddleware::class,
// 其他中间件...
],
];
三、在路由中单独启用中间件
使用 ->middleware() 方法为指定路由绑定中间件：
// routes/http.php
use Hyperf\HttpServer\Router\Router;
Router::addRoute(['GET', 'POST'], '/api/user', [\App\Controller\UserController::class, 'index'])
->middleware(\App\Middleware\JwtAuthMiddleware::class);
支持传入多个中间件，顺序执行：
->middleware([
\App\Middleware\JwtAuthMiddleware::class,
\App\Middleware\PermissionCheckMiddleware::class
])
四、在控制器中动态绑定中间件
在控制器构造函数中调用 $this->middleware()：
namespace App\Controller;
use Hyperf\HttpServer\Controller\AbstractController;
class UserController extends AbstractController
{
public function __construct()
{
$this->middleware(\App\Middleware\JwtAuthMiddleware::class);
// 或带参数：$this->middleware(JwtAuthMiddleware::class, ['except' => ['login']]);
}
public function index()
{
return $this->response->json(['data' => 'user info']);
}
}
注意：控制器级中间件暂不支持 only/except 参数（Hyperf v3.1 及以前），如需条件控制，建议在中间件内部判断路径或方法。
