如何基于ThinkPHP注解实现自定义路由注解权限控制？

本文共计1079个文字，预计阅读时间需要5分钟。

ThinkPHP 8 的官方中间件（如 `@Middleware`）主要负责绑定中间件，不解析业务逻辑——它只是将请求丢给中间件后，就不再关心了。权限判断必须由你写的中间件自行完成，注解只是起到开关的作用。

常见错误是以为加了 @Middleware("CheckPermission") 就自动读取方法上的 @Permission("user:delete") 并校验，其实框架压根不识别后者。你需要手动扩展注解解析能力。

实操建议：

• 用 think-annotation 扩展包（官方推荐）加载自定义注解类，别自己手写反射解析
• 自定义注解类必须继承 think\annotation\Annotation，且命名需匹配（如 Permission 对应 @Permission）
• 注解类的 handle() 方法里不能做权限检查，只该收集元数据（如权限码、是否忽略），检查逻辑留在中间件里

如何让 @Permission("order:pay") 在路由执行前生效？

关键在「时机」：注解信息必须在控制器方法被调用前拿到，而 ThinkPHP 的路由调度链是「路由匹配 → 中间件执行 → 控制器调用」。所以得在中间件里反查当前路由绑定的控制器方法，并读取其注解。

立即学习“PHP免费学习笔记（深入）”；

示例流程：

• 在权限中间件 CheckPermission 的 handle() 中，通过 $request->action() 和 $request->controller() 拼出完整方法名
• 用 AnnotationReader::getClassMethodAnnotations() 提取该方法的 @Permission 注解实例
• 若注解存在且 $annotation->value 不为空，则调用你的权限服务（如 Auth::check($annotation->value)）
• 注意：如果控制器用了 @Middleware 全局绑定，要确保权限中间件在认证中间件之后执行，否则 Auth::user() 可能为 null

自定义路由注解（如 @Route("v2/users/{id}")）为什么没注册到路由表？

因为 ThinkPHP 默认不扫描控制器类注解生成路由——@Route 是你自定义的，框架根本不知道它该触发什么行为。必须主动触发注解路由注册，且只能在应用初始化阶段做（比如 app/common.php 或服务提供者中）。

实操要点：

• 用 think\annotation\AnnotationReader 扫描所有控制器类文件，遍历其 public 方法，提取 @Route 注解
• 每条注解需转换为 Route::rule() 调用，注意补全模块/域名/请求类型等上下文（$annotation->method ?? 'GET'）
• 路径参数（如 {id}）要转成正则变量：[\w]+，否则路由无法匹配
• 别在中间件或控制器里动态注册路由——此时路由表已冻结，注册无效

权限注解和路由注解共存时，最容易踩的坑是什么？

是注解加载顺序和缓存冲突。ThinkPHP 会缓存注解解析结果（runtime/annotation），但如果你先运行了路由注解扫描，再改了权限注解逻辑，旧缓存可能导致 @Permission 根本不被识别。

调试时务必：

• 清空 runtime/annotation/ 目录，再启服务
• 在注解类的 handle() 里加 trace() 确认是否被调用
• 检查 config/annotation.php 中的 include_paths 是否包含你的控制器目录（默认可能只扫 app/controller，漏掉 app/api）
• 如果用 Swoole，注解缓存会常驻内存，修改后必须 reload worker，不能只 stop/start

注解不是魔法，它只是把配置从 PHP 数组挪到了代码上方——背后全是反射+缓存+手动触发，哪一环断了都静默失败。