路由 ¶

有了资源和控制器类，你可以使用类似 http://localhost/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 规则来支持为指定控制器(s)路由和 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',
        ]
    ],
],