验证与 Action

Pin 的验证能力分为两类：普通 Laravel Validation Rule 增强，以及 Action 中的 payload、validation、fake data 和 queryable 能力。

Validation Rules

内置规则：

规则	说明
Phone	中国大陆手机号校验
Unique	基于 Eloquent Model 的唯一性校验
Enum	BackedEnum 值校验

示例：

use Pin\Validation\Rules\Enum;
use Pin\Validation\Rules\Phone;
use Pin\Validation\Rules\Unique;

public function rules(): array
{
    return [
        'phone' => ['required', new Phone()],
        'email' => ['required', new Unique(User::class)],
        'status' => ['required', new Enum(UserStatus::class)],
    ];
}

更新时忽略当前记录：

new Unique(User::class)
    ->ignore($this->route('user'))
    ->where('tenant_id', tenant()->id)
    ->message('邮箱已被使用');

查询规则快捷构建

Pin\Validation\Q 是查询规则构建器，用于把 validation rules 同时作为查询 DSL：

use Pin\Validation\Q;

public function rules(): array
{
    return [
        'keyword' => Q::ns('id|username'),
        'status' => Q::inN(),
        'created_at' => Q::range(),
    ];
}

Action 可以通过 queryable() 从规则和 payload 中构建 Queryable。

Action 基类

Pin\Actions\Action 组合了：

• HasPayload：保存和读取输入数据。
• HasValidation：执行规则验证。
• HasContext：共享上下文，例如路由参数。
• HasModel：根据模块约定绑定模型。
• HasFake：根据验证规则生成 fake 数据。

示例：

use Pin\Actions\Action;
use Pin\Validation\Q;

class ListUsersAction extends Action
{
    public function rules(): array
    {
        return [
            'keyword' => Q::ns('id|username'),
            'status' => Q::inN(),
        ];
    }

    public function handle()
    {
        return $this->modelClass::query()
            ->q($this->queryable())
            ->pagination();
    }
}

容器解析后的注入

ActionServiceProvider 会在容器解析 Action 后自动：

1. 将 $request->all() 注入 payload。
2. 将路由参数注入 context。
3. 写入 __route_name context。
4. 调用 boot()。
5. 当 _fake=1 且配置允许时抛出 fake response。

Payload

$action->payload(['name' => 'Pin']);
$action->payload('profile.email', 'pin@example.com');

$email = $action->payload('profile.email');
$all = $action->payload();

验证流程

$data = $action->validated();

验证流程会依次调用：

1. authorize()，不存在时默认通过。
2. rules() 或 withRules() 提供的规则。
3. messages() 和 attributes()，如果类中存在。
4. passedValidation() 写入验证后的数据。

Fake Response

Action 可以根据规则生成 fake 数据：

$data = ListUsersAction::fake([
    'status' => 1,
]);

当 config('actions.fake_response_enabled') 为真，并且请求包含 _fake=1，Action 被解析时会直接返回 fake response。默认非生产环境启用。