Hyperf注解不继承trait中的注解，因扫描器仅解析类声明层面注解，不递归trait；必须在子类显式重复标注#[Controller]、#[GetMapping]等，或改用抽象基类替代trait以实现注解继承。
Trait里的注解不会自动继承到使用它的类上
Hyperf 的注解扫描器（AnnotationScanner）在解析类时，只读取当前类声明层面的注解，不递归解析 trait 中的注解。哪怕你在 trait 里写了 #[Controller] 或 #[Inject]，只要子类没显式标注，扫描器就当它不存在——不是 bug，是设计如此。
常见现象：一个 BaseControllerTrait 里定义了 #[GetMapping("/health")]，混入 UserController 后访问 /health 404；或者 trait 里写了 #[Inject] 属性，子类实例化后该属性为 null。
- trait 是 PHP 语言级代码复用机制，Hyperf 注解系统不感知其语义，也不会“展开”trait 再扫描
- 扫描器只认
ReflectionClass::getAttributes()返回的内容，而 trait 的属性注解不会出现在子类反射结果中 - 即使 trait 被
use进类，它本身也不是一个可被扫描的“类”，scan.paths配置对 trait 文件无效
必须在子类中手动补全注解，不能依赖 trait 传递
解决办法只有一条：把本该“共享”的注解，原样复制到每个使用该 trait 的类或方法上。没有捷径，也不能靠配置绕过。
例如，你有一个带健康检查方法的 trait：
trait HealthCheckTrait
{
#[GetMapping("/health")]
public function health(): array
{
return ['status' => 'ok'];
}
}
那么在控制器中必须这样写：
#[Controller]
class UserController extends AbstractController
{
use HealthCheckTrait;
// ✅ 必须显式加注解，trait 里的不算
#[GetMapping("/health")]
public function health(): array
{
return parent::health();
}
}
- 方法级注解（如
#[GetMapping]）必须贴在子类方法上，哪怕只是调用parent::xxx() - 类级注解（如
#[Controller]、#[Aspect]）也必须写在子类声明处，trait 里写无效 - 属性注入同理：
use SomeInjectTrait;不会触发#[Inject]扫描，子类仍需单独声明属性并加注解
为什么不能用 AOP 或自定义扫描器自动补注解
有人尝试在 AnnotationCollector 或 RegisterInjectPropertyHandler 里 hook trait 的反射信息，但这条路走不通。
根本限制在于：PHP 的 ReflectionClass::getTraits() 只返回 trait 类名，不返回 trait 中的方法/属性注解；而 ReflectionMethod::getAttributes() 对 trait 方法调用会抛出 ReflectionException —— trait 方法在反射层面没有独立的“拥有者上下文”。
- Hyperf 启动阶段的注解收集发生在类加载之后、容器注册之前，此时 trait 尚未绑定到具体类实例
- 即便强行解析 trait 文件，也无法安全映射到子类方法签名（重命名、参数变更、可见性调整都会断链）
- 社区已有 PR 尝试支持 trait 注解继承，但因破坏性变更和兼容风险，Hyperf 官方明确拒绝合入
替代方案：用抽象基类代替 trait 来承载公共注解
如果大量类需要统一路由或注入逻辑，trait 不是唯一选择。换成抽象类，注解就能自然继承：
#[Controller]
abstract class HealthCheckController extends AbstractController
{
#[GetMapping("/health")]
public function health(): array
{
return ['status' => 'ok'];
}
}
// 子类直接继承，注解生效
class UserController extends HealthCheckController
{
}
- 抽象类会被
AnnotationScanner正常扫描，其注解可被子类继承（前提是子类也带#[Controller]） - 注意：抽象类自身不会被容器实例化，所以不用担心重复注册
- 若必须保留 trait 结构（比如要混入多个非继承关系的类），那就老老实实手动补注解——这是目前最稳、最易排查的方式
别指望运行时动态修补，Hyperf 的注解体系是编译期静态收集的。漏掉的注解，启动那一刻就永远失效了。
