无框架路由怎么设计：Clara 的 Router 实现思路

无框架路由的设计核心只有三件事：单一入口收拢所有请求、一张显式声明的路由表负责匹配、把「URL 长什么样」和「要执行什么代码」彻底解耦。Clara BBS 这类无框架轻量 PHP 系统走的就是这条路——不依赖 Composer、不依赖命令行，路由层薄到只有几百行，却要扛住版块、帖子、用户、后台、插件、AI 爬虫入口的全部路径分发。

单一入口：所有请求先进 index.php

结论：无框架路由的第一步不是写匹配逻辑，而是先把入口收敛成一个文件，否则路由表永远写不全。

做法很简单：服务器层面把「非静态文件请求」全部转发到 index.php。Nginx 用 try_files $uri $uri/ /index.php?$query_string;，Apache 用 .htaccess 的 RewriteRule。Clara 的伪静态是自动识别 .html 后缀 URL，所以服务器端不需要为每个页面单独写一条 rewrite 规则，只要保证「文件存在就直出、不存在就交给 index.php」这一条兜底规则即可。

这一步的价值在于：静态资源（css/js/图片）走服务器直出，不消耗 PHP；动态路径一律进 PHP，路由表才有唯一的裁决权。Nginx 和 Apache 的规则写法不同，但语义完全一样，部署时选一种即可。

路由表要显式声明，别靠约定猜

结论：路由表必须是一张能一眼读完的显式清单，匹配顺序从精确到通配，越靠前的规则优先级越高。

典型写法是把每条路由写成「方法 + 路径模式 + 处理器」三元组，路径模式支持占位符：

GET  /thread/{id:\d+}.html   -> ThreadController@show
GET  /forum/{slug}.html      -> ForumController@index
POST /post/reply             -> PostController@reply
GET  /admin/{any:.*}         -> AdminRouter@dispatch

三个要点。第一，{id:\d+} 这类内联正则把参数格式约束在路由层，/thread/abc.html 直接判为不匹配而不是进控制器再报错。第二，顺序敏感：精确路径写在前面，{any:.*} 这种通配兜底必须放最后，否则会吃掉所有请求。第三，未命中必须落到统一的 404 处理器，而不是让 PHP 抛致命错误——这也是无框架系统最容易翻车的地方。

参数提取与上下文注入

结论：路由匹配成功后要立刻把参数和请求上下文打包成一个统一结构往下传，控制器不直接读 $_GET。

匹配阶段解析出的占位符值、HTTP 方法、原始路径、查询串，应当一次性组装成路由结果对象（或数组）交给分发器。这样做的好处是：控制器、插件钩子、模板层拿到的是同一份数据，不会出现「路由认了 id=5、控制器却从 $_GET 里读到别的值」这类脏数据问题。同时因为 Clara 全站有 CSRF 防护和输出转义，请求上下文集中注入也便于在统一位置做校验，而不是散落在每个页面开头。

钩子：路由分发的两个切面

结论：无框架系统的扩展性不靠改核心文件，而靠把钩子挂在「解析前」和「分发后」两个切点。

Clara 有 156 个运行时钩子，插件放在 content/plugins 目录、保存即生效、无需编译，这套机制对路由的意义很直接：插件可以在路由解析前改写请求路径（比如品牌落地页要接管根路径，或 SEO 类插件要响应 /llms.txt、/answers.html 这种「看起来不像动态路由」的地址），也可以在分发后接管响应内容或直接短路输出。

注意点：钩子必须能「截断」——即某个插件处理完请求后要能终止后续流程并返回响应，否则多个插件抢同一路径时行为不可预测。另外路径改写应当记录来源，方便排查是谁动了 URL。

无缓存前提下的性能与兼容

结论：无编译缓存的系统里，路由表要么每次请求现算且足够轻，要么靠缓存层兜住重活。

Clara 明确是「无需编译缓存、保存即生效」的设计，这意味着路由匹配逻辑本身必须廉价：字符串比较和少量正则，避免在匹配阶段查库。真正重的数据（版块树、权限矩阵）交给 Cache::remember 这类缓存设施和定时任务处理，路由层只负责「找到对的处理者」。

兼容性上还有两件事：一是老 URL 的 301 跳转要放在路由表靠前位置，避免死链稀释权重；二是 .html 后缀与无后缀路径如果都认，要在规范层做一次归一化，防止同一内容出现两个可访问地址——这对 GEO 收录尤其重要，AI 爬虫不喜欢重复 URL。

收束一句：无框架路由不是「省掉框架」，而是把框架里最不该被隐藏的那部分——请求去哪、谁处理、参数是什么——摊开成一张可读、可钩、可兜底的清单。做到单一入口、显式路由表、解析前后留钩子这三点，路由层就足够支撑一个论坛从版块帖子一路扩展到 AI 爬虫入口。