Hyperf控制器路由绑定仅支持routes.php手动注册和注解扫描两种方式，无隐式约定机制；手动注册最可靠，注解需正确配置扫描路径且各有适用场景与限制。
Hyperf 中控制器方法绑定路由只有两种可靠方式：写在 config/routes.php 里手动注册，或用注解自动扫描生成。没有第三种“隐式”或“约定式”的默认绑定机制。
routes.php 手动注册是最直接、最可控的方式
所有控制器方法都必须显式出现在路由配置中，Hyperf 不会自动把类方法映射成路由。常见错误是只写了控制器和方法，却忘了在 routes.php 里加对应行，结果 404。
-
Router::get('/user', 'App\Controller\UserController@index')和Router::get('/user', [App\Controller\UserController::class, 'index'])效果一致，推荐后者——避免字符串拼接出错 - 路径参数需显式声明：
Router::get('/user/{id:\d+}', 'App\Controller\UserController@show')，正则不写或写错（比如漏掉\d+）会导致匹配失败 - 如果控制器方法名是
handle或__invoke，仍需完整写明，不能省略；Hyperf 不识别“可调用类实例”这种 PHP 特性作为路由目标 - 路由组前缀叠加后，最终路径是拼接结果：
Router::addGroup('/api', fn() => Router::get('/users', ...))对应/api/users，不是/api//users
@AutoController 注解只适用于简单场景
它本质是按方法名自动生成路径，比如 index() → /index，store() → /store，不支持 RESTful 资源路由或自定义路径语义。
Skill Weave Chains — 技能链路由引擎
下载
开箱即用的技能链路由引擎。13 条预定义链覆盖搜索、开发、审查、MLOps、法律、创意等场景，三层路由架构（触发词→SAD反馈→DAG编排），recall@10=96.97%。配置驱动（chains.yaml），零代码扩展。pip install skill-weave-chains 一键安装。
- 必须确保
config/autoload/annotations.php中'scan' => true且'paths'包含控制器目录，否则注解完全不生效 -
@AutoController(prefix: 'admin')会把所有方法前缀设为/admin，但无法对单个方法再改路径——想让index()对应/admin/dashboard？不行，得换@Controller+@GetMapping - 它默认只允许 GET 和 POST，想支持 PUT/DELETE 必须手动加
@PutMapping等注解，此时已脱离@AutoController的简化逻辑 - 方法签名必须带
RequestInterface或其他可注入类型，否则运行时报ParameterNotFoundException
@Controller + @GetMapping 这套注解组合更灵活但易漏配置
这是 Spring 风格的细粒度控制，适合需要精确路径、方法、参数绑定的接口，但每一步都可能断链。
-
@Controller('/api/v1')只影响类内方法的路径前缀，不自动注册任何路由——必须每个方法都加@GetMapping等，漏一个就 404 - 路径参数要用
@Param('id')显式接收，不能只靠方法参数名自动绑定；查询参数同理，@Query('page')缺一不可 - 若用了
@Controller却没配annotations.php的扫描路径，整个类会被忽略，连构造函数都不会执行 - 注解路由和
routes.php路由共存时，优先级相同，冲突路径会报重复注册警告（启动日志里搜Duplicate route）
真正容易被忽略的是：路由绑定成功 ≠ 请求能进到控制器。中间件拦截、请求体解析失败、参数验证未通过，都会在到达控制器方法前终止流程——别只盯着路由定义本身，要顺着手动注册或注解扫描、中间件链、参数注入这三步链路去排查。
