Attributes 能直接替代 DocBlock 因为它是 PHP 8.0 语言级语法，编译期校验类型与结构，而 DocBlock 只是运行时解析的字符串；主流框架如 Symfony、PHPUnit、Doctrine、Symfony Validator 已提供对应 Attribute 映射。
Attributes 为什么能直接替代 DocBlock
因为 PHP 8.0 的 #[...] 是语言级语法，不是注释；而 DocBlock（/** @Foo */）只是被忽略的字符串，靠第三方库（如 doctrine/annotations）在运行时解析。前者编译期就校验类型、拼写和参数结构，后者直到执行反射时才可能报错，且 IDE 无法可靠跳转或补全。
哪些 DocBlock 注解有对应 Attributes
不是所有都能直接换，但主流框架已对齐：
-
@Route→#[Route]（Symfony、Hyperf、Laravel 10+） -
@Test,@DataProvider,@Covers→#[Test],#[DataProvider],#[Covers]（PHPUnit 10+） -
@ORM\Entity,@ORM\Column→#[Entity],#[Column]（Doctrine 3+，需启用attributes: true配置） -
@Assert\NotBlank→#[Assert\NotBlank]（Symfony Validator 6.2+）
注意：doctrine/annotations v3 开始支持读取 Attributes，但旧版 v2 只认 DocBlock；迁移前确认你用的库版本是否兼容。
手动替换时最容易踩的坑
别只改语法，还得处理语义差异：
立即学习“PHP免费学习笔记（深入）”；
- 参数写法不同：DocBlock 中
@Route("/api", methods={"GET"})对应#[Route(path: "/api", methods: ["GET"])]—— 属性必须用命名参数，不能省略键名 - 数组字面量必须用方括号
[]，不能用花括号{}（methods: ["GET"]✅，methods: {"GET"}❌） - 类名要完整或 use 进来：
#[Assert\NotBlank]要么写全名，要么顶部加use Assert\NotBlank; - 多个同类型属性可重复使用：
#[Middleware(A::class)] #[Middleware(B::class)]合法；但/** @Middleware(A::class) @Middleware(B::class) */在部分解析器里可能只取第一个
用 php-cs-fixer 自动迁移 PHPUnit 注解
如果你的测试代码还在用 @Test、@DataProvider 等，最稳的方式是跑一次 fixer：
php-cs-fixer fix --rules=php_unit_attributes tests/
它会自动把 /** @Test */ 换成 #[Test]，并删掉原注释（除非你显式配置 "keep_annotations": true）。前提是：
- PHP 版本 ≥ 8.0（
php-cs-fixer内部有PHP_VERSION_ID >= 8_00_00校验） - 文件被识别为 PHPUnit 测试类（含
extends TestCase或use TestCase） - 项目已升级到 PHPUnit 10+（老版本不提供
\PHPUnit\Framework\Attributes\*类）
真正麻烦的从来不是语法转换，而是那些混在 DocBlock 里的自定义注解——它们没标准映射，得手动重写成 Attribute 类，再逐个替换调用点。
