需启用注解扫描机制：一、确认安装hyperf/http-server和hyperf/annotation组件，并在annotations.php中启用scan=>true及配置控制器路径；二、控制器类添加@controller注解并可设uri前缀；三、方法上使用@getmapping等注解绑定http方法与路径；四、通过类型提示或@query等注解注入请求参数；五、执行route:list命令验证路由是否成功注册。
如果您在Hyperf框架中希望使用注解方式定义HTTP路由，而非传统配置文件或手动注册方式，则需启用并正确配置注解扫描机制。以下是实现注解路由定义的具体步骤：
一、启用注解扫描功能
Hyperf默认不自动扫描控制器中的路由注解，必须在配置中显式启用注解扫描器，并确保相关组件已安装。该步骤是注解路由生效的前提条件。
1、确认项目已安装 hyperf/http-server 和 hyperf/annotation 组件。
2、打开 config/autoload/annotations.php 文件，确保 'scan' => true 已启用。
3、在 scan 配置项中，将控制器所在目录加入 'paths' 数组，例如：app/Controller。
二、在控制器类中使用 @Controller 注解
@Controller 注解用于声明一个类为HTTP控制器，并可指定基础URI前缀，所有方法级路由将在此前缀下注册。
1、在控制器类顶部添加 @Controller 注解。
2、可选地传入路径参数，例如 @Controller("/api") 表示该控制器下所有方法路由自动附加 /api 前缀。
3、确保控制器类继承自 Hyperf\HttpServer\Contract\ControllerInterface 或直接使用 @AutoController 简化声明（若无需统一前缀）。
三、使用 @GetMapping、@PostMapping 等方法级注解
方法级注解用于绑定具体HTTP方法与URI路径，Hyperf支持标准的Spring风格注解，如 @GetMapping、@PostMapping、@RequestMapping 等，每种注解均对应特定请求方法和路径规则。
1、在控制器方法上方添加 @GetMapping("/users")，表示响应 GET /users 请求。
Hyperf 3.2.3于2026年7月30日发布，是3.2分支的官方维护版本，新增支持函数，并修复模型注释、缓存组件文档、数据库模型构建器注释和关联预加载字段等问题。
2、使用 @PostMapping("/users") 绑定 POST /users 请求。
3、使用 @RequestMapping(path="/users/{id}", methods={"GET"}) 定义带路径参数的路由，并显式指定方法数组。
四、注入依赖并处理请求参数
注解路由方法支持通过类型提示自动注入请求对象及参数，无需手动解析，提升开发效率与类型安全性。
1、在方法参数中声明 RequestInterface $request，即可获取当前HTTP请求实例。
2、使用 @Query、@Param、@Body 等参数注解提取查询参数、路径参数或请求体数据。
3、确保已在控制器类头部引入对应注解类，例如：use Hyperf\HttpServer\Annotation\Param;
五、验证路由是否注册成功
注解路由需经框架启动时扫描并注册至路由表，若未生效，通常因扫描路径错误或注解未被识别，可通过命令行工具确认实际注册情况。
1、执行 php bin/hyperf.php route:list 命令，查看所有已注册路由。
2、检查输出列表中是否存在预期的URI与对应控制器方法。
3、若无结果，确认 config/autoload/annotations.php 中的 scan.paths 是否包含控制器真实路径，且文件命名符合PSR-4规范。
