PHP Attributes是PHP 8.0+原生注解语法，非字符串注释，需用反射API读取；PHP 7.x或需兼容旧版时须用Doctrine等库解析DocBlock注解，二者不互通。
#[Attribute] 是 PHP 8.0+ 的真注解语法，不是注释；如果你在 PHP 7.x 或想兼容旧版本，那所谓“注解”其实是 @Route 这类 DocBlock 字符串，得靠 doctrine/annotations 解析——两者不互通，选错就白写。
怎么判断该用 Attributes 还是 Doctrine 注解
看 PHP 版本和运行时需求：
• PHP doctrine/annotations + @Route 这种 DocBlock 形式
• PHP ≥ 8.0 且项目可控 → 优先用原生 #[Route]，反射快、类型安全、IDE 支持好
• PHP ≥ 8.0 但要兼容老框架（如 Symfony 5.4）或需动态注册注解 → 得同时支持两种，doctrine/annotations v3 能识别 #[...]，但需手动启用 Attributes 支持
• 框架已升级到 Symfony 6+/Laravel 10+ → 原生 Attributes 是默认路径，DocBlock 注解逐步废弃
定义自定义注解类的常见错误
写一个 #[Route] 类，最容易卡在三处：
• 忘加 #[Attribute] 声明，或漏写 use Attribute;，导致反射时 getAttributes() 返回空数组
• 作用域设错：比如把 #[Attribute(Attribute::TARGET_METHOD)] 用在类上，PHP 编译期就报错
• 构造函数参数没标注类型或用了可变参数（...$args），PHP 8.1+ 会拒绝实例化，应改用命名参数语法：public function __construct(public string $path = '/', public array $methods = [])
读取注解时反射调用必须注意的点
无论用原生还是 Doctrine，反射读取都容易踩坑：
• 原生 ReflectionMethod::getAttributes() 返回的是 ReflectionAttribute 对象，要调用 newInstance() 才能得到你的注解实例，直接访问属性会报错
• Doctrine 的 $reader->getMethodAnnotations($method) 返回的是对象数组，但必须提前注册自动加载：AnnotationRegistry::registerLoader('class_exists')，否则返回空
• 缓存没开：Doctrine 默认不缓存解析结果，高频反射下性能断崖式下跌，务必加 $reader->setCache($cache)（推荐 ArrayCache 或 PhpFilesCache）
• 注解类没加 @Annotation DocBlock（Doctrine 场景）：即使类存在，也会被跳过，必须补上
数组参数和嵌套结构怎么传
原生 Attributes 支持两种传参方式，但行为不同：
• 位置参数：#[Route('/api', ['GET', 'POST'])] → 构造函数按顺序接收
• 命名参数：#[Route(path: '/api', methods: ['GET', 'POST'])] → 更清晰，PHP 8.0+ 支持，推荐用
• 数组值里不能含变量或表达式，只能是字面量：如 #[Config(host: $_ENV['DB_HOST'])] 会编译失败
• 多维数组支持有限：Doctrine 允许 @Route(methods={"GET"}, options={"cache": true})，原生 Attributes 不支持键名带引号的嵌套，得拆成独立属性或用 stdClass
立即学习“PHP免费学习笔记（深入）”；
最常被忽略的是：原生 Attributes 在 CLI 环境下反射正常，但在某些 SAPI（如 Apache mod_php）中若 opcache 启用且未预热，getAttributes() 可能返回空——不是代码问题，是 opcache 缓存了未带注解元数据的字节码。上线前务必用 opcache_reset() 或重启 Web 服务验证。
