它的本质是：**Hyperf 的路由扫描器 (RouterScanner) 在启动阶段通过反射 (Reflection)遍历所有被@Controller标记的类。它只查找Public 方法上的路由注解，因为：
- 可访问性 (Accessibility)：HTTP 请求是外部输入，只能调用类的公开接口 (Public API)。Protected/Private 方法无法被外部直接触发。
- 扫描策略 (Scanning Strategy)：为了性能和安全，扫描器默认忽略非 Public 方法，避免将内部辅助逻辑意外暴露为 API 端点。
- 元数据绑定 (Metadata Binding)：路由信息（URL、Method、Middleware）是与特定方法签名绑定的。如果注解不在方法上，扫描器无法建立 URL 到代码执行入口的映射。
如果把 Controller 比作一家餐厅的菜单：
- Controller 类：是厨房。
- Public 方法：是前台服务员能点的菜（如“宫保鸡丁”）。
- Private/Protected 方法：是厨师内部的备菜步骤（如“切葱”、“热油”）。客人不能直接点“切葱”。
#[GetMapping]：是菜单上的条目。- 规则：菜单条目必须对应一道可上桌的菜 (Public Method)。
- 错误：如果你把菜单条目写在“切葱”这个内部步骤上，服务员（路由器）找不到这道菜，客人（客户端）也就点不了。
- 核心逻辑：别把菜单贴在厨房的后门上。菜单必须贴在前台，且对应的必须是能端出来的菜。
一、扫描机制：Hyperf 如何发现路由？
1. 启动时扫描 (Startup Scanning)
- 组件：
hyperf/http-server中的RouterFactory和AnnotationScanner。 - 流程：
- 找到所有带有
@Controller注解的类。 - 使用
ReflectionClass获取类的所有方法。 - 过滤：只保留
isPublic()的方法。 - 提取：检查每个 Public 方法的 DocBlock 或 Attributes，查找
@GetMapping,@PostMapping等注解。 - 注册：将注解中的路径、HTTP 方法、中间件等信息注册到 Swoole/Hyperf 的路由表中。
- 找到所有带有
2. 为什么只扫描 Public？
- 安全性：防止开发者误将内部逻辑（如
private function calculateTax()）暴露为 HTTP 接口。 - 规范性：RESTful API 强调资源的操作，这些操作应当是公开的契约。
- 性能：减少反射开销，忽略大量私有/保护方法。
💡 核心洞察：路由注解是“对外承诺”。只有 Public 方法才能履行对外的承诺。
二、可见性约束：为什么 Private/Protected 不行？
1. 物理不可达 (Physically Unreachable)
- 机制：当 HTTP 请求到来时，Hyperf 的核心调度器会执行类似
$controllerInstance->$methodName()的操作。 - 限制：PHP 引擎禁止从外部上下文调用 Private/Protected 方法。
- 结果：即使你强行让扫描器识别了私有方法的路由，运行时也会抛出
Fatal Error: Call to private method。
2. 语义冲突 (Semantic Conflict)
- Private/Protected：意为“内部实现细节”，可能随时变更，不保证稳定性。
- Routing：意为“公开 API 端点”，需要保持稳定，供客户端调用。
- 冲突：将不稳定内部细节标记为稳定公开端点，是架构设计的反模式。
3. 注解继承问题
- 现象：如果父类有
@GetMapping，子类重写该方法但未加注解，路由是否生效？- Hyperf 行为：通常注解不自动继承到重写方法上，除非显式声明。
- 建议：在每个具体的 Public 实现上明确标注注解，确保路由清晰。
三、常见错误与陷阱
1. 错误：注解写在 Private 方法上
classUserController{/** * @GetMapping(path="/user/list") // ❌ 不会被扫描，路由不存在 */privatefunctionlistUsers(){// ...}}- 后果：启动时无报错（取决于配置），但访问
/user/list返回404 Not Found。 - 调试：运行
php bin/hyperf.php describe:routes查看已注册路由，确认该路径缺失。
2. 错误：注解写在类级别而非方法级别
/** * @Controller(prefix="/user") * @GetMapping(path="/list") // ❌ 无效，GetMapping 必须作用于方法 */classUserController{publicfunctionlist(){...}}- 后果：路由未注册。
- 修正：
@Controller定义前缀，@GetMapping定义具体路径和方法。
3. 错误：方法不是 Public
classUserController{#[GetMapping(path="/list")]protectedfunctionlist(){// ❌ 扫描器忽略 Protected// ...}}- 后果：404。
- 修正：改为
public function list()。
4. 错误：路径冲突
- 现象：两个不同的 Public 方法使用了相同的路径和 HTTP 方法。
- 后果：后扫描到的路由覆盖先前的，或者启动报错（取决于版本配置）。
- 对策：确保路由路径唯一性。
四、最佳实践：如何正确标注？
1. 标准写法
useHyperf\HttpServer\Annotation\Controller;useHyperf\HttpServer\Annotation\GetMapping;useHyperf\HttpServer\Annotation\PostMapping;#[Controller(prefix:"/api/user")]classUserController{// ✅ 正确：Public 方法 + 方法级注解#[GetMapping(path:"/list")]publicfunctionlist(){return['users'=>[]];}// ✅ 正确：支持参数绑定#[PostMapping(path:"/create")]publicfunctioncreate(RequestInterface$request){$data=$request->all();// ...}// ❌ 内部逻辑：不加路由注解，保持 PrivateprivatefunctionvalidateData(array$data):bool{returntrue;}}2. 使用describe:routes验证
- 命令：
php bin/hyperf.php describe:routes - 作用：列出所有已注册的路由、方法、回调函数。
- 价值：开发过程中，每次添加路由后运行此命令，确认路由是否生效，路径是否正确。
3. 分组与中间件
- 场景：一组路由需要相同的中间件（如 Auth）。
- 做法：在
@Controller或方法注解中指定middleware。#[GetMapping(path:"/profile",middleware:[AuthMiddleware::class])]publicfunctionprofile(){...}
4. 属性注解 (Attributes) vs 文档注释 (DocBlock)
- 趋势：PHP 8+ 推荐使用
#[Attribute]语法。 - 优势：语法更严格，IDE 支持更好，不会被误删。
- 兼容：Hyperf 同时支持两种写法，但建议统一使用 Attributes。
🚀 总结：原子化“路由注解位置”全景图
| 维度 | 关键点 |
|---|---|
| 本质 | 公开 API 契约与内部实现的隔离 |
| 扫描规则 | 仅扫描 Public 方法上的路由注解 |
| 底层原因 | 外部可达性、安全性、反射性能 |
| 常见错误 | 注解在 Private/Protected 方法、404、路径冲突 |
| 验证工具 | php bin/hyperf.php describe:routes |
| PHP 隐喻 | Menu Items must point to Servable Dishes (Public Methods) |
| 公式 | Route_Registration = Scan(Public_Methods) × Extract(Annotations) |
终极心法：
路由注解的本质，是“对外服务的窗口”。
只有打开的窗户 (Public)，才能接收阳光 (Request)。
别把窗户开在墙壁夹层里 (Private)。
于可见中见契约，于公开见服务；以规范为尺，解隐蔽之牛，于 API 设计中，求清晰之真。
行动指令：
- 检查路由：运行
describe:routes，确认所有预期的 API 都在列表中。 - 审计可见性：搜索项目中带有路由注解但非 Public 的方法，修正为 Public 或移除注解。
- 统一风格：确保团队统一使用
#[Attribute]或 DocBlock，不要混用。 - 思维升级：记住，每一个 Public 且带路由注解的方法，都是你对世界做出的承诺。请慎重对待。
