PHP ReflectionClass 怎么筛选重复注解：继承、目标类与参数验收

注解扫描器最容易出错的地方，不是把类名读出来，而是把“同一个注解的子类”“重复声明”和“参数还没验证”混成一件事。比如路由注册器只想收集实现了某个接口的 Attribute，却误用了默认名称匹配，最后少了一条路由；或者扫描阶段直接实例化 Attribute，配置写错时异常位置离真正的声明很远。

先把注解扫描的三个判断拆开

一个稳定的扫描流程应该依次回答三个问题：这个声明上有哪些 Attribute？它是不是我要的那一类？它的参数能不能构造成对象。PHP 把这三个阶段拆成了反射对象、名称过滤和实例化 API，正好可以把错误隔离开。

下面的示例定义一个基础契约和两个实现。JsonView 允许重复使用，子类 AdminView 则用来验证接口筛选。

name; }
}

#[Attribute(Attribute::TARGET_CLASS)]
class AdminView extends View {}

#[View('list')]
#[View('export')]
#[AdminView('audit')]
final class OrderController {}

这里的重点是：Attribute 的声明位置和重复规则属于 Attribute 类本身；反射读取时，PHP 先给你 ReflectionAttribute 描述对象，不会因为你调用了 getAttributes() 就立刻验证所有构造参数。

精确名称匹配与接口筛选的差别

最小读取写法很直白：

$reflection = new ReflectionClass(OrderController::class);
$all = $reflection->getAttributes();
$views = $reflection->getAttributes(View::class);
$viewLike = $reflection->getAttributes(View::class, ReflectionAttribute::IS_INSTANCEOF);

foreach ($viewLike as $attribute) {
    echo $attribute->getName(), PHP_EOL;
}

$all 会拿到三条声明。$views 是精确按类名筛选，结果只包含 View；第三种写法才会用类似 instanceof 的关系，把 AdminView 一起收进来。这个 flag 只在传入名称时有意义，不能把它当成“递归扫描父类 Attribute”的开关。

实际项目里更推荐把筛选意图写成一个小函数，调用方一眼就能看出是在找精确类型还是找某个契约的实现：

/** @return list */
function findViewAttributes(ReflectionClass $class): array
{
    return $class->getAttributes(
        View::class,
        ReflectionAttribute::IS_INSTANCEOF
    );
}

重复声明要在两个位置验收

isRepeated() 反映的是同名 Attribute 是否在当前代码元素上重复出现。它适合做诊断信息，例如日志里明确告诉开发者“一个类挂了多个视图定义”。但它不是替代声明规则的许可开关。

如果 View 没有 Attribute::IS_REPEATABLE，重复声明在解析阶段可能仍能被反射看到；真正调用 newInstance() 时，重复性和目标位置等约束才会被验证。因此扫描器不要只判断数组长度：

foreach ($viewLike as $attribute) {
    $message = [
        'name' => $attribute->getName(),
        'repeated' => $attribute->isRepeated(),
        'arguments' => $attribute->getArguments(),
    ];

    var_export($message);
}

如果业务只允许一个定义，应在业务层再加数量检查；如果业务允许多个，就在 Attribute 声明上明确设置可重复标志，并规定同名项的覆盖或合并顺序。

先读参数，再决定何时 newInstance

getArguments() 读取的是源码中传给 Attribute 的位置参数和命名参数。它不会替你运行构造函数，也不会把参数自动转成业务对象。这个特性很适合做“先报告全部问题，再实例化”的扫描器。

foreach (findViewAttributes($reflection) as $attribute) {
    $args = $attribute->getArguments();
    $name = $args['name'] ?? $args[0] ?? null;

    if (!is_string($name) || $name === '') {
        throw new LogicException('View name must be a non-empty string');
    }

    $view = $attribute->newInstance();
    echo (string) $view, PHP_EOL;
}

这里的顺序有两个好处：参数错误在扫描器自己的校验处暴露；只有通过初筛的声明才会创建对象。如果 Attribute 构造器有类型约束、默认值或命名参数，最终仍应把 newInstance() 放在 try/catch 边界内，记录类名和 Attribute 名称后再决定是跳过还是让部署失败。

目标位置不是 getAttributes 的过滤条件

Attribute::TARGET_CLASS、TARGET_METHOD 和 TARGET_PARAMETER 描述允许的使用位置。它们不是 getAttributes() 的第二个参数，也不会改变名称筛选结果。一个 Attribute 写在错误的声明位置时，反射阶段仍可能拿到描述对象，约束通常在实例化阶段才真正暴露。

因此，扫描类、方法和参数时要分别建立入口：

$classAttributes = $reflection->getAttributes(View::class);
$method = $reflection->getMethod('index');
$methodAttributes = $method->getAttributes(View::class);
$parameterAttributes = $method->getParameters()[0]->getAttributes(View::class);

不要从类级反射对象推断方法级结果，也不要因为类级筛选成功就假设参数级 Attribute 同样合法。每个反射元素都应使用自己的 getAttributes()，并在错误信息里带上声明位置。

一个可落地的扫描验收清单

• 要全部声明：调用无参数的 getAttributes()，不要先猜具体类名。
• 要精确类名：传名称但保持 flags 为默认值。
• 要父类或接口契约：传名称并显式使用 ReflectionAttribute::IS_INSTANCEOF。
• 要检查重复：遍历每个 ReflectionAttribute 并读取 isRepeated()，同时检查业务数量规则。
• 要诊断参数：先用 getArguments() 记录原始参数，再在可控边界内调用 newInstance()。
• 要验证目标位置：分别扫描类、方法、属性、参数或常量的反射对象。

常见问题

getAttributes(View::class) 会自动包含 AdminView 吗？

不会。默认是精确名称匹配；只有传入 ReflectionAttribute::IS_INSTANCEOF 才会把符合继承或接口关系的 Attribute 纳入结果。

isRepeated() 能判断 Attribute 是否允许重复吗？

不能。它描述当前声明是否重复出现；是否允许重复由 Attribute 类声明中的 Attribute::IS_REPEATABLE 决定。

什么时候应该调用 newInstance()？

完成名称、数量、目标位置和参数初筛后再调用。这样可以把缺参、类型错误和目标不匹配集中到明确的扫描阶段。

getArguments() 返回的是实例属性吗？

不是，它返回声明时传入的参数数组。实例属性值要等 newInstance() 成功后才能读取。

把反射结果变成可复查的契约

ReflectionClass 的价值不在于“能读到 Attribute”，而在于把筛选、诊断和实例化分成可验证的步骤。先确定名称匹配语义，再处理重复声明，最后构造实例，扫描器才能在扩展到方法和参数时保持一致。把每次扫描的类名、Attribute 名、参数和失败边界写进测试输出，后续升级 PHP 或增加注解子类时，问题会比直接依赖字符串比较更早暴露。