PHP Attributes 扫描控制器元数据的缓存方法

我在把路由从配置数组迁移到 PHP Attributes 后，最先遇到的不是语法问题，而是每个请求都要重新反射控制器。真正稳妥的做法是：扫描时使用 ReflectionClass，把 Attributes 转成可序列化的纯数组，再缓存这份“路由元数据”；不要把 ReflectionAttribute 或属性对象本身直接塞进共享缓存。

官方地址：https://www.php.net/manual/en/language.attributes.reflection.php

缓存的单位应是“类名对应的路由描述”，而不是 Reflection 对象。缓存键至少包含类名、映射规则版本和部署版本；命中时直接交给分发器，只有失效或未命中才重新扫描。

先把扫描结果变成稳定的数据

PHP 官方 Reflection API 的 getAttributes() 返回 ReflectionAttribute 数组。它可以先读取名称和参数，调用 newInstance() 时才创建属性类实例。这个延迟点很适合放在扫描阶段，扫描完成后只留下路由需要的字段。

例如把控制器方法上的 Route 规范成 method、path、handler 三个字段：

 */
    public function scan(string $controller): array
    {
        $reflection = new ReflectionClass($controller);
        $routes = [];

        foreach ($reflection->getMethods() as $method) {
            // 只筛选 Route，避免把无关 Attribute 混入路由表。
            foreach ($method->getAttributes(Route::class) as $attribute) {
                // newInstance() 这里才校验构造参数并创建属性对象。
                $route = $attribute->newInstance();
                $routes[] = [
                    'method' => strtoupper($route->method),
                    'path' => $route->path,
                    'handler' => $controller . '::' . $method->getName(),
                ];
            }
        }

        return $routes;
    }
}

进程内缓存先解决重复扫描

单个 PHP-FPM 请求结束后，普通静态变量也会消失，所以最安全的第一步是做进程内缓存：同一个请求里多个分发器或中间件读取同一个控制器时，只扫描一次。键使用完整类名，返回值保持数组，调用方不能修改内部缓存。

> */
    private static array $cache = [];

    public function __construct(private MetadataScanner $scanner) {}

    public function routesFor(string $controller): array
    {
        if (!isset(self::$cache[$controller])) {
            // 缓存的是纯数组，不保留 ReflectionClass 或 Attribute 实例。
            self::$cache[$controller] = $this->scanner->scan($controller);
        }

        // 返回副本，防止分发器意外污染同一进程的缓存结果。
        return self::$cache[$controller];
    }
}

如果应用是长驻进程，这个静态缓存会跨请求存活，必须在部署重载、代码热更新或路由规则改变时清空。PHP-FPM 的短请求模型则没有这个长期失效问题，但每个新 worker 仍会各自建立缓存。

缓存键要带上部署与规则版本

需要 APCu、Redis 或文件缓存时，建议把键明确写成版本化格式，例如 route-meta:v3:build-20260929:App\Http\UserController。类名解决“缓存谁”，映射版本解决“按哪套规则解释”，部署版本解决“代码是否已经换代”。不要只用控制器类名，否则旧 worker 或旧序列化数据可能继续被误用。

get($key);

    if (is_array($routes)) {
        // 命中时直接交给分发器，跳过 Reflection 扫描。
        return $routes;
    }

    try {
        $routes = $scanner->scan($controller);
        $cache->set($key, $routes, 3600);
        return $routes;
    } catch (Throwable $error) {
        // 属性构造参数错误应暴露为启动/路由配置错误，不写入坏缓存。
        throw new RuntimeException('Controller metadata scan failed', 0, $error);
    }
}

把缓存放在分发入口，而不是 Attribute 类里

分发器只关心最终元数据：按请求方法和路径匹配，再调用 handler。Attribute 类负责表达声明，扫描器负责转换，缓存负责复用，三者分层后更容易替换 APCu 或 Redis，也不会把缓存细节渗进每个控制器。

我的判断是：控制器数量不大、使用 PHP-FPM 时，先采用进程内静态缓存即可；多个 worker 或长驻进程需要共享时，再加 APCu/Redis，并把部署版本作为必填键段。共享缓存只存字符串、数字、布尔值和数组，不存闭包、Reflection 对象或带环境引用的服务实例。

常见边界与排查方法

• 修改 Attribute 后仍走旧路由：先确认 build 版本是否变化，再清理共享缓存；不要只重启一个长驻 worker。
• newInstance() 报错：检查 Attribute 类是否存在、构造参数是否匹配；异常发生时不要把空数组当成成功结果缓存。
• 父类方法是否被扫描：明确是否需要继承路由，并为扫描器写出对应策略；不要把 Reflection 默认行为猜成框架约定。
• 只想判断有没有标记：可以读取 getAttributes(Route::class) 后先看数量，只有需要参数时才实例化。

相关问题

缓存 ReflectionAttribute 会更快吗？不建议把它作为共享缓存格式。将其转换为稳定数组后，序列化、失效和跨进程传递都更明确。

Attributes 能替代所有配置文件吗？不能。它适合和代码声明强绑定的元数据；运营人员频繁修改、需要热更新的配置仍应放在独立配置源。