prefix末尾不能带斜杠，否则拼接出双斜杠（如/api//index）导致fastroute匹配失败；正确写法是prefix: '/api'且方法路径不加开头斜杠，如@getmapping("index")。

prefix 参数末尾不能带斜杠

写成 prefix: '/api/' 会导致路由匹配失败，比如访问 /api/index 时 404。Hyperf 会把前缀和方法路径拼接成 /api//index（双斜杠），而 FastRoute 不识别这种路径格式。

正确写法是统一去掉末尾斜杠：prefix: '/api'，然后方法路径写成 /index 或直接 index（不加开头斜杠）。

• ✅ 推荐：#[AutoController(prefix: '/api')] + public function index() → 匹配 GET /api/index
• ❌ 错误：#[AutoController(prefix: '/api/')] → 拼出 /api//index，FastRoute 跳过匹配
• ⚠️ 注意：即使控制器里方法路径写 @GetMapping("/index")，前缀末尾斜杠仍会引发双斜杠问题

prefix 和路由路径拼接规则必须对齐

Hyperf 的注解路由拼接逻辑是「前缀 + 方法路径」，但方法路径是否带开头斜杠，直接影响最终结果。这个细节在文档里没明说，但实测行为很明确。

Skill Weave Chains — 技能链路由引擎

开箱即用的技能链路由引擎。13 条预定义链覆盖搜索、开发、审查、MLOps、法律、创意等场景，三层路由架构（触发词→SAD反馈→DAG编排），recall@10=96.97%。配置驱动（chains.yaml），零代码扩展。pip install skill-weave-chains 一键安装。

下载

• 若方法用 @GetMapping("index")（无斜杠），则拼接为 /api/index
• 若方法用 @GetMapping("/index")（带斜杠），则拼接为 /api/index —— FastRoute 会自动 normalize 掉重复斜杠，但不保证所有版本都兼容
• 最稳妥做法：prefix 不带斜杠，方法路径也不带开头斜杠，例如 @GetMapping("users")

嵌套 prefix 容易触发路径覆盖或丢失

当同时使用全局路由分组（Router::addGroup('/v1', ...)）和控制器 prefix 时，Hyperf 不会自动合并前缀，而是以最后注册的为准——这取决于加载顺序，极易出错。

• ❌ 避免混用：Router::addGroup('/v1', [...]) + #[AutoController(prefix: '/users')] → 实际注册的是 /users，不是 /v1/users
• ✅ 统一收口：要么全用 Router::addGroup，要么全用控制器 prefix，不要交叉
• ? 如果必须嵌套（如 /api/v1/users），控制器 prefix 应写成 '/api/v1'，方法路径写 'users'，而非拆成两层

route:list 输出能直接暴露 prefix 错误

执行 php bin/hyperf.php route:list 后，如果看到某条路由的 URI 列出现 // 或明显多出斜杠（如 /api//index），基本可以锁定是 prefix 末尾多了斜杠。

• 正常输出应为：GET | /api/index | App\Controller\IndexController::index
• 异常输出示例：GET | /api//index | ... → 立即检查 prefix 值
• 如果该路由根本没出现在列表里，优先排查 scan.paths 是否漏了控制器目录，而不是先改 prefix

实际项目里，prefix 看似简单，但拼接逻辑藏在框架底层，一旦出错没有明确报错，只能靠 route:list 反推。最保险的做法是：所有 prefix 字符串手动 rtrim($str, '/') 再传入注解。