Laravel 中间件与自定义请求类（Request）的正确配合使用方法

laravel 中间件的 `handle` 方法必须接收 `\illuminate\http\request` 类型参数，而自定义请求类（如 `vacancylistrequest`）仅能在控制器方法中通过依赖注入自动验证和绑定，不可直接用于中间件类型提示。

在 Laravel 中，中间件（Middleware）是 HTTP 请求处理管道中的一个环节，其核心契约要求 handle 方法的第一个参数必须是 \Illuminate\Http\Request 的实例——这是 Laravel 框架底层调度器（Router/Dispatcher）严格约定的类型约束。因此，以下写法是非法且会触发致命错误的：

// ❌ 错误：中间件 handle 方法不能声明为自定义 Request 类型
public function handle(VacancyListRequest $request, Closure $next)
{
    // ...
}

该写法会导致 PHP 类型错误：Argument #1 ($request) must be of type App\Http\Requests\Vacancy\VacancyListRequest, Illuminate\Http\Request given，因为框架传入的是原始 \Illuminate\Http\Request 实例，而非经过验证/转换后的 VacancyListRequest。

✅ 正确做法是：中间件保持标准类型签名，控制器负责启用自定义请求验证。

✅ 步骤一：修正中间件签名

中间件应始终接收原生 Request，并在内部按需操作请求数据（如解析、格式化、预处理），但不改变其类型：

Kubit.ai

一个AI驱动的产品分析平台，为产品和数据团队构建

下载

analyzeQuery($request);
        $request = $this->formatValues($request);
        $request = $this->prepareParams($request);

        return $next($request); // 仍传递 Illuminate\Http\Request 实例
    }

    protected function analyzeQuery(Request $request): Request { /* ... */ }
    protected function formatValues(Request $request): Request { /* ... */ }
    protected function prepareParams(Request $request): Request { /* ... */ }
}

⚠️ 注意：$request 是不可变对象（immutable by convention），虽然 Laravel 允许你返回新 Request 实例（如通过 withQuery() 或 merge()），但更推荐使用 request()->merge([...]) 或在控制器中统一处理，避免中间件过度侵入请求生命周期。

✅ 步骤二：在控制器中使用自定义 Request 类型

VacancyListRequest 的真正价值在于自动授权 + 验证 + 依赖注入，它应在控制器方法中声明，由 Laravel 自动实例化并执行 authorize() 和 rules()：

validated() 返回安全过滤后的数据
        $data = $request->validated();

        // 后续业务逻辑...
        return response()->json(['vacancies' => [...]]);
    }
}

同时确保 VacancyListRequest 正确定义了规则与可选授权逻辑：

check()
    }

    public function rules(): array
    {
        return [
            'page' => ['sometimes', 'integer', 'min:1'],
            'per_page' => ['sometimes', 'integer', 'between:1,100'],
            'category' => ['nullable', 'string', 'max:50'],
            'q' => ['nullable', 'string', 'max:255'],
        ];
    }
}

? 补充说明：为什么中间件不能用自定义 Request？

• Laravel 的中间件注册与调用由 Pipeline 类统一管理，所有中间件 handle() 方法在运行时均由 Router 以统一签名 function (Request $request, Closure $next) 调用；
• 自定义 FormRequest 是控制器层的服务容器绑定+验证代理机制，它依赖于 Laravel 的 RouteDependencyResolver 在控制器解析阶段才被实例化并执行验证；
• 尝试在中间件中强制类型提示自定义 Request，会破坏框架的类型安全契约，导致运行时类型不匹配。

✅ 最佳实践总结

通过明确职责边界——中间件专注“流程控制”，控制器请求类专注“输入契约”——你能构建出更健壮、可维护的 Laravel 应用架构。