路由 ¶

當資源和控制器類別準備就緒後，您可以使用類似 https://127.0.0.1/index.php?r=user/create 的 URL 訪問資源，這與您在一般 Web 應用程式中所做的操作類似。

實際上，您通常希望啟用美觀 URL 並利用 HTTP 動詞。例如，請求 POST /users 將表示訪問 user/create 動作。這可以通過在應用程式配置中配置 urlManager 應用程式組件 來輕鬆完成，如下所示

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

與 Web 應用程式的 URL 管理相比，上面的主要新內容是使用 yii\rest\UrlRule 來路由 RESTful API 請求。這個特殊的 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 和 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'],
],

您也可以配置 patterns 或 extraPatterns 以重新定義現有模式或添加此規則支持的新模式。例如，要通過端點 GET /users/search 支持新的動作 search，請配置 extraPatterns 選項如下，

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

您可能已經注意到控制器 ID user 在端點 URL 中以複數形式 users 出現。這是因為 yii\rest\UrlRule 在創建子 URL 規則時會自動將控制器 ID 複數化。您可以通過將 yii\rest\UrlRule::$pluralize 設置為 false 來禁用此行為。

資訊：控制器 ID 的複數化由 yii\helpers\Inflector::pluralize() 完成。該方法遵循特殊的複數化規則。例如，單詞 box 將被複數化為 boxes 而不是 boxs。

如果自動複數化不符合您的要求，您也可以配置 yii\rest\UrlRule::$controller 屬性，以明確指定如何將端點 URL 中使用的名稱映射到控制器 ID。例如，以下代碼將名稱 u 映射到控制器 ID user。

[
    'class' => 'yii\rest\UrlRule',
    'controller' => ['u' => 'user'],
]

包含規則的額外配置 ¶

指定應用於 yii\rest\UrlRule 中包含的每個規則的額外配置可能很有用。一個很好的例子是指定 expand 參數的預設值

[
    'class' => 'yii\rest\UrlRule',
    'controller' => ['user'],
    'ruleConfig' => [
        'class' => 'yii\web\UrlRule',
        'defaults' => [
            'expand' => 'profile',
        ]
    ],
],