Yii2.0 RESTful风格的Controller与ActiveController

yii\rest\Controller提供的大多数RESTful API功能通过过滤器实现. 特别是以下过滤器会按顺序执行：

• yii\filters\ContentNegotiator: 支持内容协商。
• yii\filters\VerbFilter: 支持HTTP 方法验证;
• yii\filters\AuthMethod: 支持用户认证;
• yii\filters\RateLimiter: 支持频率限制.

这些过滤器都在yii\rest\Controller::behaviors()方法中声明。原本的声明如下：

    /**
     * @inheritdoc
     */
    public function behaviors()
    {
        return [
            ‘contentNegotiator‘ => [
                ‘class‘ => ContentNegotiator::className(),
                ‘formats‘ => [
                    ‘application/json‘ => Response::FORMAT_JSON,
                    ‘application/xml‘ => Response::FORMAT_XML,
                ],
            ],
            ‘verbFilter‘ => [
                ‘class‘ => VerbFilter::className(),
                ‘actions‘ => $this->verbs(),
            ],
            ‘authenticator‘ => [
                ‘class‘ => CompositeAuth::className(),
            ],
            ‘rateLimiter‘ => [
                ‘class‘ => RateLimiter::className(),
            ],
        ];
    }

首先是yii\filters\ContentNegotiator过滤器，该过滤器是用于内容协商的，例如，
如果一个 RESTful API 请求中包含以下 header，

Accept: application/json; q=1.0, */*; q=0.1

将会得到JSON格式的响应，幕后，执行一个 RESTful API 控制器动作之前，yii\filters\ContentNegotiator
filter 将检查 HTTP header 在请求时和配置 yii\web\Response::format
为 json。 之后的动作被执行并返回得到的资源对象或集合， yii\rest\Serializer
将结果转换成一个数组。最后，yii\web\JsonResponseFormatter 该数组将序列化为JSON字符串，并将其包括在响应主体。

之后将会执行yii\filters\VerbFilter，这一步是对动词的过滤，参考yii\rest\ActiveController中的声明：

    /**
     * @inheritdoc
     */
    protected function verbs()
    {
        return [
            ‘index‘ => [‘GET‘, ‘HEAD‘],
            ‘view‘ => [‘GET‘, ‘HEAD‘],
            ‘create‘ => [‘POST‘],
            ‘update‘ => [‘PUT‘, ‘PATCH‘],
            ‘delete‘ => [‘DELETE‘],
        ];
    }

所谓的动词即是用户发出的请求的类型，由此对应不同的操作。

然后是yii\filters\AuthMethod和Web应用不同，RESTful
APIs 通常是无状态的，也就意味着不应使用sessions 或 cookies， 因此每个请求应附带某种授权凭证，因为用户授权状态可能没通过sessions 或 cookies维护， 常用的做法是每个请求都发送一个秘密的access token来认证用户，由于access token可以唯一识别和认证用户。

最后是yii\filters\RateLimiter为防止滥用，你应该考虑增加速率限制到您的API。
例如，您可以限制每个用户的API的使用是在10分钟内最多100次的API调用。 如果一个用户同一个时间段内太多的请求被接收， 将返回响应状态代码 429 (这意味着过多的请求)。

要启用速率限制, yii\web\User::identityClass 应该实现 yii\filters\RateLimitInterface. 这个接口需要实现以下三个方法：

• getRateLimit(): 返回允许的请求的最大数目及时间，例如，[100,
600] 表示在600秒内最多100次的API调用。
• loadAllowance(): 返回剩余的允许的请求和相应的UNIX时间戳数 当最后一次速率限制检查时。
• saveAllowance(): 保存允许剩余的请求数和当前的UNIX时间戳。

你可以在user表中使用两列来记录容差和时间戳信息。 loadAllowance() 和 saveAllowance() 可以通过实现对符合当前身份验证的用户
的这两列值的读和保存。为了提高性能，你也可以 考虑使用缓存或NoSQL存储这些信息。

一旦 identity 实现所需的接口， Yii 会自动使用 yii\filters\RateLimiter 为 yii\rest\Controller 配置一个行为过滤器来执行速率限制检查。 如果速度超出限制 该速率限制器将抛出一个 yii\web\TooManyRequestsHttpException。 你可以在你的 REST 控制器类里配置速率限制，

public function behaviors()
{
    $behaviors = parent::behaviors();
    $behaviors[‘rateLimiter‘][‘enableRateLimitHeaders‘] = false;
    return $behaviors;
}

当速率限制被激活，默认情况下每个响应将包含以下HTTP头发送 目前的速率限制信息：

• X-Rate-Limit-Limit: 同一个时间段所允许的请求的最大数目;
• X-Rate-Limit-Remaining: 在当前时间段内剩余的请求的数量;
• X-Rate-Limit-Reset: 为了得到最大请求数所等待的秒数。

你可以禁用这些头信息通过配置 yii\filters\RateLimiter::enableRateLimitHeaders 为false, 就像在上面的代码示例所示。

yii\rest\ActiveController继承了yii\rest\Controller，在这个基础上，封装了基本的RESTful
API：

    /**
     * @inheritdoc
     */
    public function actions()
    {
        return [
            ‘index‘ => [
                ‘class‘ => ‘yii\rest\IndexAction‘,
                ‘modelClass‘ => $this->modelClass,
                ‘checkAccess‘ => [$this, ‘checkAccess‘],
            ],
            ‘view‘ => [
                ‘class‘ => ‘yii\rest\ViewAction‘,
                ‘modelClass‘ => $this->modelClass,
                ‘checkAccess‘ => [$this, ‘checkAccess‘],
            ],
            ‘create‘ => [
                ‘class‘ => ‘yii\rest\CreateAction‘,
                ‘modelClass‘ => $this->modelClass,
                ‘checkAccess‘ => [$this, ‘checkAccess‘],
                ‘scenario‘ => $this->createScenario,
            ],
            ‘update‘ => [
                ‘class‘ => ‘yii\rest\UpdateAction‘,
                ‘modelClass‘ => $this->modelClass,
                ‘checkAccess‘ => [$this, ‘checkAccess‘],
                ‘scenario‘ => $this->updateScenario,
            ],
            ‘delete‘ => [
                ‘class‘ => ‘yii\rest\DeleteAction‘,
                ‘modelClass‘ => $this->modelClass,
                ‘checkAccess‘ => [$this, ‘checkAccess‘],
            ],
            ‘options‘ => [
                ‘class‘ => ‘yii\rest\OptionsAction‘,
            ],
        ];
    }

在创建自己的RESTful API时可以通过对yii\rest\ActiveController::actions()的重载来对对应的方法进行禁用和允许的设置。同时要对yii\rest\ActiveController::verbs()进行重载：

    /**
     * @inheritdoc
     */
    protected function verbs()
    {
        return [
            ‘index‘ => [‘GET‘, ‘HEAD‘],
            ‘view‘ => [‘GET‘, ‘HEAD‘],
            ‘create‘ => [‘POST‘],
            ‘update‘ => [‘PUT‘, ‘PATCH‘],
            ‘delete‘ => [‘DELETE‘],
        ];
    }

用于处理不同的动作对应的HTTP请求方式。

最后yii\rest\ActiveController提供了一个yii\rest\ActiveController::checkAccess()方法。该方法用于检验当前发起请求的用户是否有权限使用某数据层进行某个操作。