PHP无原生运行时注解，需通过DocBlock注释+Doctrine Annotations等库解析实现；DocBlock须以/*开头、/结尾、紧贴声明上方；推荐doctrine/annotations用于运行时，phpdocumentor/reflection-docblock用于静态分析；PHP 8+支持原生Attributes但与DocBlock不兼容。
PHP 本身不原生支持运行时注解（如 Java 的 @Override 或 Python 的装饰器语法），所谓“PHP 注解”实际是通过 DocBlock 注释 + 第三方库解析实现的伪注解，本质是字符串解析，不是语言特性。
DocBlock 注释怎么写才被注解库识别
只有以 /** 开头、*/ 结尾、且每行以 * 开头的块注释，才被视为有效 DocBlock。关键点：
- 必须紧贴在类、方法、属性或函数声明的正上方，中间不能有空行
- 注解标签必须以
@开头，后接标识符（如@Route、@ORM\Entity），后面可跟空格、字符串、括号参数 - 参数若含空格或特殊字符，需用双引号包裹，例如：
@Route("/api/user", methods={"GET"}) - 不区分大小写（但惯例全大写），
@route和@Route在大多数解析器中等效
主流注解解析库选哪个：Doctrine Annotations vs phpDocumentor
doctrine/annotations 是当前最常用、生态最成熟的运行时注解解析器；phpdocumentor/reflection-docblock 更侧重静态分析（如 IDE 提示、生成文档），不提供运行时反射能力。
- 需要在运行时读取注解（比如路由分发、实体映射），选
doctrine/annotations - 只需要生成 API 文档或做静态类型检查，
phpdocumentor/reflection-docblock足够轻量 -
doctrine/annotations默认启用缓存（建议配AnnotationReader::setCache()），否则每次反射都重新解析，性能损耗明显 - 注意 PHP 版本兼容性：Doctrine Annotations v2 要求 PHP >= 7.4，v3 已转向 PHP 8.1+ 并支持 Attributes（真注解）
用 Doctrine Annotations 读取类方法上的 @Route
假设你有一个控制器方法想通过注解定义路由：
立即学习“PHP免费学习笔记（深入）”；
/**
* @Route("/users", methods={"GET"})
*/
public function listUsers(): array { ... }
对应解析代码如下：
- 先用
new \Doctrine\Common\Annotations\AnnotationReader()实例化读取器 - 用
$reader->getMethodAnnotations($reflectionMethod)获取全部注解对象数组 - 遍历结果，用
instanceof判断是否为自定义注解类（如App\Annotation\Route），不能直接比对字符串名 - 确保已调用
AnnotationRegistry::registerLoader('class_exists')，否则自定义注解类无法自动加载 - 注解类本身需用
@Annotation和@Target("METHOD")等声明元信息，否则会被忽略
PHP 8.0+ 可用 Attributes 替代 DocBlock，但别混用
PHP 8 引入了原生 #[Attribute] 语法，这才是真正的注解（编译期保留、类型安全、IDE 可跳转）。但它和 DocBlock 注解完全不兼容。
- 旧项目迁移到 Attributes 需重写所有注解类，并改写使用方式：
#[Route("/users")]≠@Route("/users") - Doctrine Annotations v3 支持 Attributes，但默认不启用；需手动调用
$reader->enablePhp8Attributes() - 同时存在 DocBlock 和 Attributes 时，Doctrine 默认只读 Attributes（除非显式禁用）
- Attributes 无法表达多行结构化数据（如 YAML 风格嵌套），复杂元数据仍建议用配置文件而非注解
注解不是银弹——它把配置逻辑耦合进代码，调试困难、IDE 支持参差、静态分析受限。真正该用注解的地方很少，比如框架内部的轻量元数据标记；业务逻辑配置尽量走 YAML/PHP 数组。
