Hyperf3.1面试问答：注解路由与控制器最佳实践【实战演练】-php教程-PHP中文网

必须启用注解扫描且路径正确：config/autoload/annotations.php中scan设为true，paths包含app/controller；开发时cacheable设为false；推荐用#[autocontroller]声明控制器。

hyperf3.1面试问答：注解路由与控制器最佳实践【实战演练】

想在Hyperf 3.1项目中正确写出能被访问的注解路由控制器，又怕改了代码却始终404、route:list查不到、或服务重启后注解不生效？这通常不是代码写错了，而是注解扫描链某个环节断开了。

确认注解扫描已启用且路径配置正确

打开 config/autoload/annotations.php 文件，检查 scan 配置项是否为 true，并确认 'paths' 数组中包含你的控制器目录，例如 'app/Controller'。

如果 'scan' => false 或 'paths' 为空/未包含 app/Controller，注解将完全被忽略——【这是90%的404根本原因】。

开发阶段务必设置 'cacheable' => false，否则修改注解后不重启服务，旧缓存会持续生效。

选择控制器声明方式：AutoController 还是 Controller + 方法注解

方法一：用 #[AutoController] 快速启动

在 app/Controller/IndexController.php 中写：

namespace App\Controller;
use Hyperf\HttpServer\Annotation\AutoController;
#[AutoController(prefix: '/api')] // 注意：不要写成 '/api/'
class IndexController {
public function index() { return ['code' => 0, 'msg' => 'ok']; }
}

方法二：用 #[Controller] + #[GetMapping] 精确控制

同样在 IndexController.php 中写：

use Hyperf\HttpServer\Annotation\Controller;
use Hyperf\HttpServer\Annotation\GetMapping;
#[Controller(prefix: '/api')]
class IndexController {
#[GetMapping(path: '/health')]
public function health() { return ['status' => 'up']; }
}

在SEO发布前，从路由清单生成XML网站地图和robots.txt

当代理已经知道网站路由或内容URL，并且在启动前需要有效的sitemap XML、sitemap索引或robots.txt引用时，请使用sitemap。这是一个发布构件技能，而不是爬虫或SEO平台。

下载

注意：#[Controller] 和 #[GetMapping] 必须在同一类中；类名必须严格匹配 PSR-4 规则（如文件名为 IndexController.php，则类必须为 App\Controller\IndexController）。

验证路由是否真实注册成功

第一步：执行命令查看已加载路由

在项目根目录运行：php bin/hyperf.php route:list

输出中必须出现类似这一行：GET | /api/index | App\Controller\IndexController::index，才说明注解已被扫描并注册。

第二步：临时移除控制器文件，触发404

将 IndexController.php 重命名为 IndexController.php.bak → 启动服务（或确保已重启）→ 执行 curl http://127.0.0.1:9501/api/index → 返回 404 即证明原路由确实由该控制器提供。

第三步：若 route:list 无输出或 curl 始终空响应，立即检查：【是否执行过 composer dump-autoload】，以及 config/autoload/annotations.php 中 scan.paths 是否拼写错误（比如写成 app/Controllers）。