# 3.4 FormRequest 验证器

:::tip 概述
参数格式验证由 **FormRequest** 完成（Laravel 标准机制）：控制器方法类型注入请求类，未通过校验时框架自动返回统一 JSON 错误响应。所有请求类继承本项目的 `BaseRequest`，子类只需声明 `rules()` 与 `messages()`。
:::

## 请求类文件位置

```text
app/Http/Requests/ExampleRequest.php
```

## 完整代码（来自项目实际代码）

```php
<?php

namespace App\Http\Requests;

/**
 * 案例表单请求
 *
 * 负责案例演示新增/修改接口的参数校验。
 *
 * 说明：
 * - 继承 BaseRequest，基础校验能力（失败响应统一处理）由基类提供。
 * - 本类只声明案例特有的字段规则与自定义错误消息。
 * - 新增与修改共用本请求类，修改时由基类或控制器负责校验 id。
 * - 前端传参使用 camelCase，数据库字段为 snake_case；
 * - type 类型：1=类型1，2=类型2，3=类型3，4=类型4，
 *   与 Example 模型的约定一致。
 * - status 状态：1=在用，2=停用。
 */
class ExampleRequest extends BaseRequest
{
    /**
     * 校验规则
     *
     * @return array<string, string> 字段规则
     */
    public function rules(): array
    {
        return [
            'name' => 'required|string|max:255',       // 案例名称：必填，最长 255
            'avatar' => 'nullable|string|max:255',     // 头像/图片地址：可空，最长 255
            'type' => 'nullable|integer|in:1,2,3,4',   // 类型：1=类型1，2=类型2，3=类型3，4=类型4
            'status' => 'nullable|integer|in:1,2',     // 状态：1=在用，2=停用
            'sort' => 'nullable|integer',              // 排序值：可空，整数
        ];
    }

    /**
     * 自定义错误消息
     *
     * 为需要友好提示的规则提供中文消息，覆盖框架默认英文提示。
     *
     * @return array<string, string> 字段规则 => 错误消息
     */
    public function messages(): array
    {
        return [
            'name.required' => '案例名称不能为空',
            'name.max' => '案例名称不能超过 255 个字符',
            'avatar.max' => '图片地址不能超过 255 个字符',
            'type.in' => '案例类型不合法，允许：1-类型1 2-类型2 3-类型3 4-类型4',
            'status.in' => '状态值不合法，允许：1-在用 2-停用',
            'sort.integer' => '排序值格式不正确',
        ];
    }
}
```

## 控制器中的使用

```php
// 类型注入：请求到达方法前自动完成校验
public function add(ExampleRequest $request): JsonResponse
{
    // validated() → 已校验数据，键名转换由 Service 写入入口统一完成
    return $this->_add($this->exampleService, $request->validated());
}
```

:::tip validated() 是白名单
`validated()` 只返回 `rules()` 中声明过的键，未声明的字段在进入控制器前即被丢弃。业务需要传递给 Service 的字段（如修改接口的 `id`、用户表单的 `city` / `roles`）都应在规则中声明，否则即使前端传了也到不了 Service。
:::

## BaseRequest 基类提供的能力

`app/Http/Requests/BaseRequest.php`：

| 能力 | 说明 |
|------|------|
| `authorize()` 统一返回 true | 鉴权由路由中间件与 `#[Permission]` 注解负责，请求类不参与授权 |
| `failedValidation()` 统一处理 | 校验失败返回固定 JSON：`{"code":1,"ok":false,"msg":"参数验证失败","data":{字段=>错误数组}}`（code=1 与 `Controller::fail()` 约定一致） |

:::warning 两条校验失败路径
- **FormRequest 注入**（本章方式）→ 失败响应 `code=1`；
- **代码内手动** `Validator::validate()` 抛出的 `ValidationException` → 由全局 Handler 渲染为 `code=422`。

前端两种都应兼容（以 `code !== 0` 判失败）。详见 [5.16 统一响应与异常抛出](/zh/core/exception.html)。
:::

## 常用验证规则

| 规则 | 说明 | 示例 |
|------|------|------|
| `required` | 必填 | `'name' => 'required'` |
| `string` | 字符串 | `'name' => 'string'` |
| `max:n` | 最大长度 | `'title' => 'max:200'` |
| `min:n` | 最小长度 | `'password' => 'min:6'` |
| `integer` | 整数 | `'sort' => 'integer'` |
| `in:a,b,c` | 枚举值 | `'status' => 'in:1,2'` |
| `nullable` | 可空（不传则跳过其余规则） | `'avatar' => 'nullable\|string'` |
| `email` | 邮箱格式 | `'email' => 'email'` |
| `date` | 日期格式 | `'start_time' => 'date'` |
| `regex:/.../` | 正则 | `'code' => 'regex:/^[A-Za-z]+$/'` |

## 分层职责：格式 vs 业务

| 层 | 职责 | 示例 |
|----|------|------|
| **FormRequest（本章）** | 参数**格式**：必填、类型、长度、枚举 | `name` 必填、`type` 只能 1-4 |
| **Service 层** | 参数**业务规则**：唯一性、状态依赖、权限 | `name` 不能与已有记录重复 |

:::tip 唯一性为什么不放 FormRequest？
`uniqueFields` 校验在 Service 层完成（`HasUniqueCheck` Trait），因为软删除场景下数据库唯一索引会误伤（`is_delete=1` 的旧记录仍占索引），且需要排除自身（update 场景）。见 [3.5 Service 层开发](/zh/guide/logic.html)。
:::

## 场景拆分（新增 vs 修改字段差异大时）

FormRequest 可按方法区分规则：

```php
class UserRequest extends BaseRequest
{
    public function rules(): array
    {
        // 通过 $this->isMethod('post') 或自定义场景标识区分
        $rules = [
            'realname' => 'required|string|max:50',
            'mobile' => 'nullable|max:20',
        ];

        if ($this->isMethod('post')) {
            // 新增时才要求用户名
            $rules['username'] = 'required|string|min:3|max:50';
        }

        return $rules;
    }
}
```