PHP Attributes读取类元数据并做参数校验的方案

PHP Attributes适合把“这个字段需要什么规则”写在声明旁边，但它不会自动完成参数校验。可维护的做法是：用自定义 Attribute 保存规则和提示信息，用 ReflectionProperty::getAttributes() 读取元数据，再通过 newInstance() 得到规则对象，最后把失败结果统一收集到字段错误映射中。

官方资料：https://www.php.net/manual/en/language.attributes.php

先把校验规则声明在属性旁边

属性校验的第一步不是扫描整个类，而是先定义一个限制目标为属性的 Attribute。构造函数保存最小必要信息，例如规则名、是否允许空值和提示语；业务代码只负责解释这些字段。

这里的 IS_REPEATABLE 允许同一个属性挂多条规则，但它只改变声明能力，不会自动执行规则。若某字段只能有一条约束，可以去掉该标志，让重复声明在设计阶段就暴露出来。

用 ReflectionProperty 读取并实例化元数据

校验器可以遍历对象的公开属性，再只取 Validate::class。getName() 用来识别 Attribute，getArguments() 适合做通用日志或调试，而真正执行校验时应优先调用 newInstance()，让 PHP 按构造函数还原对象。

function validate(object $input): array
{
    $errors = [];
    $reflection = new ReflectionClass($input);

    foreach ($reflection->getProperties() as $property) {
        // 中文说明：只读取本校验器认识的 Attribute，跳过无关元数据。
        $attributes = $property->getAttributes(Validate::class);
        if ($attributes === []) {
            continue;
        }

        // 中文说明：读取当前字段值；私有属性应改用显式访问策略或 DTO 映射。
        $value = $property->getValue($input);
        foreach ($attributes as $attribute) {
            // 中文说明：newInstance 会按 Attribute 构造函数恢复规则对象。
            $rule = $attribute->newInstance();
            $failed = match ($rule->rule) {
                'required' => $value === '',
                'email' => !filter_var($value, FILTER_VALIDATE_EMAIL),
                default => throw new InvalidArgumentException("未知规则: {$rule->rule}"),
            };
            if ($failed) {
                // 中文说明：同一字段保留多条失败信息，便于接口一次返回完整结果。
                $errors[$property->getName()][] = $rule->message;
            }
        }
    }
    return $errors;
}

规则执行和元数据读取要分开看：ReflectionAttribute 只描述声明，真正的校验结果仍来自你的规则分支。未知规则抛出配置错误更合适；客户端输入不合格则进入字段错误数组，二者不要共用同一个状态码语义。

把字段错误、反射错误和成功结果分层

在控制器中，可以把空数组视为校验通过，把非空数组转换成 422 响应；反射对象构造失败、规则名拼写错误则属于服务端配置问题，应记录日志并返回通用的 500。这样前端不会把“后端规则写错”误显示成用户输入错误。

$errors = validate($payload);
if ($errors !== []) {
    // 中文说明：字段错误面向调用方，保留字段名和可读提示。
    return response_json(['errors' => $errors], 422);
}

// 中文说明：通过校验后才进入业务创建，避免半成品数据继续传播。
return response_json(['data' => $payload], 201);

继承、重复声明与缓存要提前定边界

如果要按父类 Attribute 类型筛选，可以传入 ReflectionAttribute::IS_INSTANCEOF；不传标志时是精确类名匹配。重复 Attribute 则可通过 isRepeated() 识别，业务上通常按声明顺序执行。反射结果可以按类名缓存，但不要把带请求状态的校验结果缓存进元数据缓存。

常见问题

Attributes能替代完整的验证框架吗？它更适合作为声明层。规则数量、嵌套数据、国际化提示和依赖注入变复杂后，应把执行器独立出来，或交给成熟验证组件。

为什么读取到了 Attribute 却没有校验效果？因为声明不会自动触发逻辑。必须遍历反射结果、调用 newInstance()，并在规则执行后处理返回的错误。