PHP Attribute 做路由元数据：读取、缓存与冲突处理

把路由写进 Attribute 的价值，不是把注解换成另一种写法，而是让“路径、HTTP 方法、处理器”成为可以被程序读取的结构化数据。实战中建议在启动阶段扫描一次控制器，生成以方法和路径为键的路由表；请求到来后只查缓存，并在构建阶段直接拒绝重复路由。

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

先把路由声明设计成稳定的数据

路由元数据至少要包含路径和 HTTP 方法。路径进入索引前统一补齐开头的斜杠、去掉尾部多余斜杠，并把方法转成大写。这样 get /users 和 GET users/ 不会被当成两条不同规则。

path = $path === '//' ? '/' : $path;
        $this->method = strtoupper($method);
        if (!in_array($this->method, ['GET', 'POST', 'PUT', 'PATCH', 'DELETE'], true)) {
            throw new InvalidArgumentException('不支持的 HTTP 方法');
        }
    }
}

final class UserController
{
    #[Route('/users', 'GET')]
    public function list(): string { return 'list'; }

    #[Route('/users', 'POST')]
    public function create(): string { return 'create'; }
}

这里使用了 PHP 8 的 Attribute 语法。官方文档说明，Attribute 可以挂在方法、函数、参数、属性和类常量等声明上；路由场景把目标限制为方法更安全，也更容易在扫描时发现误用。

用 ReflectionMethod 读取 Attribute，而不是猜字符串

扫描控制器时，先调用 getAttributes(Route::class) 获取描述对象，再调用 newInstance() 创建 Route。两步分开很重要：前一步可以先检查数量，后一步才触发构造参数和目标约束的验证。

getMethods(ReflectionMethod::IS_PUBLIC) as $method) {
        // 继承来的方法不是本控制器声明的路由，避免重复收录。
        if ($method->getDeclaringClass()->getName() !== $controller) {
            continue;
        }
        $attributes = $method->getAttributes(Route::class);
        if (count($attributes) > 1) {
            throw new LogicException("方法 {$method->getName()} 声明了多个 Route");
        }
        if ($attributes !== []) {
            // newInstance 会把 Attribute 构造参数变成可直接使用的对象。
            $routes[] = [$method->getName(), $attributes[0]->newInstance()];
        }
    }
    return $routes;
}

扫描一次，缓存可匹配的路由索引

不要在每个请求里重新反射控制器。启动时把结果转换为标量数组，键使用 METHOD path，值保存控制器类名和方法名。文件缓存、OPcache 预加载或容器启动缓存都可以承载这份数据，具体方案取决于部署方式。

method . ' ' . $route->path;
            if (isset($table[$key])) {
                $old = $table[$key]['handler'];
                throw new LogicException("重复路由 {$key}: {$old} 与 {$class}::{$handler}");
            }
            // 缓存只放标量，避免把反射对象或闭包写入长期缓存。
            $table[$key] = ['controller' => $class, 'handler' => $handler];
        }
    }
    return $table;
}

$routes = compileRouteTable([UserController::class]);
$match = $routes['GET /users'] ?? null;

这一步同时完成了冲突处理：GET /users 和 POST /users 是两个合法键；第二次注册同一方法和路径则立即抛出异常。比“后注册覆盖先注册”更容易排查，也不会因为加载顺序变化而产生隐蔽行为。

几个容易踩坑的边界

PHP 官方文档还提供了 ReflectionAttribute::IS_INSTANCEOF 过滤方式和 IS_REPEATABLE 标志。路由系统是否开放重复声明，应该由匹配器设计决定，而不是为了“读取到更多属性”默认打开。

常见问题

为什么 getAttributes 返回的是 ReflectionAttribute？

这是延迟实例化设计：先得到名称和构造参数，调用 newInstance() 后才创建 Attribute 对象，便于把参数错误集中暴露在启动阶段。

路由缓存应该缓存 Route 对象吗？

更稳妥的是缓存类名、方法名、HTTP 方法和路径等标量数据。这样缓存跨进程、跨部署更容易失效和重建。

同一路径不同 HTTP 方法算冲突吗？

不算，只要索引键包含 HTTP 方法。真正的冲突是规范化后的 METHOD 与 path 完全相同。

最终的判断标准很简单：Attribute 负责声明，Reflection 负责启动时读取，路由表负责请求时匹配，冲突检查负责把配置错误尽早变成可读异常。