Yii2.0 RESTful Web服務（4）

AlanJager發表於2020-04-07
RESTWeb

路由

隨著資源和控制器類準備，您可以使用URL如 http://localhost/index.php?r=user/create訪問資源，類似於你可以用正常的Web應用程式做法。

在實踐中，你通常要用美觀的URL並採取有優勢的HTTP動詞。 例如，請求POST /users意味著訪問user/create動作。 這可以很容易地通過配置urlManager應用程式元件來完成 如下所示：

'urlManager' => [
    'enablePrettyUrl' => true,
    'enableStrictParsing' => true,
    'showScriptName' => false,
    'rules' => [
        ['class' => 'yii\rest\UrlRule', 'controller' => 'user'],
    ],
]

將enablePrettyUrl設定為true，譬如訪問www.xxxxx.com時不會直接顯示www.xxxxx.com/site/index.php 而是需要在rules中增加對應的配置。

將enableStrictParsing設定為true，該項表示訪問的Url必須至少匹配一個路由規則，否則認定為無效，且在設定enablePrettyUrl為true後生效。

將showScriptName設定為true，表示在Url保留入口指令碼index.php。

相比於URL管理的Web應用程式上述主要的新東西是通過RESTful API 請求yii\rest\UrlRule。這個特殊的URL規則類將會 建立一整套子URL規則來支援路由和URL建立的指定的控制器。 例如， 上面的程式碼中是大致按照下面的規則

:

[
    'PUT,PATCH users/<id>' => 'user/update',
    'DELETE users/<id>' => 'user/delete',
    'GET,HEAD users/<id>' => 'user/view',
    'POST users' => 'user/create',
    'GET,HEAD users' => 'user/index',
    'users/<id>' => 'user/options',
    'users' => 'user/options',
]

該規則支援下面的API末端:

  • GET /users: 逐頁列出所有使用者；
  • HEAD /users: 顯示使用者列表的概要資訊；
  • POST /users: 建立一個新使用者；
  • GET /users/123: 返回使用者為123的詳細資訊;
  • HEAD /users/123: 顯示使用者 123 的概述資訊;
  • PATCH /users/123 and PUT /users/123: 更新使用者123;
  • DELETE /users/123: 刪除使用者123;
  • OPTIONS /users: 顯示關於末端 /users 支援的動詞;
  • OPTIONS /users/123: 顯示有關末端 /users/123 支援的動詞。

您可以通過配置 only 和 except 選項來明確列出哪些行為支援， 哪些行為禁用。例如，

[
    'class' => 'yii\rest\UrlRule',
    'controller' => 'user',
    'except' => ['delete', 'create', 'update'],
],

如果UserController是繼承自ActiveController，對應的方法的禁用也可以通過yii\rest\ActiveController::actions()方法宣告（Yii2.0 RESTful Controller相關）

您也可以通過配置 patterns 或 extraPatterns 重新定義現有的模式或新增此規則支援的新模式。 例如，通過末端 GET /users/search 可以支援新行為 search， 按照如下配置 extraPatterns 選項，

[
    'class' => 'yii\rest\UrlRule',
    'controller' => 'user',
    'extraPatterns' => [
        'GET search' => 'search',
    ],

您可能已經注意到控制器IDuser以複數形式出現在users末端。 這是因為 yii\rest\UrlRule 能夠為他們使用的末端全自動複數化控制器ID。 您可以通過設定 yii\rest\UrlRule::pluralize 為false 來禁用此行為，如果您想使用一些特殊的名字您可以通過配置 yii\rest\UrlRule::controller 屬性。

yii\rest\UrlRule::controller的值在通常情況下是直接使用了urlManager中配置在rules中的user為字首，當然Yii2.0也提供了兩種自定義方式，一種是傳入鍵值對陣列譬如將yii\rest\UrlRule::controller賦值為"['u' => 'user' ]" 這樣後續的訪問則將u視為控制器id，另外一種則是輸入一個陣列譬如"['user', 'player']" 這樣就會生成所有傳入值對應的路由規則。Yii在路由規則這邊採用了一種比較簡單的的方式進行處理，如果採用簡單粗暴的方式，Yii完全可以犧牲一定的開發便利性，在程式碼層面提高路由規則的效能，例如直接採用正規表示式的方式，但是Yii沒有這樣做。Yii在urlManager::init()的時候對所有路由進行了快取，很好的穩定了效能與開發便利性。

相關文章