拓冰网站定制 
教育后端前端【免费下载链接】moodleMoodle - the worlds open source learning platform项目地址https://gitcode.com/gh_mirrors/mo/moodle点击查看免费下载FastRoutenikic/fast-route是一款以“快”为核心设计目标、基于正则表达式实现的 PHP 请求路由器被当前 Moodle 仓库以 Composer 依赖的形式内置在 public/lib/nikic/fast-route 目录下。本文以其官方 README 为主线完整覆盖安装、路由定义语法、可选段、分组、缓存、dispatch 分发语义以及 Parser / DataGenerator / Dispatcher 三组件架构并结合仓库源码逐层揭示其“快”的底层原理。读完本文你将能独立使用 FastRoute 搭建高性能 REST 路由也能理解并替换其默认分发策略。一、FastRoute 是什么FastRoute 是一个快速实现的正则表达式路由器它把一组路由规则编译成少数几条正则表达式在请求到来时用最少的正则匹配完成分发。官方 README 明确说明其设计动机并给出了介绍实现原理的博客链接见 README.md。从当前仓库的 composer.json 可以看到它的基础信息包名nikic/fast-route描述为 Fast request router for PHP许可证BSD-3-Clause作者Nikita Popovnikic最低要求PHP 5.4.0自动加载采用 PSR-4FastRoute\→src/并额外加载src/functions.php提供simpleDispatcher/cachedDispatcher两个全局函数。仓库内的源码结构如下均位于 public/lib/nikic/fast-route/srcRouteParser/Std.php默认路由语法解析器DataGenerator/数据生成器提供CharCountBased、GroupCountBased、GroupPosBased、MarkBased四种策略及公共抽象RegexBasedAbstractDispatcher/分发器同样提供上述四种对应策略及公共抽象RegexBasedAbstractRouteParser.php、DataGenerator.php、Dispatcher.php三个核心接口RouteCollector.php路由收集器负责 addRoute / addGroup / 快捷方法Route.php路由值对象BadRouteException.php非法路由异常functions.phpsimpleDispatcher与cachedDispatcher工厂函数。二、安装与引入FastRoute 通过 Composer 安装官方 README 给出的命令为composer require nikic/fast-route安装完成后引入vendor/autoload.php即可使用Moodle 仓库中已将其内置属于全局 Composer 依赖体系的一部分require /path/to/vendor/autoload.php;三、快速上手基础用法官方 README 提供了一段完整可运行的基础示例。核心流程是先通过FastRoute\simpleDispatcher()注册路由再从超全局变量中取出 HTTP 方法与 URI 并做规范化去掉 query string、rawurldecode 解码最后调用dispatch()根据返回状态码分支处理?php require /path/to/vendor/autoload.php; $dispatcher FastRoute\simpleDispatcher(function(FastRoute\RouteCollector $r) { $r-addRoute(GET, /users, get_all_users_handler); // {id} must be a number (\d) $r-addRoute(GET, /user/{id:\d}, get_user_handler); // The /{title} suffix is optional $r-addRoute(GET, /articles/{id:\d}[/{title}], get_article_handler); }); // Fetch method and URI from somewhere $httpMethod $_SERVER[REQUEST_METHOD]; $uri $_SERVER[REQUEST_URI]; // Strip query string (?foobar) and decode URI if (false ! $pos strpos($uri, ?)) { $uri substr($uri, 0, $pos); } $uri rawurldecode($uri); $routeInfo $dispatcher-dispatch($httpMethod, $uri); switch ($routeInfo[0]) { case FastRoute\Dispatcher::NOT_FOUND: // ... 404 Not Found break; case FastRoute\Dispatcher::METHOD_NOT_ALLOWED: $allowedMethods $routeInfo[1]; // ... 405 Method Not Allowed break; case FastRoute\Dispatcher::FOUND: $handler $routeInfo[1]; $vars $routeInfo[2]; // ... call $handler with $vars break; }需要注意URI 的获取与规范化去 query string、URL 解码是调用方自己的职责——README 明确说明该库不与任何 PHP Web SAPI 绑定因此在 CLI、常驻服务或自定义服务器中都能使用。四、路由定义详解4.1 addRoute 与多方法路由路由通过收集器RouteCollector的addRoute()注册签名如下$r-addRoute($method, $routePattern, $handler);$method大写 HTTP 方法字符串也可传入数组一次注册多个方法$routePattern路由模式字符串$handler任意值回调、控制器类名等均可。多方法注册示例README 原文// These two calls $r-addRoute(GET, /test, handler); $r-addRoute(POST, /test, handler); // Are equivalent to this one call $r-addRoute([GET, POST], /test, handler);从源码看RouteCollector.php 的addRoute()内部会先把当前分组前缀拼到路由前面然后交给routeParser-parse()解析出路由数据再对$httpMethod强转为数组逐个方法、对每份解析结果调用dataGenerator-addRoute()完成注册。4.2 占位符语法与自定义正则默认语法中{foo}表示名为foo的占位符匹配正则[^/]即不包含/的任意字符串。要约束匹配内容可写成{bar:[0-9]}指定自定义正则。README 给出的典型示例// Matches /user/42, but not /user/xyz $r-addRoute(GET, /user/{id:\d}, handler); // Matches /user/foobar, but not /user/foo/bar $r-addRoute(GET, /user/{name}, handler); // Matches /user/foo/bar as well $r-addRoute(GET, /user/{name:.}, handler);默认正则[^/]定义在 Std.php 的DEFAULT_DISPATCH_REGEX常量中而占位符的完整解析正则在 Std.php 的VARIABLE_REGEX中它支持占位符名[a-zA-Z_][a-zA-Z0-9_-]*以及可选的: 自定义正则部分。4.3 捕获组限制占位符的自定义正则不能包含捕获组。例如{lang:(en|de)}是非法写法因为()是捕获组会与 FastRoute 最终为每个占位符生成的捕获组冲突。正确做法是二选一{lang:en|de} // 直接用 | 分支 {lang:(?:en|de)} // 用非捕获组 (?:...)这一校验位于 DataGenerator/RegexBasedAbstract.php当检测到参数正则含捕获组时直接抛出BadRouteException错误信息形如Regex ... for parameter ... contains a capturing group。其底层通过一段精心编写的正则L162-L185半精确地识别捕获组会跳过字符类、转义字符与非捕获组(?:、(?、(?P、(?等。4.4 可选段 [...]用[...]包裹的路由片段是可选的/foo[bar]既能匹配/foo也能匹配/foobar。可选段只能出现在路由末尾不能出现在中间。README 给出的对比// This route $r-addRoute(GET, /user/{id:\d}[/{name}], handler); // Is equivalent to these two routes $r-addRoute(GET, /user/{id:\d}, handler); $r-addRoute(GET, /user/{id:\d}/{name}, handler); // Multiple nested optional parts are possible as well $r-addRoute(GET, /user[/{id:\d}[/{name}]], handler); // This route is NOT valid, because optional parts can only occur at the end $r-addRoute(GET, /user[/{id:\d}]/{name}, handler);这一约束在解析器层面强制实施。Std.php 的parse()先通过rtrim($route, ])统计末尾可选段数量再按[切分如果方括号数量对不上或发现路由中间存在]都会抛出BadRouteException错误信息分别为 Optional segments can only occur at the end of a route 和 Number of opening [ and closing ] does not match。空的可选段同样会报 Empty optional part。4.5 handler 的灵活性$handler不要求必须是回调它可以是控制器类名、闭包或任何你想与路由关联的数据。FastRoute 只负责告诉你哪个 handler 对应当前 URI如何解释它完全由你决定。这使 FastRoute 能无缝嵌入各类框架的 DI 容器或控制器解析逻辑中。4.6 常用方法的快捷方法对GET、POST、PUT、PATCH、DELETE、HEAD六种方法提供快捷方法$r-get(/get-route, get_handler); $r-post(/post-route, post_handler);等价于$r-addRoute(GET, /get-route, get_handler); $r-addRoute(POST, /post-route, post_handler);在 RouteCollector.php 中get/post/put/delete/patch/head六个方法均被实现为对应addRoute的简单别名。五、路由分组addGroup()允许为一组路由指定公共前缀内部嵌套的分组前缀会逐层拼接$r-addGroup(/admin, function (RouteCollector $r) { $r-addRoute(GET, /do-something, handler); $r-addRoute(GET, /do-another-thing, handler); $r-addRoute(GET, /do-something-else, handler); });等价于$r-addRoute(GET, /admin/do-something, handler); $r-addRoute(GET, /admin/do-another-thing, handler); $r-addRoute(GET, /admin/do-something-else, handler);源码实现见 RouteCollector.phpaddGroup()把当前分组前缀保存为$previousGroupPrefix拼上$prefix后执行回调最后恢复原前缀因此嵌套分组天然支持。六、缓存cachedDispatchersimpleDispatcher之所以接受回调定义路由是为了让缓存变得无缝。改用cachedDispatcher后生成的路由数据dispatch data会被写入缓存文件之后直接从缓存重建分发器跳过重新解析与编译的开销?php $dispatcher FastRoute\cachedDispatcher(function(FastRoute\RouteCollector $r) { $r-addRoute(GET, /user/{name}/{id:[0-9]}, handler0); $r-addRoute(GET, /user/{id:[0-9]}, handler1); $r-addRoute(GET, /user/{name}, handler2); }, [ cacheFile __DIR__ . /route.cache, /* required */ cacheDisabled IS_DEBUG_ENABLED, /* optional, enabled by default */ ]);选项数组说明选项是否必填说明cacheFile必填缓存文件路径未设置时抛出LogicException错误信息 Must specify cacheFile optioncacheDisabled可选默认false为true时跳过缓存读写常用于调试环境从 functions.php 的cachedDispatcher()源码可以看到完整逻辑合并默认选项默认cacheDisabled false校验cacheFile存在若未禁用缓存且缓存文件存在直接require该文件——缓存文件内容形如?php return var_export 导出的数组;见 L66-L69 的写入逻辑若结果不是数组则抛RuntimeException否则新建RouteCollector、执行回调收集路由、getData()生成数据未禁用缓存时用file_put_contents把var_export后的数据写入cacheFile用缓存数据构造分发器返回。因此cacheFile本质是一个返回数组的 PHP 文件require后可被 OPcache 加速这也是其“快”的又一来源。七、dispatch 分发语义调用$dispatcher-dispatch($httpMethod, $uri)会返回一个数组首个元素是状态码取值有三种FastRoute\Dispatcher::NOT_FOUND0路由不存在FastRoute\Dispatcher::METHOD_NOT_ALLOWED2URI 存在但方法不允许第二个元素为该方法允许的 HTTP 方法列表例如[FastRoute\Dispatcher::METHOD_NOT_ALLOWED, [GET, POST]]FastRoute\Dispatcher::FOUND1命中路由第二个元素为 handler第三个元素为占位符名到值的映射字典例如对GET /user/nikic/42匹配到handler0[FastRoute\Dispatcher::FOUND, handler0, [name nikic, id 42]]注意README 原文强调HTTP 规范要求405 Method Not Allowed响应必须携带Allow:头来列出资源可用的方法。使用 FastRoute 的应用在返回 405 时应取第二个数组元素填充该响应头。三个状态常量定义在 Dispatcher.php 接口中NOT_FOUND 0, FOUND 1, METHOD_NOT_ALLOWED 2。而完整的分发流程在 Dispatcher/RegexBasedAbstract.php先在静态路由哈希表中精确查$httpMethod $uri命中即为 FOUND零正则开销未命中则进入变量路由正则匹配HEAD请求会回退匹配GET路由再尝试通配方法*的回退路由若仍未命中则遍历所有其他方法尝试匹配同一 URI收集允许方法列表返回METHOD_NOT_ALLOWED一个都不允许则返回NOT_FOUND。八、架构剖析Parser / DataGenerator / Dispatcher 三组件8.1 三个接口路由过程由三个组件协作完成接口定义如下README 原文?php namespace FastRoute; interface RouteParser { public function parse($route); } interface DataGenerator { public function addRoute($httpMethod, $routeData, $handler); public function getData(); } interface Dispatcher { const NOT_FOUND 0, FOUND 1, METHOD_NOT_ALLOWED 2; public function dispatch($httpMethod, $uri); }8.2 解析器的输出结构RouteParser把路由模式字符串转换为路由信息数组每条路由信息又由若干片段组成。README 用/user/{id:\d}[/{name}]举例解析结果如下[ [ /user/, [id, \d], ], [ /user/, [id, \d], /, [name, [^/]], ], ]即字符串片段原样保留占位符片段表示为[占位符名, 正则]可选段展开成多条路由信息这里展开为两条。这正是 Std.phpparsePlaceholders()的实现行为。8.3 数据生成器与分发器的耦合关系解析得到的数组传给DataGenerator::addRoute()所有路由注册完后调用getData()得到分发器所需的全部路由数据。该数据的格式没有进一步规定——它与对应的分发器紧密耦合。因此可以单独替换路由解析器例如改用不同的模式语法但数据生成器与分发器必须成对更换因为前者的输出与后者的输入严格绑定生成器与分发器分离的原因是只有分发器在缓存场景下才需要被缓存的正是不需要缓存的那一方——生成器的输出。8.4 通过 options 覆盖三组件使用simpleDispatcher/cachedDispatcher时通过 options 数组覆盖组件README 示例与默认值一致?php $dispatcher FastRoute\simpleDispatcher(function(FastRoute\RouteCollector $r) { /* ... */ }, [ routeParser FastRoute\\RouteParser\\Std, dataGenerator FastRoute\\DataGenerator\\GroupCountBased, dispatcher FastRoute\\Dispatcher\\GroupCountBased, ]);把GroupCountBased换成GroupPosBased即可切换到另一种分发策略。从 functions.php 可见simpleDispatcher的完整默认选项还包括routeCollector FastRoute\RouteCollector它依次实例化收集器、执行回调、getData()并构造分发器L22-L27。8.5 四种分发策略DataGenerator与Dispatcher各提供四种配对实现目录见 src/DataGenerator 与 src/Dispatcher策略分块依据分发时如何定位 handlerGroupCountBased按捕获组数量分组默认近似块大小 10routeMap[count($matches)]见 Dispatcher/GroupCountBased.phpGroupPosBased按捕获组位置分组找第一个非空匹配的下标见 Dispatcher/GroupPosBased.phpCharCountBased按匹配到的字符数分组routeMap[end($matches)]匹配串附加 suffix见 Dispatcher/CharCountBased.phpMarkBased用命名捕获组MARK标记routeMap[$matches[MARK]]见 Dispatcher/MarkBased.php以默认的 GroupCountBased 为例DataGenerator/GroupCountBased.php 的processChunk()会把一组正则拼成一条大正则~^(?|...)$~(?|分支重置组让所有分支的捕获组编号对齐并为变量数不足的正则补空捕获组()然后以捕获组数量 1为键建routeMap。分发时见 Dispatcher/GroupCountBased.php只需执行一次preg_match就能按count($matches)立刻定位 handler 并解析变量——这正是少而快的关键。8.6 静态路由与变量路由的分离DataGenerator/RegexBasedAbstract.php 的addRoute()会判断路由是否纯静态count($routeData) 1 is_string($routeData[0])见 L76-L79静态路由进入哈希表staticRoutes匹配时是 O(1) 精确查找变量路由进入按方法组织的methodToRegexToRoutesMap并分块生成正则。同时该抽象类还集中做了多项合法性校验同方法同模式重复注册 →BadRouteException静态路由被已注册的变量路由遮蔽 →BadRouteException同一占位符重复使用 →BadRouteException见buildRegexForRoute()L138-L142。九、HEAD 请求的自动回退HTTP 规范要求所有通用服务器必须同时支持 GET 与 HEADRFC 2616 5.1.1。为避免用户为每个资源手动注册 HEAD 路由FastRoute 在HEAD 未显式定义时自动回退匹配同 URI 的 GET 路由。PHP Web SAPI 会透明地移除 HEAD 响应的实体主体因此绝大多数用户无需感知此行为。但 README 特别提醒在 Web SAPI 之外如自研服务器使用 FastRoute 的实现者绝不能为 HEAD 请求发送实体主体——这是非 SAPI 用户自己的责任应用也可以为某个资源显式注册 HEAD 路由从而完全绕过该回退行为。对应回退逻辑见 Dispatcher/RegexBasedAbstract.php当$httpMethod HEAD时先查静态GET映射再匹配GET的变量路由。十、源码阅读指引若想深入验证本文涉及的实现细节可在当前仓库中按以下路径展开阅读工厂函数与缓存逻辑src/functions.phpsimpleDispatcherL12-L28cachedDispatcherL36-L73路由收集与分组src/RouteCollector.php默认语法解析器src/RouteParser/Std.php数据生成公共逻辑与校验src/DataGenerator/RegexBasedAbstract.php分发公共逻辑静态查表、HEAD 回退、405 方法收集src/Dispatcher/RegexBasedAbstract.php四种策略实现src/DataGenerator 与 src/Dispatcher 下的同名文件路由值对象src/Route.php含matches()方法供变量路由遮蔽静态路由的校验使用包元信息与依赖约束composer.json。十一、总结FastRoute 的设计精髓可以概括为三点静态路由哈希直查、变量路由按方法分块编译成极少数大正则默认 GroupCountBased 每块约 10 条路由、可选段在解析期展开。这使得它在请求分发阶段的正则调用次数降到最低同时通过cachedDispatcher把编译结果以 PHP 数组文件的形式固化下来配合 OPcache 进一步压缩运行期开销。无论你是要在 Moodle 生态内复用这份内置依赖还是在自有框架中落地高性能路由层都可以直接遵循本文的 API 与源码证据快速上手。赞分享教育后端前端【免费下载链接】moodleMoodle - the worlds open source learning platform项目地址https://gitcode.com/gh_mirrors/mo/moodle点击查看免费下载相关推荐ShowDoc 内置 FastRoute基于正则的高性能 PHP 路由库原理与实战指南ShowDoc 内置 FastRoute基于正则的高性能 PHP 路由库原理与实战指南 FastRoute 是 ShowDoc 项目依赖链中一个轻量而高效的正文档知识库后端前端FastRoute终极路由指南5个高级正则表达式技巧实现精准URL匹配FastRoute终极路由指南5个高级正则表达式技巧实现精准URL匹配 FastRoute作为PHP生态中高性能的请求路由库以其轻量级设计和高效的URL匹配后端Fluent Bit高级配置技巧正则表达式与条件路由完全指南Fluent Bit高级配置技巧正则表达式与条件路由完全指南 你是否还在为日志处理中的数据过滤和路由难题烦恼本文将带你掌握Fluent Bit中最强大的两个可观测性日志分析云原生流处理上一篇Sketch Measure代码规范解读遵循行业最佳实践下一篇如何在Photoshop中无缝集成Stable DiffusionAuto-Photoshop-StableDiffusion-Plugin完整指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 FastRoute：基于正则表达式的高性能 PHP 请求路由器完全指南（Moodle 内置依赖源码级解析）
教育后端前端【免费下载链接】moodleMoodle - the worlds open source learning platform项目地址https://gitcode.com/gh_mirrors/mo/moodle点击查看免费下载FastRoutenikic/fast-route是一款以“快”为核心设计目标、基于正则表达式实现的 PHP 请求路由器被当前 Moodle 仓库以 Composer 依赖的形式内置在 public/lib/nikic/fast-route 目录下。本文以其官方 README 为主线完整覆盖安装、路由定义语法、可选段、分组、缓存、dispatch 分发语义以及 Parser / DataGenerator / Dispatcher 三组件架构并结合仓库源码逐层揭示其“快”的底层原理。读完本文你将能独立使用 FastRoute 搭建高性能 REST 路由也能理解并替换其默认分发策略。一、FastRoute 是什么FastRoute 是一个快速实现的正则表达式路由器它把一组路由规则编译成少数几条正则表达式在请求到来时用最少的正则匹配完成分发。官方 README 明确说明其设计动机并给出了介绍实现原理的博客链接见 README.md。从当前仓库的 composer.json 可以看到它的基础信息包名nikic/fast-route描述为 Fast request router for PHP许可证BSD-3-Clause作者Nikita Popovnikic最低要求PHP 5.4.0自动加载采用 PSR-4FastRoute\→src/并额外加载src/functions.php提供simpleDispatcher/cachedDispatcher两个全局函数。仓库内的源码结构如下均位于 public/lib/nikic/fast-route/srcRouteParser/Std.php默认路由语法解析器DataGenerator/数据生成器提供CharCountBased、GroupCountBased、GroupPosBased、MarkBased四种策略及公共抽象RegexBasedAbstractDispatcher/分发器同样提供上述四种对应策略及公共抽象RegexBasedAbstractRouteParser.php、DataGenerator.php、Dispatcher.php三个核心接口RouteCollector.php路由收集器负责 addRoute / addGroup / 快捷方法Route.php路由值对象BadRouteException.php非法路由异常functions.phpsimpleDispatcher与cachedDispatcher工厂函数。二、安装与引入FastRoute 通过 Composer 安装官方 README 给出的命令为composer require nikic/fast-route安装完成后引入vendor/autoload.php即可使用Moodle 仓库中已将其内置属于全局 Composer 依赖体系的一部分require /path/to/vendor/autoload.php;三、快速上手基础用法官方 README 提供了一段完整可运行的基础示例。核心流程是先通过FastRoute\simpleDispatcher()注册路由再从超全局变量中取出 HTTP 方法与 URI 并做规范化去掉 query string、rawurldecode 解码最后调用dispatch()根据返回状态码分支处理?php require /path/to/vendor/autoload.php; $dispatcher FastRoute\simpleDispatcher(function(FastRoute\RouteCollector $r) { $r-addRoute(GET, /users, get_all_users_handler); // {id} must be a number (\d) $r-addRoute(GET, /user/{id:\d}, get_user_handler); // The /{title} suffix is optional $r-addRoute(GET, /articles/{id:\d}[/{title}], get_article_handler); }); // Fetch method and URI from somewhere $httpMethod $_SERVER[REQUEST_METHOD]; $uri $_SERVER[REQUEST_URI]; // Strip query string (?foobar) and decode URI if (false ! $pos strpos($uri, ?)) { $uri substr($uri, 0, $pos); } $uri rawurldecode($uri); $routeInfo $dispatcher-dispatch($httpMethod, $uri); switch ($routeInfo[0]) { case FastRoute\Dispatcher::NOT_FOUND: // ... 404 Not Found break; case FastRoute\Dispatcher::METHOD_NOT_ALLOWED: $allowedMethods $routeInfo[1]; // ... 405 Method Not Allowed break; case FastRoute\Dispatcher::FOUND: $handler $routeInfo[1]; $vars $routeInfo[2]; // ... call $handler with $vars break; }需要注意URI 的获取与规范化去 query string、URL 解码是调用方自己的职责——README 明确说明该库不与任何 PHP Web SAPI 绑定因此在 CLI、常驻服务或自定义服务器中都能使用。四、路由定义详解4.1 addRoute 与多方法路由路由通过收集器RouteCollector的addRoute()注册签名如下$r-addRoute($method, $routePattern, $handler);$method大写 HTTP 方法字符串也可传入数组一次注册多个方法$routePattern路由模式字符串$handler任意值回调、控制器类名等均可。多方法注册示例README 原文// These two calls $r-addRoute(GET, /test, handler); $r-addRoute(POST, /test, handler); // Are equivalent to this one call $r-addRoute([GET, POST], /test, handler);从源码看RouteCollector.php 的addRoute()内部会先把当前分组前缀拼到路由前面然后交给routeParser-parse()解析出路由数据再对$httpMethod强转为数组逐个方法、对每份解析结果调用dataGenerator-addRoute()完成注册。4.2 占位符语法与自定义正则默认语法中{foo}表示名为foo的占位符匹配正则[^/]即不包含/的任意字符串。要约束匹配内容可写成{bar:[0-9]}指定自定义正则。README 给出的典型示例// Matches /user/42, but not /user/xyz $r-addRoute(GET, /user/{id:\d}, handler); // Matches /user/foobar, but not /user/foo/bar $r-addRoute(GET, /user/{name}, handler); // Matches /user/foo/bar as well $r-addRoute(GET, /user/{name:.}, handler);默认正则[^/]定义在 Std.php 的DEFAULT_DISPATCH_REGEX常量中而占位符的完整解析正则在 Std.php 的VARIABLE_REGEX中它支持占位符名[a-zA-Z_][a-zA-Z0-9_-]*以及可选的: 自定义正则部分。4.3 捕获组限制占位符的自定义正则不能包含捕获组。例如{lang:(en|de)}是非法写法因为()是捕获组会与 FastRoute 最终为每个占位符生成的捕获组冲突。正确做法是二选一{lang:en|de} // 直接用 | 分支 {lang:(?:en|de)} // 用非捕获组 (?:...)这一校验位于 DataGenerator/RegexBasedAbstract.php当检测到参数正则含捕获组时直接抛出BadRouteException错误信息形如Regex ... for parameter ... contains a capturing group。其底层通过一段精心编写的正则L162-L185半精确地识别捕获组会跳过字符类、转义字符与非捕获组(?:、(?、(?P、(?等。4.4 可选段 [...]用[...]包裹的路由片段是可选的/foo[bar]既能匹配/foo也能匹配/foobar。可选段只能出现在路由末尾不能出现在中间。README 给出的对比// This route $r-addRoute(GET, /user/{id:\d}[/{name}], handler); // Is equivalent to these two routes $r-addRoute(GET, /user/{id:\d}, handler); $r-addRoute(GET, /user/{id:\d}/{name}, handler); // Multiple nested optional parts are possible as well $r-addRoute(GET, /user[/{id:\d}[/{name}]], handler); // This route is NOT valid, because optional parts can only occur at the end $r-addRoute(GET, /user[/{id:\d}]/{name}, handler);这一约束在解析器层面强制实施。Std.php 的parse()先通过rtrim($route, ])统计末尾可选段数量再按[切分如果方括号数量对不上或发现路由中间存在]都会抛出BadRouteException错误信息分别为 Optional segments can only occur at the end of a route 和 Number of opening [ and closing ] does not match。空的可选段同样会报 Empty optional part。4.5 handler 的灵活性$handler不要求必须是回调它可以是控制器类名、闭包或任何你想与路由关联的数据。FastRoute 只负责告诉你哪个 handler 对应当前 URI如何解释它完全由你决定。这使 FastRoute 能无缝嵌入各类框架的 DI 容器或控制器解析逻辑中。4.6 常用方法的快捷方法对GET、POST、PUT、PATCH、DELETE、HEAD六种方法提供快捷方法$r-get(/get-route, get_handler); $r-post(/post-route, post_handler);等价于$r-addRoute(GET, /get-route, get_handler); $r-addRoute(POST, /post-route, post_handler);在 RouteCollector.php 中get/post/put/delete/patch/head六个方法均被实现为对应addRoute的简单别名。五、路由分组addGroup()允许为一组路由指定公共前缀内部嵌套的分组前缀会逐层拼接$r-addGroup(/admin, function (RouteCollector $r) { $r-addRoute(GET, /do-something, handler); $r-addRoute(GET, /do-another-thing, handler); $r-addRoute(GET, /do-something-else, handler); });等价于$r-addRoute(GET, /admin/do-something, handler); $r-addRoute(GET, /admin/do-another-thing, handler); $r-addRoute(GET, /admin/do-something-else, handler);源码实现见 RouteCollector.phpaddGroup()把当前分组前缀保存为$previousGroupPrefix拼上$prefix后执行回调最后恢复原前缀因此嵌套分组天然支持。六、缓存cachedDispatchersimpleDispatcher之所以接受回调定义路由是为了让缓存变得无缝。改用cachedDispatcher后生成的路由数据dispatch data会被写入缓存文件之后直接从缓存重建分发器跳过重新解析与编译的开销?php $dispatcher FastRoute\cachedDispatcher(function(FastRoute\RouteCollector $r) { $r-addRoute(GET, /user/{name}/{id:[0-9]}, handler0); $r-addRoute(GET, /user/{id:[0-9]}, handler1); $r-addRoute(GET, /user/{name}, handler2); }, [ cacheFile __DIR__ . /route.cache, /* required */ cacheDisabled IS_DEBUG_ENABLED, /* optional, enabled by default */ ]);选项数组说明选项是否必填说明cacheFile必填缓存文件路径未设置时抛出LogicException错误信息 Must specify cacheFile optioncacheDisabled可选默认false为true时跳过缓存读写常用于调试环境从 functions.php 的cachedDispatcher()源码可以看到完整逻辑合并默认选项默认cacheDisabled false校验cacheFile存在若未禁用缓存且缓存文件存在直接require该文件——缓存文件内容形如?php return var_export 导出的数组;见 L66-L69 的写入逻辑若结果不是数组则抛RuntimeException否则新建RouteCollector、执行回调收集路由、getData()生成数据未禁用缓存时用file_put_contents把var_export后的数据写入cacheFile用缓存数据构造分发器返回。因此cacheFile本质是一个返回数组的 PHP 文件require后可被 OPcache 加速这也是其“快”的又一来源。七、dispatch 分发语义调用$dispatcher-dispatch($httpMethod, $uri)会返回一个数组首个元素是状态码取值有三种FastRoute\Dispatcher::NOT_FOUND0路由不存在FastRoute\Dispatcher::METHOD_NOT_ALLOWED2URI 存在但方法不允许第二个元素为该方法允许的 HTTP 方法列表例如[FastRoute\Dispatcher::METHOD_NOT_ALLOWED, [GET, POST]]FastRoute\Dispatcher::FOUND1命中路由第二个元素为 handler第三个元素为占位符名到值的映射字典例如对GET /user/nikic/42匹配到handler0[FastRoute\Dispatcher::FOUND, handler0, [name nikic, id 42]]注意README 原文强调HTTP 规范要求405 Method Not Allowed响应必须携带Allow:头来列出资源可用的方法。使用 FastRoute 的应用在返回 405 时应取第二个数组元素填充该响应头。三个状态常量定义在 Dispatcher.php 接口中NOT_FOUND 0, FOUND 1, METHOD_NOT_ALLOWED 2。而完整的分发流程在 Dispatcher/RegexBasedAbstract.php先在静态路由哈希表中精确查$httpMethod $uri命中即为 FOUND零正则开销未命中则进入变量路由正则匹配HEAD请求会回退匹配GET路由再尝试通配方法*的回退路由若仍未命中则遍历所有其他方法尝试匹配同一 URI收集允许方法列表返回METHOD_NOT_ALLOWED一个都不允许则返回NOT_FOUND。八、架构剖析Parser / DataGenerator / Dispatcher 三组件8.1 三个接口路由过程由三个组件协作完成接口定义如下README 原文?php namespace FastRoute; interface RouteParser { public function parse($route); } interface DataGenerator { public function addRoute($httpMethod, $routeData, $handler); public function getData(); } interface Dispatcher { const NOT_FOUND 0, FOUND 1, METHOD_NOT_ALLOWED 2; public function dispatch($httpMethod, $uri); }8.2 解析器的输出结构RouteParser把路由模式字符串转换为路由信息数组每条路由信息又由若干片段组成。README 用/user/{id:\d}[/{name}]举例解析结果如下[ [ /user/, [id, \d], ], [ /user/, [id, \d], /, [name, [^/]], ], ]即字符串片段原样保留占位符片段表示为[占位符名, 正则]可选段展开成多条路由信息这里展开为两条。这正是 Std.phpparsePlaceholders()的实现行为。8.3 数据生成器与分发器的耦合关系解析得到的数组传给DataGenerator::addRoute()所有路由注册完后调用getData()得到分发器所需的全部路由数据。该数据的格式没有进一步规定——它与对应的分发器紧密耦合。因此可以单独替换路由解析器例如改用不同的模式语法但数据生成器与分发器必须成对更换因为前者的输出与后者的输入严格绑定生成器与分发器分离的原因是只有分发器在缓存场景下才需要被缓存的正是不需要缓存的那一方——生成器的输出。8.4 通过 options 覆盖三组件使用simpleDispatcher/cachedDispatcher时通过 options 数组覆盖组件README 示例与默认值一致?php $dispatcher FastRoute\simpleDispatcher(function(FastRoute\RouteCollector $r) { /* ... */ }, [ routeParser FastRoute\\RouteParser\\Std, dataGenerator FastRoute\\DataGenerator\\GroupCountBased, dispatcher FastRoute\\Dispatcher\\GroupCountBased, ]);把GroupCountBased换成GroupPosBased即可切换到另一种分发策略。从 functions.php 可见simpleDispatcher的完整默认选项还包括routeCollector FastRoute\RouteCollector它依次实例化收集器、执行回调、getData()并构造分发器L22-L27。8.5 四种分发策略DataGenerator与Dispatcher各提供四种配对实现目录见 src/DataGenerator 与 src/Dispatcher策略分块依据分发时如何定位 handlerGroupCountBased按捕获组数量分组默认近似块大小 10routeMap[count($matches)]见 Dispatcher/GroupCountBased.phpGroupPosBased按捕获组位置分组找第一个非空匹配的下标见 Dispatcher/GroupPosBased.phpCharCountBased按匹配到的字符数分组routeMap[end($matches)]匹配串附加 suffix见 Dispatcher/CharCountBased.phpMarkBased用命名捕获组MARK标记routeMap[$matches[MARK]]见 Dispatcher/MarkBased.php以默认的 GroupCountBased 为例DataGenerator/GroupCountBased.php 的processChunk()会把一组正则拼成一条大正则~^(?|...)$~(?|分支重置组让所有分支的捕获组编号对齐并为变量数不足的正则补空捕获组()然后以捕获组数量 1为键建routeMap。分发时见 Dispatcher/GroupCountBased.php只需执行一次preg_match就能按count($matches)立刻定位 handler 并解析变量——这正是少而快的关键。8.6 静态路由与变量路由的分离DataGenerator/RegexBasedAbstract.php 的addRoute()会判断路由是否纯静态count($routeData) 1 is_string($routeData[0])见 L76-L79静态路由进入哈希表staticRoutes匹配时是 O(1) 精确查找变量路由进入按方法组织的methodToRegexToRoutesMap并分块生成正则。同时该抽象类还集中做了多项合法性校验同方法同模式重复注册 →BadRouteException静态路由被已注册的变量路由遮蔽 →BadRouteException同一占位符重复使用 →BadRouteException见buildRegexForRoute()L138-L142。九、HEAD 请求的自动回退HTTP 规范要求所有通用服务器必须同时支持 GET 与 HEADRFC 2616 5.1.1。为避免用户为每个资源手动注册 HEAD 路由FastRoute 在HEAD 未显式定义时自动回退匹配同 URI 的 GET 路由。PHP Web SAPI 会透明地移除 HEAD 响应的实体主体因此绝大多数用户无需感知此行为。但 README 特别提醒在 Web SAPI 之外如自研服务器使用 FastRoute 的实现者绝不能为 HEAD 请求发送实体主体——这是非 SAPI 用户自己的责任应用也可以为某个资源显式注册 HEAD 路由从而完全绕过该回退行为。对应回退逻辑见 Dispatcher/RegexBasedAbstract.php当$httpMethod HEAD时先查静态GET映射再匹配GET的变量路由。十、源码阅读指引若想深入验证本文涉及的实现细节可在当前仓库中按以下路径展开阅读工厂函数与缓存逻辑src/functions.phpsimpleDispatcherL12-L28cachedDispatcherL36-L73路由收集与分组src/RouteCollector.php默认语法解析器src/RouteParser/Std.php数据生成公共逻辑与校验src/DataGenerator/RegexBasedAbstract.php分发公共逻辑静态查表、HEAD 回退、405 方法收集src/Dispatcher/RegexBasedAbstract.php四种策略实现src/DataGenerator 与 src/Dispatcher 下的同名文件路由值对象src/Route.php含matches()方法供变量路由遮蔽静态路由的校验使用包元信息与依赖约束composer.json。十一、总结FastRoute 的设计精髓可以概括为三点静态路由哈希直查、变量路由按方法分块编译成极少数大正则默认 GroupCountBased 每块约 10 条路由、可选段在解析期展开。这使得它在请求分发阶段的正则调用次数降到最低同时通过cachedDispatcher把编译结果以 PHP 数组文件的形式固化下来配合 OPcache 进一步压缩运行期开销。无论你是要在 Moodle 生态内复用这份内置依赖还是在自有框架中落地高性能路由层都可以直接遵循本文的 API 与源码证据快速上手。赞分享教育后端前端【免费下载链接】moodleMoodle - the worlds open source learning platform项目地址https://gitcode.com/gh_mirrors/mo/moodle点击查看免费下载相关推荐ShowDoc 内置 FastRoute基于正则的高性能 PHP 路由库原理与实战指南ShowDoc 内置 FastRoute基于正则的高性能 PHP 路由库原理与实战指南 FastRoute 是 ShowDoc 项目依赖链中一个轻量而高效的正文档知识库后端前端FastRoute终极路由指南5个高级正则表达式技巧实现精准URL匹配FastRoute终极路由指南5个高级正则表达式技巧实现精准URL匹配 FastRoute作为PHP生态中高性能的请求路由库以其轻量级设计和高效的URL匹配后端Fluent Bit高级配置技巧正则表达式与条件路由完全指南Fluent Bit高级配置技巧正则表达式与条件路由完全指南 你是否还在为日志处理中的数据过滤和路由难题烦恼本文将带你掌握Fluent Bit中最强大的两个可观测性日志分析云原生流处理上一篇Sketch Measure代码规范解读遵循行业最佳实践下一篇如何在Photoshop中无缝集成Stable DiffusionAuto-Photoshop-StableDiffusion-Plugin完整指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考