当前位置：首页 > 文章列表 > 文章 > php教程 > PHP Attributes 扫描控制器元数据的缓存方法

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

来源：17golang原创 2026-09-29 03:01:31 0浏览收藏

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

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

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

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

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

对象	是否进入缓存	原因
ReflectionClass	否	运行时反射句柄不适合作为共享数据
ReflectionAttribute	否	它是本次反射得到的描述对象
路由数组	是	字段简单、可序列化、可重新构建

例如把控制器方法上的 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 Attributes 控制器扫描到纯数组路由元数据的结构说明图 — 图1：控制器 Attributes 扫描结构说明图，重点看 Reflection 对象如何收敛为纯数组。

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

单个 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);
    }
}