第十章 路由管理组件
路由管理组件负责建立外部访问地址与应用程序执行入口之间的映射关系。用户通过浏览器或其他客户端访问框架应用时,HTTP 请求首先进入框架运行入口,框架根据请求地址、请求方法及路由规则确定对应的控制器和执行方法,再将解析出的参数传递给目标程序。
本章围绕 WangStruct Framework 的路由管理机制展开,设计路由注册、路由解析、参数传递、动态路由和路由分组等基础功能,建立统一的路由管理类及相关接口,使开发者能够通过配置文件或程序代码定义应用访问路径。
10.1 路由管理组件的工程定位
在 Web 应用中,URL 地址是外部访问应用程序的重要入口。不同的 URL 通常对应不同的业务功能,例如首页访问、用户信息查询、内容展示和数据提交等。框架需要将这些外部访问地址转换为内部程序调用关系,使应用程序不必直接根据 URL 字符串编写大量判断代码。
路由管理组件承担这一转换工作。它接收请求组件提供的请求信息,根据预先注册的路由规则进行匹配,确定目标控制器、执行方法及其参数,最终将解析结果交给应用运行管理程序处理。
路由管理组件与请求、控制器及应用运行程序之间形成以下关系:
路由管理组件主要负责地址匹配和目标程序定位,不负责实现控制器内部的业务逻辑,也不直接处理数据库操作或页面展示。
从工程职责上看,路由管理组件需要完成以下工作:
-
路由规则注册:建立 URL 地址、请求方法和目标控制器之间的映射关系。
-
路由规则存储:统一管理框架运行期间已经注册的路由信息。
-
路由地址解析:根据当前 HTTP 请求信息查找匹配的路由规则。
-
路由参数提取:识别动态地址中的参数,并将参数传递给目标程序。
-
动态路由处理:支持 URL 中包含可变参数的访问路径。
-
路由分组管理:将具有共同路径前缀或共同配置的路由组织在一起。
-
路由结果返回:向应用运行程序提供统一的路由解析结果。
10.2 路由组件目录结构
路由管理组件属于框架核心程序的一部分,统一放置在 framework/Router/ 目录中。路由规则可以通过框架配置文件或应用程序代码注册,应用控制器则由应用程序目录管理。
本章涉及的工程目录结构如下:
WangStruct/
├── framework/ # 框架核心程序目录
│ ├── Router/ # 路由管理组件目录
│ │ ├── Router.php # 路由注册与统一管理类
│ │ ├── RouteParser.php # 路由地址解析类
│ │ ├── RouteMatcher.php # 路由规则匹配类
│ │ └── RouteGroup.php # 路由分组管理类
│ ├── Http/ # HTTP请求与响应组件目录
│ │ ├── Request.php # HTTP请求对象
│ │ └── Response.php # HTTP响应对象
│ └── Core/ # 框架核心类目录
│ └── Application.php # 应用运行管理类
├── config/ # 框架配置目录
│ └── routes.php # 默认路由规则配置文件
├── app/ # 应用程序目录
│ └── Controller/ # 应用控制器目录
│ └── IndexController.php # 默认首页控制器
└── public/ # Web访问入口目录
└── index.php # 框架启动入口
各程序文件的职责应当保持明确。
Router.php 是路由管理入口,负责路由注册、路由规则保存、分组调用以及统一调度解析过程。
RouteParser.php 负责处理路由地址,将 URL 路径转换成便于匹配的路径结构,并识别其中的动态参数。
RouteMatcher.php 负责将当前请求信息与已经注册的路由规则进行比较,确定是否存在匹配结果。
RouteGroup.php 负责组织具有共同前缀或共同配置的路由规则。
routes.php 用于保存通过配置方式定义的路由规则。应用开发者也可以通过程序代码直接调用路由管理接口注册路由。
10.3 路由规则的数据结构设计
路由管理程序需要使用统一的数据结构保存路由信息。每条路由规则至少需要记录请求方法、访问路径和目标程序信息。
可以将一条路由规则表示为:
其中:
-
\(M\):HTTP 请求方法,例如 GET、POST。
-
\(U\):URL 路径。
-
\(C\):目标控制器。
-
\(A\):目标执行方法。
-
\(P\):路由参数及相关配置。
例如:
$route = array(
'method' => 'GET',
'path' => '/user/profile',
'controller' => 'UserController',
'action' => 'profile',
'params' => array()
);
这条规则表示,当客户端使用 GET 方法访问 /user/profile 时,框架将请求映射到 UserController 控制器的 profile 方法。
路由管理程序可以将多条规则保存在统一数组中:
$routes = array(
array(
'method' => 'GET',
'path' => '/',
'controller' => 'IndexController',
'action' => 'index'
),
array(
'method' => 'GET',
'path' => '/user/profile',
'controller' => 'UserController',
'action' => 'profile'
)
);
在实际工程中,路由规则由路由管理类统一维护。配置文件负责提供初始规则,程序注册接口负责增加运行期间需要使用的规则。
路由规则的数据结构应当保持统一,避免配置注册和程序注册采用两套不同的数据格式。
10.4 路由注册机制
路由注册是建立 URL 与应用程序之间映射关系的过程。框架需要提供统一的注册接口,使开发者能够通过不同方式定义访问路径。
路由注册主要包括两种方式:配置文件注册和程序代码注册。
10.4.1 配置文件注册
配置文件注册适合集中管理应用访问路径。开发者可以在 config/routes.php 中定义路由规则。
例如:
<?php
return array(
array(
'method' => 'GET',
'path' => '/',
'controller' => 'IndexController',
'action' => 'index'
),
array(
'method' => 'GET',
'path' => '/user/profile',
'controller' => 'UserController',
'action' => 'profile'
),
array(
'method' => 'POST',
'path' => '/user/login',
'controller' => 'UserController',
'action' => 'login'
)
);
框架启动时读取路由配置文件,将其中的规则交给路由管理类注册。
这种方式将路由定义与控制器程序分离,便于开发者集中查看和维护应用访问路径。
10.4.2 程序代码注册
除了配置文件,框架还需要提供程序化注册接口。
例如:
$router->get(
'/',
'IndexController@index'
);
$router->post(
'/user/login',
'UserController@login'
);
$router->get(
'/user/profile',
'UserController@profile'
);
其中,get() 和 post() 分别用于注册 GET 和 POST 请求路由。
为了统一管理不同 HTTP 请求方法,可以在路由管理类中建立通用注册接口:
$router->add(
'GET',
'/user/profile',
'UserController',
'profile'
);
程序注册与配置文件注册最终都应转换为统一的路由规则结构,并保存在路由管理类内部。
10.5 路由管理类设计
Router.php 是路由组件的核心管理程序,负责接收路由注册请求、维护路由规则,并协调路由解析和匹配程序。
其主要接口包括:
| 接口 | 功能 |
|---|---|
add() |
注册一条路由规则 |
get() |
注册 GET 请求路由 |
post() |
注册 POST 请求路由 |
put() |
注册 PUT 请求路由 |
delete() |
注册 DELETE 请求路由 |
group() |
创建路由分组 |
load() |
加载配置文件中的路由 |
dispatch() |
根据当前请求执行路由解析和匹配 |
getRoutes() |
获取已注册的路由规则 |
下面给出路由管理类的基础工程实现示例:
<?php
class Router
{
protected $routes = array();
protected $parser;
protected $matcher;
public function __construct(
RouteParser $parser,
RouteMatcher $matcher
) {
$this->parser = $parser;
$this->matcher = $matcher;
}
public function add(
$method,
$path,
$controller,
$action
) {
$this->routes[] = array(
'method' => strtoupper($method),
'path' => $path,
'controller' => $controller,
'action' => $action
);
return $this;
}
public function get($path, $handler)
{
return $this->registerHandler(
'GET',
$path,
$handler
);
}
public function post($path, $handler)
{
return $this->registerHandler(
'POST',
$path,
$handler
);
}
public function put($path, $handler)
{
return $this->registerHandler(
'PUT',
$path,
$handler
);
}
public function delete($path, $handler)
{
return $this->registerHandler(
'DELETE',
$path,
$handler
);
}
protected function registerHandler(
$method,
$path,
$handler
) {
$parts = explode('@', $handler, 2);
if (count($parts) !== 2) {
throw new InvalidArgumentException(
'Invalid route handler.'
);
}
return $this->add(
$method,
$path,
$parts[0],
$parts[1]
);
}
public function load($file)
{
if (!is_file($file)) {
throw new InvalidArgumentException(
'Route configuration file not found.'
);
}
$routes = require $file;
if (!is_array($routes)) {
throw new InvalidArgumentException(
'Invalid route configuration.'
);
}
foreach ($routes as $route) {
$this->add(
$route['method'],
$route['path'],
$route['controller'],
$route['action']
);
}
return $this;
}
public function getRoutes()
{
return $this->routes;
}
}
这段代码展示路由注册和配置加载的基本关系。dispatch() 的具体实现将在后续路由解析和匹配部分完成,避免将注册管理与请求解析混合在同一个接口中。
10.6 路由地址解析机制
路由地址解析负责将客户端请求中的 URL 路径转换成可供路由匹配程序使用的标准形式。
例如,客户端访问:
https://example.com/user/profile?id=1001
其中:
/user/profile
属于 URL 路径,而:
id=1001
属于查询字符串参数。
路由地址解析主要处理路径部分,不应将查询字符串直接混入路由规则。
因此,请求信息可以分为:
其中:
-
\(P\):URL 路径。
-
\(Q\):URL 查询参数。
路由解析首先取得路径,再根据注册规则识别是否存在对应的目标程序。
10.6.1 路径标准化
不同请求可能出现路径末尾斜杠、重复斜杠或 URL 编码等情况。框架需要统一处理路径格式,避免同一访问路径因格式差异产生不一致的匹配结果。
例如:
/user/profile
/user/profile/
/user//profile
路径标准化需要明确框架采用的规则。不能在没有定义的情况下,擅自将所有不同路径视为同一地址。
本章示例采用去除路径首尾斜杠、合并连续斜杠的基础规则:
<?php
class RouteParser
{
public function normalize($path)
{
$path = parse_url(
$path,
PHP_URL_PATH
);
if ($path === false || $path === null) {
return '/';
}
$path = preg_replace(
'#/+#',
'/',
$path
);
$path = trim($path, '/');
return $path === ''
? '/'
: '/' . $path;
}
}
标准化后的路径可以作为后续路由匹配的输入。
10.6.2 路由路径解析
路由路径可以分为静态路径和动态路径。
静态路径是指路径结构固定的 URL:
/
/user/profile
/article/list
动态路径是指路径中存在可变参数的 URL:
/user/{id}
/article/{id}
/category/{name}
例如:
/user/1001
可以匹配:
/user/{id}
其中 1001 是动态参数的实际值。
路由解析程序需要识别 {id} 这样的参数标记,并提取参数名称,为后续匹配建立对应关系。
10.7 路由规则匹配机制
路由规则匹配是将当前 HTTP 请求与已经注册的路由规则进行比较的过程。
匹配时主要考虑两个条件:
-
请求方法是否一致。
-
请求路径是否符合路由规则。
例如,已注册以下规则:
$router->get(
'/user/profile',
'UserController@profile'
);
当请求方法为 GET,路径为 /user/profile 时,路由匹配成功。
如果请求方法为 POST,即使路径相同,也不能直接按照 GET 路由执行。
可以将基本匹配关系表示为:
其中:
-
\(M_R\):路由规则中的请求方法。
-
\(M_Q\):当前请求方法。
-
\(P_R\):路由规则路径。
-
\(P_Q\):当前请求路径。
-
\(\sim\):路径匹配关系。
10.7.1 静态路由匹配
静态路由采用路径完全匹配方式。
例如:
注册路径:/user/profile
请求路径:/user/profile
两者一致时,匹配成功。
可以通过以下程序实现基础匹配:
<?php
class RouteMatcher
{
public function matchStatic(
$routePath,
$requestPath
) {
return $routePath === $requestPath;
}
}
10.7.2 动态路由匹配
动态路由需要识别路径中的参数标记,并将实际 URL 中对应位置的内容提取出来。
例如:
路由规则:/user/{id}
请求路径:/user/1001
匹配后得到:
array(
'id' => '1001'
);
动态路由匹配可以通过将参数标记转换为正则表达式实现。
基础示例:
<?php
class RouteMatcher
{
public function match(
$routePath,
$requestPath
) {
$names = array();
$pattern = preg_replace_callback(
'/\{([a-zA-Z_][a-zA-Z0-9_]*)\}/',
function ($matches) use (&$names) {
$names[] = $matches[1];
return '([^/]+)';
},
$routePath
);
$pattern = '#^' . $pattern . '$#';
if (!preg_match(
$pattern,
$requestPath,
$matches
)) {
return false;
}
array_shift($matches);
$params = array();
foreach ($names as $index => $name) {
$params[$name] = $matches[$index];
}
return $params;
}
}
这里的实现展示了动态参数提取的基本过程。实际工程还需要对路由路径中的正则特殊字符进行转义,并明确参数编码、重复参数名和约束表达式的处理规则。
10.7.3 请求方法与路径联合匹配
路由匹配程序需要同时检查请求方法和请求路径。
例如:
$route = array(
'method' => 'GET',
'path' => '/user/{id}',
'controller' => 'UserController',
'action' => 'show'
);
当前请求:
GET /user/1001
匹配成功后,路由程序返回目标控制器、执行方法和动态参数。
而:
POST /user/1001
不应匹配这条 GET 路由。
10.8 路由参数传递机制
路由参数传递负责将路由解析过程中提取的数据交给目标控制器。
路由参数主要包括两类:
一类是动态路径参数,例如 /user/{id} 中的 id;另一类是 URL 查询参数,例如 /user/profile?id=1001 中的 id。
两者来源不同,不能在路由解析时混为一谈。
动态路径参数由路由匹配程序提取,查询参数由 HTTP 请求对象负责读取。
例如:
/user/1001?type=basic
其中:
$routeParams = array(
'id' => '1001'
);
查询参数则由请求对象读取:
$queryParams = array(
'type' => 'basic'
);
路由解析结果可以采用以下结构:
$routeResult = array(
'controller' => 'UserController',
'action' => 'show',
'params' => array(
'id' => '1001'
)
);
应用运行程序取得解析结果后,负责定位控制器并调用对应方法。
路由管理组件只负责提供参数,不负责决定参数在业务逻辑中的含义。
10.9 路由分组管理
当应用程序中的路由数量增加时,直接注册所有路由会使配置文件和程序代码变得冗长。路由分组机制可以将具有共同路径前缀或共同配置的路由组织起来,减少重复定义。
例如,后台管理系统中的访问路径通常具有共同前缀:
/admin
/admin/user
/admin/article
/admin/system
可以将这些路由组织到一个分组中:
$router->group('/admin', function ($route) {
$route->get(
'/user',
'AdminUserController@index'
);
$route->get(
'/article',
'AdminArticleController@index'
);
$route->get(
'/system',
'AdminSystemController@index'
);
});
分组注册后,路由管理程序需要将分组前缀与内部路由路径组合起来,形成完整路径:
/admin/user
/admin/article
/admin/system
10.9.1 路由分组类设计
RouteGroup.php 用于管理分组前缀及其内部注册行为。
基础工程实现示例:
<?php
class RouteGroup
{
protected $router;
protected $prefix;
public function __construct(
Router $router,
$prefix
) {
$this->router = $router;
$this->prefix = $prefix;
}
protected function mergePath($path)
{
return '/' . trim(
$this->prefix . '/' . $path,
'/'
);
}
public function get($path, $handler)
{
return $this->router->get(
$this->mergePath($path),
$handler
);
}
public function post($path, $handler)
{
return $this->router->post(
$this->mergePath($path),
$handler
);
}
}
该示例展示了分组路径组合的基本职责。路由管理类需要提供对应的 group() 接口,并将分组回调与 RouteGroup 对象关联起来。
路由分组的核心作用是组织路由路径,不应在没有明确设计的情况下,将权限判断、身份认证或业务处理逻辑自动加入分组机制。
10.10 路由解析结果与应用程序调度
路由匹配成功后,路由管理组件需要向应用运行程序返回统一格式的解析结果。
解析结果至少应包含:
$routeResult = array(
'controller' => 'UserController',
'action' => 'show',
'params' => array(
'id' => '1001'
)
);
应用运行程序根据解析结果完成控制器定位和方法调用。
路由管理程序与应用运行程序之间的关系可以表示为:
路由管理类可以提供统一的 dispatch() 方法,作为路由解析与应用程序调度之间的接口。
其基本处理步骤如下:
-
从请求对象中获取 HTTP 请求方法和 URL 路径。
-
对请求路径进行标准化处理。
-
遍历已经注册的路由规则。
-
检查请求方法是否一致。
-
执行静态路径或动态路径匹配。
-
提取动态路径参数。
-
生成统一的路由解析结果。
-
将结果返回给应用运行程序。
路由管理类不应直接承担控制器内部的执行任务。控制器实例化和方法调用仍由应用运行程序负责,这样可以保持路由组件与应用执行机制之间的职责边界。
10.11 路由管理组件的启动与运行流程
路由管理组件需要在框架启动阶段完成初始化,并在请求处理阶段参与应用程序调度。
启动阶段主要完成路由管理类实例化、路由规则加载和路由组件注册。
请求运行阶段则根据当前请求执行路由匹配,并将解析结果交给应用程序。
其中,未匹配结果应由应用运行程序统一处理。具体返回何种 HTTP 状态码、是否使用自定义错误页面,应由后续异常处理和响应机制的设计确定,不应由路由匹配程序擅自决定。
10.12 路由管理组件的工程验证
路由管理组件完成工程实现后,需要分别验证路由注册、路径解析、请求方法匹配、动态参数提取和路由分组等功能。
验证应当围绕实际代码和实际运行结果展开,不能仅凭代码结构判断路由功能已经正常运行。
10.12.1 路由注册验证
检查配置文件注册和程序注册是否能够生成统一的路由规则结构。
验证内容包括:
-
GET、POST、PUT、DELETE 等路由注册接口是否正常。
-
配置文件是否能够正确加载。
-
注册后的路由信息是否能够统一读取。
-
无效路由配置是否能够被识别。
10.12.2 路径解析验证
分别使用普通路径、根路径和包含查询字符串的 URL 进行测试,检查路径标准化结果是否符合预先定义的规则。
同时检查 URL 编码路径和末尾斜杠的处理情况。
10.12.3 动态路由验证
使用以下规则:
/user/{id}
测试不同请求路径:
| 请求路径 | 预期结果 |
|---|---|
/user/1001 |
匹配成功,提取 id=1001 |
/user/2002 |
匹配成功,提取 id=2002 |
/user/ |
不匹配 |
/article/1001 |
不匹配 |
10.12.4 请求方法验证
针对同一 URL 注册不同请求方法,检查路由管理程序能否根据请求方法进行区分,避免将 GET 路由错误匹配为 POST 路由。
10.12.5 路由分组验证
检查分组前缀与内部路径是否能够正确组合,确认分组内部路由最终形成的完整 URL 与定义一致。
10.12.6 应用调度验证
将路由解析结果交给应用运行程序,检查控制器定位、方法调用和参数传递是否符合设计要求。
实际工程验证按照既定开发流程执行:先检查工程文件和依赖关系,再实施代码,完成本地 PHP 语法检查和适用的功能测试,之后同步服务器进行运行验证,发现问题及时修复并复测。没有经过对应阶段验证的功能,不应标记为已验收。
10.13 路由管理组件的工程边界
路由管理组件负责 URL 地址与应用控制程序之间的映射,不负责替代其他框架组件。
其工程边界主要体现在以下方面。
路由注册负责建立访问路径与目标程序之间的对应关系,不负责实现控制器业务功能。
路由解析负责识别请求路径及其动态参数,不负责处理 HTTP 请求主体中的业务数据。
路由匹配负责根据请求方法和路径查找对应规则,不负责判断用户是否具有业务操作权限。
路由分组负责组织具有共同路径结构的路由,不自动承担身份认证、权限控制或业务逻辑。
路由调度负责向应用运行程序提供解析结果,不直接取代应用运行程序的控制器实例化和方法调用职责。
通过上述职责划分,路由管理组件能够与请求响应组件、自动加载组件及应用运行管理程序形成相对独立的协作关系。
本章建立了 WangStruct Framework 的基础路由管理机制,明确了路由规则的数据结构、注册方式、路径解析、静态与动态匹配、参数传递、路由分组以及应用调度接口,为后续应用控制程序的组织和执行提供统一的访问路径管理基础。


