hyperf中trait内注解不生效是因扫描器仅解析类声明注解且php反射不递归trait，必须在子类显式重复标注#[controller]、#[getmapping]等，或改用抽象基类替代trait。
Hyperf 中自定义注解写在 Trait 里，子类 use 后完全不生效——这不是 Bug，是框架扫描机制和 PHP 语言特性的双重限制，必须手动补全注解，没有自动继承路径。
Trait 中的注解不会被 AnnotationScanner 读取
Hyperf 的 AnnotationScanner 只解析类声明层面的注解，调用的是 ReflectionClass::getAttributes()。而 PHP 的反射系统对 trait 的处理是隔离的：ReflectionClass::getTraits() 只返回 trait 类名，不提供其内部方法或属性的注解信息。
- 你在
HealthCheckTrait里写了#[GetMapping("/health")]，UserControlleruse它后，UserController::class的反射结果里根本看不到这个注解 -
scan.paths配置对 trait 文件无效——即使你把 trait 所在目录加进扫描路径，扫描器也不会“展开” trait 去解析其中的注解 - trait 是编译期代码复用机制，不是运行时可被独立注册的容器目标，Hyperf 的 DI 和 AOP 都不感知它
为什么“重新扫描 Trait 引用类”也解决不了问题
所谓“让子类被重新扫描”，前提是子类本身得有注解；但问题根源在于：trait 里的注解压根不会进入子类的反射元数据，扫描器连看都看不到，自然谈不上“重新”或“再次”识别。
Hyperf 3.1.66
下载
本页面提供企业级 PHP 协程框架 Hyperf 3.1.66 版本的官方源码下载与完整更新日志。重点解析 v3.1.66 版本中新增的 gRPC 多客户端负载均衡支持、Pool 连接池全量刷新、Guzzle 持久化 Cookie 以及数据库 JSON 包含键查询等核心优化特性。
- 执行
php bin/hyperf.php di:init-proxy或清空runtime/container/，只会重新扫描UserController自身声明的注解，不会触发对 trait 内容的二次挖掘 - 哪怕你在 trait 文件里给方法加了
#[Inject]，只要UserController没在对应方法上显式标注，该属性注入就为null - 试图在
RegisterInjectPropertyHandler或AnnotationCollector中 hook trait 反射，会失败——因为 PHP 不暴露 trait 方法的ReflectionAttribute实例
唯一可靠做法：在子类中显式重复标注
别试图绕过，直接在使用 trait 的类或方法上，把注解原样写一遍。这是 Hyperf 设计决定下的事实标准，不是权宜之计。
- 类级注解（如
#[Controller]、#[Aspect]）必须写在子类class声明前，trait 里写无效 - 方法级注解（如
#[GetMapping]、#[PostMapping]）必须贴在子类方法上，哪怕只是return parent::xxx(); - 属性注入同理：
use SomeInjectTrait;不会触发#[Inject]，子类仍需声明#[Inject] public SomeService $service; - 如果多个控制器都要混入同一套注解逻辑，优先考虑抽象基类替代 trait，基类上的注解可被子类继承（因
ReflectionClass会包含父类注解）
最易被忽略的一点：很多人以为“只要 trait 被 use 进来，它的语义就合并进了当前类”，但在注解层面，Hyperf 和 PHP 反射根本不这么认为——它只认你眼睛能看到的、写在当前作用域里的 #[...]。
