動態路由
動態路由就是把 url
的請求優雅地對應到你想要執行的操作方法。
EasySwoole
的動態路由是基于 FastRoute 實現,與其路由規則保持一致。
示例代碼
新建文件 App\HttpController\Router.php
,(從框架 3.4.x
版本開始,用戶可能不需要新建此文件。如果用戶在安裝時選擇了釋放 Router.php
則不必新建,如果沒有,請自行新建):
<?php
namespace App\HttpController;
use EasySwoole\Component\Context\ContextManager;
use EasySwoole\Http\AbstractInterface\AbstractRouter;
use EasySwoole\Http\Request;
use EasySwoole\Http\Response;
use FastRoute\RouteCollector;
class Router extends AbstractRouter
{
function initialize(RouteCollector $routeCollector)
{
$routeCollector->get('/user', '/user');
$routeCollector->get('/user1', '/User/user1');
$routeCollector->get('/rpc', '/Rpc/index');
$routeCollector->get('/', function (Request $request, Response $response) {
$response->write('this is router home');
return false; // 不再往下請求,結束此次響應
});
// $routeCollector->get('/', '/index');
$routeCollector->get('/test', function (Request $request, Response $response) {
$response->write('this is router test.');
return '/child';
});
$routeCollector->get('/child', function (Request $request, Response $response) {
$response->write('this is router child.');
return false; // 不再往下請求,結束此次響應
});
$routeCollector->get('/mtest1', '/a/b/c/d/index/index');
$routeCollector->get('/mtest2', '/A/B/C/D/Index/index');
// 從 `easyswoole/http 2.x 版本開始,綁定的參數將由框架內部進行組裝到框架的 `Context(上下文)` 數據之中,具體使用請看下文。
$routeCollector->get('/user/{id:\d+}', function (Request $request, Response $response) {
// 獲取 id 參數
$context = ContextManager::getInstance()->get(Router::PARSE_PARAMS_CONTEXT_KEY);
$id = $context['id'];
$response->write("this is router user, id is {$id}");
return false; // 不再往下請求,結束此次響應
});
}
}
創建路由
EasySwoole
路由接受一個 URI
和一個 Handler
(這個 Handler
可以是一個 閉包callback
或者一個 字符串string
),提供了一個簡單優雅的方法來定義路由和行為,而不需要復雜的路由配置文件:
<?php
namespace App\HttpController;
use EasySwoole\Http\AbstractInterface\AbstractRouter;
use EasySwoole\Http\Request;
use EasySwoole\Http\Response;
use FastRoute\RouteCollector;
class Router extends AbstractRouter
{
function initialize(RouteCollector $routeCollector)
{
$routeCollector->get('/greeting', function (Request $request, Response $response) {
$response->write('Hello World');
return false;
});
}
}
從上面可以看到,創建匹配 HTTP
請求方法 GET
的路由的方法很簡單,如下:
$routeCollector->get($uri, $handler);
-
$uri
為字符串string
格式 -
$handler
為閉包callback
或者字符串string
格式,當為字符串
格式時則表示是與控制類的action
相關聯。
針對上述方法的參數的含義說明如下:
- 當
$handler
為/xxx
時,則對應關聯執行App\HttpController\Index.php
類的xxx()
方法。 - 當
$handler
為/xxx/xxx/xxx/xxx
或者/Xxx/Xxx/Xxx/xxx
時,二者其實等價,都對應關聯執行App\HttpController\Xxx\Xxx\Xxx.php
類的xxx()
方法。 - 當
$handler
為/xxx/xxx/xxx/Xxx
或者/Xxx/Xxx/Xxx/Xxx
時,二者也等價,都對應關聯執行App\HttpController\Xxx\Xxx\Xxx.php
類的Xxx()
方法。
綜上所述,其實 $handler
中最后一個 /
后的名稱一定為控制器類的 action
名稱 (且不會轉換大小寫),前面的則為對應控制器所在命名空間及路徑,控制器名稱及文件夾名稱請務必以 大寫字母
開頭,否則路由將不能匹配到對應的執行方法。而對于 $uri
則沒有特殊要求。$handler
指定路由匹配成功后需要處理的方法,可以傳入一個閉包,當傳入閉包時一定要 注意處理完成之后要處理結束響應,否則請求會繼續 Dispatch
尋找對應的控制器來處理,當然如果利用這一點,也可以對某些請求進行處理后再交給控制器執行邏輯。
用戶在新建控制器類和文件夾時,請使用 大駝峰法
命名。如果使用回調函數方式處理路由,return false;
代表不繼續往下請求。
默認路由文件
默認路由文件位于 App\HttpController
目錄的 Router.php
文件。在 Router.php
文件可以定義我們常用的路由。對于大多數應用程序,也都是在 Router.php
文件定義路由。例如,你可以在瀏覽器中輸入 http://example.com/user
來訪問以下路由:
<?php
namespace App\HttpController;
use EasySwoole\Http\AbstractInterface\AbstractRouter;
use FastRoute\RouteCollector;
class Router extends AbstractRouter
{
function initialize(RouteCollector $routeCollector)
{
// 下面定義的路由將 /user URI 與 App\HttpController\User 類 的 index() action 相關聯
$routeCollector->get('/user', '/User/index');
}
}
添加額外的路由文件
上述已經提到 EasySwoole
框架默認的路由文件為 App\HttpController
目錄的 Router.php
文件。當我們想要添加額外的路由文件時,我們可以在 App
目錄新建一個目錄 Route
用來統一存放額外的路由,然后在 App\HttpController
目錄的 Router.php
文件中進行注冊。如下:
在 App\Route
目錄(前提:已自行創建好此目錄),新增 ApiRouter.php
文件,該文件內容如下:
<?php
namespace App\Route;
use FastRoute\RouteCollector;
class ApiRouter
{
public function initialize(RouteCollector &$routeCollector)
{
$routeCollector->addGroup('/api/v1/user', function (RouteCollector $routeCollector) {
$routeCollector->post('/create', '/Api/User/create');
$routeCollector->post('/delete/{id:\d+}', '/Api/User/delete');
$routeCollector->post('/update/{id:\d+}', '/Api/User/update');
$routeCollector->post('/query', '/Api/User/query');
});
}
}
在 App\HttpController
目錄的 Router.php
文件中進行注冊額外的路由:
<?php
namespace App\HttpController;
use App\Route\ApiRouter;
use EasySwoole\Http\AbstractInterface\AbstractRouter;
use FastRoute\RouteCollector;
class Router extends AbstractRouter
{
function initialize(RouteCollector $routeCollector)
{
// 注冊額外的路由
(new ApiRouter())->initialize($routeCollector);
}
}
依賴注入
在路由的回調方法中,框架會自動將當前的 HTTP
請求和 HTTP
響應注入依賴到你的路由回調中:
<?php
namespace App\HttpController;
use EasySwoole\Http\AbstractInterface\AbstractRouter;
use EasySwoole\Http\Request;
use EasySwoole\Http\Response;
use FastRoute\RouteCollector;
class Router extends AbstractRouter
{
function initialize(RouteCollector $routeCollector)
{
$routeCollector->get('/greeting', function (Request $request, Response $response) {
$response->write('Hello World');
return false;
});
}
}
注入的 HTTP
請求對象可用來讀取請求參數等,注入的 HTTP
響應對象可用來指定返回給客戶端的響應內容。
匹配 HTTP 方法
路由器允許你注冊能響應任何 HTTP
請求的路由
$routeCollector->get($uri, $handler);
// 等價于
$routeCollector->addRoute('GET', $uri, $handler);
$routeCollector->post($uri, $handler);
// 等價于
$routeCollector->addRoute('POST', $uri, $handler);
$routeCollector->put($uri, $handler);
// 等價于
$routeCollector->addRoute('PUT', $uri, $handler);
$routeCollector->patch($uri, $handler);
// 等價于
$routeCollector->addRoute('PATCH', $uri, $handler);
$routeCollector->delete($uri, $handler);
// 等價于
$routeCollector->addRoute('DELETE', $uri, $handler);
$routeCollector->head($uri, $handler);
// 等價于
$routeCollector->addRoute('HEAD', $uri, $handler);
$routeCollector->addRoute('OPTIONS', $uri, $handler);
有的時候你可能需要注冊一個可響應多種 HTTP
請求的路由,這時你可以使用 addRoute
方法注冊一個實現響應多種 HTTP
請求的路由:
$routeCollector->addRoute(['GET', 'POST'], $uri, $handler);
addRoute 方法說明
方法格式如下:
$routeCollector->addRoute($http, $uri, $handler);
-
$httpMethd
(HTTP
請求方法)參數必須是大寫
的HTTP
請求方法字符串或者字符串數組,如GET
、POST
、PUT
、PATCH
、DELETE
、HEAD
、OPTIONS
。 -
$uri
參數需要傳入一個URI
,格式如:/路徑名稱/{參數名稱:匹配規則}
,占位符:
用于限制約束路由參數。 -
$handler
參數需要傳入一個字符串或閉包,上述已說明,就不做過多闡述。
示例如下:
$routeCollector->addRoute('GET', $uri, $handler);
$routeCollector->addRoute(['GET', 'POST'], $uri, $handler);
路由參數
必需參數
有時你將需要捕獲路由內的 URI
段。例如,你可能需要從 URL
中捕獲用戶的 ID
。你可以通過定義路由參數來做到這一點:
<?php
namespace App\HttpController;
use EasySwoole\Component\Context\ContextManager;
use EasySwoole\Http\AbstractInterface\AbstractRouter;
use EasySwoole\Http\Request;
use EasySwoole\Http\Response;
use FastRoute\RouteCollector;
class Router extends AbstractRouter
{
function initialize(RouteCollector $routeCollector)
{
$routeCollector->get('/user/{id}', function (Request $request, Response $response) {
$context = ContextManager::getInstance()->get(Router::PARSE_PARAMS_CONTEXT_KEY);
$id = $context['id'];
$response->write("User {$id}");
return false;
});
}
}
也可以根據你的需要在路由中定義多個參數:
<?php
namespace App\HttpController;
use EasySwoole\Component\Context\ContextManager;
use EasySwoole\Http\AbstractInterface\AbstractRouter;
use EasySwoole\Http\Request;
use EasySwoole\Http\Response;
use FastRoute\RouteCollector;
class Router extends AbstractRouter
{
function initialize(RouteCollector $routeCollector)
{
$routeCollector->get('/posts/{post}/comments/{comment}', function (Request $request, Response $response) {
$context = ContextManager::getInstance()->get(Router::PARSE_PARAMS_CONTEXT_KEY);
$post = $context['post'];
$comment = $context['comment'];
$response->write("post: {$post}, comment: {$comment}");
return false;
});
}
}
路由的參數通常都會被放在 {}
,并且參數名只能為字母。
可選參數
有時,你可能需要指定一個路由參數,但你希望這個參數是可選的。你可以在加上 []
標記將 /{參數}
包含起來來實現:
<?php
namespace App\HttpController;
use EasySwoole\Component\Context\ContextManager;
use EasySwoole\Http\AbstractInterface\AbstractRouter;
use EasySwoole\Http\Request;
use EasySwoole\Http\Response;
use FastRoute\RouteCollector;
class Router extends AbstractRouter
{
function initialize(RouteCollector $routeCollector)
{
$routeCollector->get('/user[/{name}]', function (Request $request, Response $response) {
$context = ContextManager::getInstance()->get(Router::PARSE_PARAMS_CONTEXT_KEY);
$name = $context['name'] ?? '';
$response->write("name: {$name}");
return false;
});
// 上述路由等價于下面2個路由
$routeCollector->get('/user', function (Request $request, Response $response) {
// your code
return false;
});
$routeCollector->get('/user/{name}', function (Request $request, Response $response) {
$context = ContextManager::getInstance()->get(Router::PARSE_PARAMS_CONTEXT_KEY);
$name = $context['name'];
$response->write("name: {$name}");
return false;
});
$routeCollector->get('/user[/{id}[/{name}]]', function (Request $request, Response $response) {
$context = ContextManager::getInstance()->get(Router::PARSE_PARAMS_CONTEXT_KEY);
$name = $context['name'] ?? '';
$response->write("name: {$name}");
return false;
});
}
}
獲取路由參數
從 Context 中獲取路由參數(路由參數的默認獲取機制)
可以從 \EasySwoole\Component\Context\ContextManager::getInstance()->get(Router::PARSE_PARAMS_CONTEXT_KEY)
上下文中獲取路由參數。此配置項是easyswoole/http 2.x
版本開始的默認配置。如需設置需在 App\HttpController\Router.php
添加如下代碼:
$this->parseParams(\EasySwoole\Http\AbstractInterface\AbstractRouter::PARSE_PARAMS_IN_CONTEXT);
具體使用示例:
<?php
namespace App\HttpController;
use EasySwoole\Component\Context\ContextManager;
use EasySwoole\Http\AbstractInterface\AbstractRouter;
use EasySwoole\Http\Request;
use EasySwoole\Http\Response;
use FastRoute\RouteCollector;
class Router extends AbstractRouter
{
function initialize(RouteCollector $routeCollector)
{
// /user/1
$routeCollector->get('/user/{id}', function (Request $request, Response $response) {
$context = ContextManager::getInstance()->get(Router::PARSE_PARAMS_CONTEXT_KEY);
$id = $context['id']; // 1
$response->write("id: {$id}");
return false;
});
}
}
從 Query Param 中獲取路由參數
如果想從 Query Param 中獲取路由參數,可使用這個 $this->request()->getQueryParams()
方法進行獲取,但是需要先在 App\HttpController\Router.php
中進行設置:
$this->parseParams(\EasySwoole\Http\AbstractInterface\AbstractRouter::PARSE_PARAMS_IN_GET);
具體設置如下:
<?php
namespace App\HttpController;
use EasySwoole\Http\AbstractInterface\AbstractRouter;
use EasySwoole\Http\Request;
use EasySwoole\Http\Response;
use FastRoute\RouteCollector;
class Router extends AbstractRouter
{
function initialize(RouteCollector $routeCollector)
{
$this->parseParams(Router::PARSE_PARAMS_IN_GET);
// /user/1
$routeCollector->get('/user/{id:\d+}', function (Request $request, Response $response) {
$id = $request->getQueryParam('id'); // 1
$response->write("id: {$id}");
return false;
});
}
}
從 POST 請求參數中獲取路由參數
如果想從 POST 請求參數中獲取路由參數,可使用這個 $this->request()->getParsedBody()
方法進行獲取,但是需要先在 App\HttpController\Router.php
中進行設置:
$this->parseParams(\EasySwoole\Http\AbstractInterface\AbstractRouter::PARSE_PARAMS_IN_POST);
具體設置如下:
<?php
namespace App\HttpController;
use EasySwoole\Http\AbstractInterface\AbstractRouter;
use EasySwoole\Http\Request;
use EasySwoole\Http\Response;
use FastRoute\RouteCollector;
class Router extends AbstractRouter
{
function initialize(RouteCollector $routeCollector)
{
$this->parseParams(Router::PARSE_PARAMS_IN_POST);
// /user/1
$routeCollector->get('/user/{id:\d+}', function (Request $request, Response $response) {
$id = $request->getParsedBody('id'); // 1
$response->write("id: {$id}");
return false;
});
}
}
NONE
不獲取路由參數時,可以在 App\HttpController\Router.php
中進行設置:
$this->parseParams(\EasySwoole\Http\AbstractInterface\AbstractRouter::PARSE_PARAMS_NONE);
注意:以上 4 種設置,用戶只能設置 1 種。
Router
默認使用的設置是從請求上下文 Context 中獲取路由參數。
easyswoole/http 2.x
之前版本綁定的參數將由框架內部進行組裝到框架的 Query Param
數據之中,調用方式如下:
<?php
namespace App\HttpController;
use EasySwoole\Http\AbstractInterface\AbstractRouter;
use EasySwoole\Http\Request;
use EasySwoole\Http\Response;
use FastRoute\RouteCollector;
class Router extends AbstractRouter
{
function initialize(RouteCollector $routeCollector)
{
// /user/1
$routeCollector->get('/user/{id:\d+}', function (Request $request, Response $response) {
$id = $request->getQueryParam('id'); // 1
$response->write("id: {$id}");
return false;
});
}
}
參數約束驗證
你可以在路由參數后面添加正則表達式來限制路由參數的格式:
<?php
namespace App\HttpController;
use EasySwoole\Component\Context\ContextManager;
use EasySwoole\Http\AbstractInterface\AbstractRouter;
use EasySwoole\Http\Request;
use EasySwoole\Http\Response;
use FastRoute\RouteCollector;
class Router extends AbstractRouter
{
function initialize(RouteCollector $routeCollector)
{
$routeCollector->get('/user/{name:.+}', function (Request $request, Response $response) {
$context = ContextManager::getInstance()->get(Router::PARSE_PARAMS_CONTEXT_KEY);
$name = $context['name'];
$response->write("name: {$name}");
return false;
});
$routeCollector->get('/user1/{name:[A-Za-z]+}', function (Request $request, Response $response) {
$context = ContextManager::getInstance()->get(Router::PARSE_PARAMS_CONTEXT_KEY);
$name = $context['name'];
$response->write("name: {$name}");
return false;
});
// 將限制 `/users/` 后面的id參數,只能是數字 `[0-9]`
$routeCollector->get('/user/{id:\d+}', function (Request $request, Response $response) {
$context = ContextManager::getInstance()->get(Router::PARSE_PARAMS_CONTEXT_KEY);
$id = $context['id'];
$response->write("id: {$id}");
return false;
});
$routeCollector->get('/user1/{id:[0-9]+}', function (Request $request, Response $response) {
$context = ContextManager::getInstance()->get(Router::PARSE_PARAMS_CONTEXT_KEY);
$id = $context['id'];
$response->write("id: {$id}");
return false;
});
$routeCollector->get('/user2/{id:[0-9]+}/{name:[a-z]+}', function (Request $request, Response $response) {
$context = ContextManager::getInstance()->get(Router::PARSE_PARAMS_CONTEXT_KEY);
$id = $context['id'];
$name = $context['name'];
$response->write("id: {$id}, name: {$name}");
return false;
});
}
}
路由參數中的斜杠字符
路由允許除 /
之外的所有字符出現在路由參數值中。 你必須使用正則表達式明確允許 /
成為占位符的一部分:
<?php
namespace App\HttpController;
use EasySwoole\Component\Context\ContextManager;
use EasySwoole\Http\AbstractInterface\AbstractRouter;
use EasySwoole\Http\Request;
use EasySwoole\Http\Response;
use FastRoute\RouteCollector;
class Router extends AbstractRouter
{
function initialize(RouteCollector $routeCollector)
{
$routeCollector->get('/search/{search:.*}', function (Request $request, Response $response) {
$context = ContextManager::getInstance()->get(Router::PARSE_PARAMS_CONTEXT_KEY);
$search = $context['search'];
$response->write("search: {$search}");
return false;
});
}
}
路由分組
路由分組允許你共享 URI
前綴,而無需在每個單獨的路由上定義這些 URI` 前綴。
嵌套組嘗試智能地將 URI
前綴與其父組 “合并”。URI
前綴中的斜杠會在適當的地方自動添加。
<?php
use EasySwoole\Http\Request;
use EasySwoole\Http\Response;
use FastRoute\RouteCollector;
$routeCollector->addGroup('/admin', function (RouteCollector $collector) {
$collector->addRoute('GET', '/do-something', function (Request $request, Response $response) {
$response->write('this is do-something');
return false;
});
$collector->addRoute('GET', '/do-another-thing', function (Request $request, Response $response) {
$response->write('this is do-another-thing');
return false;
});
$collector->addRoute('GET', '/do-something-else', function (Request $request, Response $response) {
$response->write('do-something-else');
return false;
});
});
// 和上述路由等價
$routeCollector->addRoute('GET', '/admin/do-something', function (Request $request, Response $response) {
$response->write('this is do-something');
return false;
});
$routeCollector->addRoute('GET', '/admin/do-another-thing', function (Request $request, Response $response) {
$response->write('this is do-another-thing');
return false;
});
$routeCollector->addRoute('GET', '/admin/do-something-else', function (Request $request, Response $response) {
$response->write('do-something-else');
return false;
});
特殊的路由
從路由調度到其他路由
如果要定一個調度到另一個 URI
的路由,可以使用 return
的方式,可快速實現類似重定向的功能,而不需要去定義完整的路由或者控制器:
$routeCollector->addRoute('GET', '/here', function (Request $request, Response $response) {
return '/there';
});
use EasySwoole\Http\Request;
use EasySwoole\Http\Response;
use FastRoute\RouteCollector;
$routeCollector->addGroup('/admin', function (RouteCollector $collector) {
// /admin/test?version=1
// /admin/test?version=2
// /admin/test?version=3
$collector->addRoute('GET', '/test', function (Request $request, Response $response) {
$version = $request->getQueryParam('version');
if ($version == 1) {
$path = '/V1' . $request->getUri()->getPath(); // "/V1/admin/test"
} else {
// /V2/admin/test
$path = '/V2' . $request->getUri()->getPath(); // "/V2/admin/test"
}
// return "/V1/admin/test";
// return "/V2/admin/test";
return $path;
});
});
// 注意:/admins/index?version=x 不能匹配到下面這個 action 路由配置參數
// 需要單獨配置路由,如下所示:即執行對應的 App\HttpController\V1\Admins.php 類的 index() 方法
// $routeCollector->addRoute('GET', '/admins/index', '/V1/Admin/index');
$routeCollector->addGroup('/admins', function (RouteCollector $collector) {
// /admin/test?version=1
// /admin/test?version=2
// /admin/test?version=3
$collector->addRoute('GET', '/{action}', function (Request $request, Response $response) {
$version = $request->getQueryParam('version');
if ($version == 1) {
$path = '/V1' . $request->getUri()->getPath(); // "/V1/admins/test"
} else {
$path = '/V2' . $request->getUri()->getPath(); // "/V2/admins/test"
}
// return "/V1/admin/test";
// return "/V2/admin/test";
return $path;
});
});
全局模式攔截
在 Router.php
加入以下代碼,即可開啟全局模式攔截
$this->setGlobalMode(true);
全局模式攔截下,路由將只匹配 Router.php
中指定的 $handler
的控制器方法進行響應,將不會執行框架的默認解析。
異常錯誤處理
通過以下 2
個方法,可設置 路由HTTP請求方法無法匹配
以及 路由無法匹配
的處理機制:
在 Router.php
加入以下代碼:
<?php
use EasySwoole\Http\Request;
use EasySwoole\Http\Response;
// 路由HTTP請求方法無法匹配
$this->setMethodNotAllowCallBack(function (Request $request, Response $response) {
$response->withStatus(404);
return false; // 結束此次響應
});
// 路由未知,無法匹配
$this->setRouterNotFoundCallBack(function (Request $request, Response $response){
$response->withStatus(404);
return 'index'; // 重定向到 index 路由
});
該回調函數只針對于 fastRoute
未匹配狀況,如果回調里面不結束該請求響應,則該次請求將會繼續進行 Dispatch
并嘗試尋找對應的控制器進行響應處理。