前端API请求验证的挑战
在现代Web应用中，前后端分离架构日益普及，前端通过API与后端进行数据交互。为了提供良好的用户体验并减少服务器负载，前端通常需要进行数据验证。然而，这带来了一个常见问题：验证规则的重复定义。
许多开发者会选择在前端使用JavaScript库（如jQuery Validation或Laravel Javascript Validation）来编写一套验证逻辑，同时在后端Laravel中通过Form Request或控制器验证器再编写一套相同的验证逻辑。这种重复不仅增加了开发工作量，还极易导致前后端验证规则不一致，从而引发潜在的数据问题和调试困难。
尤其当API请求不直接来源于HTML表单元素时，传统基于表单的验证库显得力不从心。例如，通过JavaScript动态构建的数据对象、数据表格的批量操作或复杂的模态框交互，其数据可能不与单个表单绑定，导致前端验证逻辑难以统一和实施。在这种情况下，一些开发者可能会考虑使用“隐藏表单”等变通方案，但这无疑增加了不必要的复杂性和维护成本。
引入Laravel Precognition：统一验证的利器
为了优雅地解决前后端验证规则重复和不一致的问题，Laravel 10 引入了 Laravel Precognition。Precognition 允许前端在实际提交数据之前，向后端发送一个“预验证”请求，后端仅执行验证逻辑，并返回验证结果，而不会执行控制器中的业务逻辑。其核心优势在于：
- 规则复用： 无需在前端重新定义验证规则，直接复用后端 Laravel Form Request 或控制器中已有的验证逻辑。
- 实时反馈： 允许前端在用户输入时或提交前即时获取验证反馈，提升用户体验。
- 通用性： 适用于任何类型的API请求，无论是表单提交、动态数据更新还是其他复杂的交互场景。
Laravel Precognition 工作原理
当前端发起一个带有特定 HTTP 头（Precognition: true）的请求时，Laravel 框架会识别这是一个 Precognition 请求。此时，框架会：
- 执行验证： 按照请求对应的 Form Request 或控制器中定义的验证规则对请求数据进行验证。
-
返回结果：
- 如果验证通过，Laravel 会返回一个 204 No Content 响应，表示数据有效。
- 如果验证失败，Laravel 会返回一个 422 Unprocessable Entity 响应，并在响应体中包含详细的验证错误信息。
- 跳过业务逻辑： 无论验证结果如何，控制器中定义的数据处理逻辑（如数据库操作、业务计算等）都不会被执行。
前端接收到这些响应后，可以根据验证结果更新UI，例如显示错误消息或启用提交按钮。
实现步骤与示例
1. 后端准备：定义Form Request
Laravel Precognition 完美兼容 Laravel 现有的 Form Request 验证机制。你只需像往常一样定义你的 Form Request 类即可。
假设我们有一个用于获取医生预约的API请求，其验证规则如下：
<?php
namespace App\Http\Requests\DoctorProfile;
use App\Http\Requests\ApiRequest; // 假设 ApiRequest 继承自 Illuminate\Foundation\Http\FormRequest
class GetAppointments extends ApiRequest
{
/**
* Determine if the user is authorized to make this request.
*/
public function authorize(): bool
{
return true; // 根据实际业务逻辑授权
}
/**
* Get the validation rules that apply to the request.
*
* @return array<string, \Illuminate\Contracts\Validation\ValidationRule|array<mixed>|string>
*/
public function rules(): array
{
return [
'doctor_id' => ['required', 'integer', 'min:0'],
'date' => ['nullable', 'date_format:Y-m-d'], // 日期可以为空，但如果存在必须是 Y-m-d 格式
];
}
}在控制器中，你正常使用这个 Form Request：
<?php
namespace App\Http\Controllers;
use App\Http\Requests\DoctorProfile\GetAppointments;
use Illuminate\Http\JsonResponse;
class AppointmentController extends Controller
{
public function index(GetAppointments $request): JsonResponse
{
// 如果是 Precognition 请求且验证通过，此方法不会被完全执行，
// Laravel 会直接返回 204。
// 如果是常规请求且验证通过，此方法会正常执行。
// 这里可以处理获取预约的业务逻辑
$validatedData = $request->validated();
// 示例：根据验证后的数据查询预约
// $appointments = ...
return response()->json([
'message' => 'Appointments retrieved successfully.',
'data' => $validatedData, // 示例数据
]);
}
}2. 前端集成：发送Precognition请求
Laravel 官方提供了 @laravel-precognition/js 包，它为前端集成 Precognition 提供了便利。
安装依赖：
npm install @laravel-precognition/js axios
JavaScript 示例：
下面的示例展示了如何使用 createPrecognition 方法进行预验证，然后根据验证结果决定是否发送实际的提交请求。
// frontend/src/api.js (或你的组件脚本)
import { createPrecognition } from '@laravel-precognition/js';
import axios from 'axios'; // 假设你已配置好 Axios
// 创建一个 Precognition 实例，传入你的 Axios 实例
const precognition = createPrecognition({
axios,
});
/**
* 执行数据预验证。
* @param {number} doctorId 医生ID
* @param {string} date 预约日期 (Y-m-d 格式)
* @returns {Promise<{isValid: boolean, errors: object}>} 验证结果
*/
async function validateAppointmentData(doctorId, date) {
try {
// precognition.post 方法会自动添加 'Precognition: true' 头
// 后端只会执行验证，如果通过则返回 204 No Content
await precognition.post('/api/appointments', {
doctor_id: doctorId,
date: date,
});
console.log('数据预验证成功！');
return { isValid: true, errors: {} };
} catch (error) {
if (error.response && error.response.status === 422 && error.response.data.errors) {
// 处理验证失败，后端返回 422 状态码和错误信息
console.error('验证错误:', error.response.data.errors);
return { isValid: false, errors: error.response.data.errors };
} else {
// 处理其他意外错误
console.error('预验证过程中发生意外错误:', error);
return { isValid: false, errors: { general: '发生意外错误。' } };
}
}
}
/**
* 实际提交预约数据。
* @param {number} doctorId 医生ID
* @param {string} date 预约日期 (Y-m-d 格式)
* @returns {Promise<{success: boolean, data?: object, errors?: object}>} 提交结果
*/
async function submitAppointmentData(doctorId, date) {
try {
// 这是一个常规的 Axios POST 请求，不带 Precognition 头
// 后端会执行验证，如果通过则执行控制器业务逻辑并返回结果
const response = await axios.post('/api/appointments', {
doctor 
