Hyperf 注解是基于 PHPDoc 的元编程机制，需配合 AOP 与扫描生效；核心注解包括 @Controller、@GetMapping、@Inject 等；自定义注解需定义类、编写处理器并注册；调试时需检查扫描路径、PHPDoc 格式及代理类生成。
Hyperf 的注解（Annotation）是其核心特性之一，本质是通过 PHPDoc 注释 + 自定义解析器实现的元编程机制，用于声明式地配置路由、注入依赖、定义中间件、管理生命周期等。它不改变 PHP 语法，但极大提升了开发效率和代码可读性。
注解必须配合 AOP 和注解扫描才能生效
Hyperf 默认启用注解驱动，但前提是：
- 项目已正确安装
hyperf/annotation组件（通常随hyperf/framework自动引入） -
config/autoload/annotations.php中配置了需要扫描的命名空间路径（如App\Controller、App\Service） - 启动时执行了注解扫描（Hyperf 在
Di\ClassLoader中自动完成，无需手动调用） - 类文件需使用
/** */标准 PHPDoc，且注解类已正确导入（如use Hyperf\HttpServer\Annotation\GetMapping;）
常用核心注解及典型用法
以下是最常被使用的几类注解，直接对应关键开发场景：
-
@Controller：标记控制器类，自动注册为容器对象，并启用路由扫描。可选参数
prefix设置统一前缀，例如：#[Controller(prefix: "/api/user")] -
@GetMapping / @PostMapping / @RequestMapping：绑定 HTTP 方法与路径，支持路径变量（
{id}）和正则约束（{id:\d+}），例如：#[GetMapping("/info/{id:\d+}")] -
@Inject：属性注入依赖，替代
$container->get()或构造函数注入。支持类型提示自动推导，例如：#[Inject] private UserService $userService; -
@Middleware：为方法或类添加中间件，支持全局、分组、单接口粒度控制，例如：
#[Middleware(AuthMiddleware::class)] -
@Value：从配置中心（
config/autoload/）注入值，支持点号路径，例如：#[Value("app.name")] private string $appName;
自定义注解要三步走
当内置注解不够用时，可快速扩展自己的注解：
-
定义注解类：创建在
App\Annotation下，继承Hyperf\Di\Annotation\AbstractAnnotation，设置$name属性作为标签名 -
编写处理器（Aspect）：实现
Hyperf\Di\Aop\AroundInterface或Hyperf\Di\Aop\PointExecutionInterface，在process()中读取注解元数据并执行逻辑 -
注册到容器：在
config/autoload/annotations.php的scan→paths中加入自定义注解路径，并在aspects数组中注册对应的 Aspect 类
调试注解问题的实用技巧
注解不生效？优先检查这几处：
- 运行
php bin/hyperf.php di:scan手动触发注解扫描（开发环境建议开启scan.enable为true） - 确认注解写在类/方法/属性的 上方紧邻位置，且 PHPDoc 格式完整（
/** ... */，不能是//或/* ... */） - 查看
runtime/container/proxy/下是否生成了代理类；若无，说明扫描未覆盖该文件 - 使用
php bin/hyperf.php annotation:debug查看当前已加载的注解及其处理器绑定状态
