路由中间件必须在routes.php中通过middleware选项绑定，不支持用注解覆盖；addGroup定义的中间件默认继承给子路由；混用时执行顺序取决于注册顺序而非类型层级。
路由中间件绑定必须在 routes.php 里用 middleware 选项
Hyperf 不支持在控制器或方法上通过注解“覆盖”路由级中间件的绑定逻辑——注解只管控制器/方法自身，而路由中间件是请求匹配阶段就确定的优先级更高的环节。你写在 config/routes.php 中的 middleware 数组，会直接参与中间件链构建，且不被全局中间件自动继承。
常见错误是把中间件类名写成字符串而非数组，或误塞进其他 key（比如 middlewa 拼错）：
-
Router::get('/user', [UserController::class, 'info'], ['middleware' => [AuthMiddleware::class]])✅ 正确 -
Router::get('/user', [UserController::class, 'info'], ['middleware' => AuthMiddleware::class])❌ 少了外层数组，Hyperf 会静默忽略 -
Router::get('/user', [UserController::class, 'info'], ['middlewa' => [AuthMiddleware::class]])❌ 键名错误，完全不生效
addGroup 的中间件绑定会透传给子路由
用 addGroup 定义前缀路由时，中间件不是“可选附加”，而是默认向下继承的。如果你在 group 外层指定了 middleware，所有内部 get/post 都会自动带上，除非显式用空数组覆盖。
示例：
Router::addGroup('/api/v1', function () {
Router::get('/users', [UserController::class, 'list']);
Router::post('/users', [UserController::class, 'create']);
}, ['middleware' => [JwtAuthMiddleware::class, CorsMiddleware::class]]);
上面两个路由都会执行 JwtAuthMiddleware 和 CorsMiddleware；若想让 /users 创建接口跳过鉴权，得单独再写一行并覆盖：
Router::post('/api/v1/users', [UserController::class, 'create'], ['middleware' => []]);
路由中间件和注解中间件混用时，执行顺序由注册位置决定
Hyperf 最终把所有中间件合并成一条链，但不会按“类型”分层排序——它只看注册顺序和优先级值。同一中间件类如果既在 routes.php 里绑了，又在控制器上加了 #[Middleware]，以最后一次注册为准（不是“路由 > 注解”这种固定规则）。
容易踩的坑：
- 你在
routes.php给/admin/*绑了AdminRoleMiddleware，又在某个 AdminController 上写了#[Middleware(AdminRoleMiddleware::class)]→ 后者会覆盖前者，可能漏掉部分路由 - 多个中间件共用一个类但没传
$priority，它们的执行顺序取决于在配置中出现的先后，而不是你写的先后 - 注解中间件的
$priority只对同一批注解有效；它不能把一个路由级中间件“插队”到两个注解中间件之间
中间件未生效？先检查 Server::SERVER_HTTP 是否匹配
Hyperf 支持多 server 类型（http、tcp、websocket），而路由中间件只对 http server 生效。如果你改过 config/autoload/servers.php 里的 server 名称（比如改成 'name' => 'web'），那 config/autoload/middlewares.php 里 'http' => [] 这个键就失效了——路由中间件也一样，Router::get 默认只作用于 http server。
验证方式：打印 Router::getRouter()->getRouteCollector()->getData() 看是否包含你定义的中间件数组；更直接的是在中间件 process 开头加 var_dump('hit')，发请求看有没有输出。
真正麻烦的是跨 server 场景下复用中间件逻辑——比如你有 http 和 grpc 两个入口，不能靠路由绑定统一管理，得抽离成通用服务再手动调用。
