README

适用于企业模板的 REST 基础组件

组件包含用于 RESTful API 的控制器，具有标准化的过滤器和行为。

除了基本配置外，还包括用于格式化和处理 CORS 请求的附加层。同时，还提供了 API 服务器在请求成功执行或请求出错时的基本响应。

安装

要将组件连接到代码，需要在 composer.json 中添加以下代码

"require": {
    "oleg-chulakov-studio/yii2-rest": "~1.0.0"
}

或者执行以下命令

composer require oleg-chulakov-studio/yii2-rest

访问控制

默认情况下，Yii2 使用两种行为来控制对每个控制器的访问。设置 VerbFilter 和 AccessControl 访问过滤器需要相当大的规则数组。因此，通过创建基本访问数组简化了此设置。

public function accessRules()
{
    return [
        'index'   => $this->createAccess('get', true),
        'view'    => $this->createAccess('get', true, '@'),
        'create'  => $this->createAccess('post', true, '@'),
        'update'  => $this->createAccess('put, patch', true, '@'),
        'delete'  => $this->createAccess('delete', true, '@'),
        'options' => $this->createAccess(),
    ];
}

访问方法和规则可以写成两种形式

• 'post, get' - 使用逗号分隔的元素字符串
• ['admin', '@'] - 元素数组

如果需要扩展行为，使其不同于标准行为，可以重写生成过滤器配置的方法

• AccessControl - 方法 protected function accessBehavior($rules) 接收访问规则列表并返回行为配置。
• VerbFilter - 方法 protected function verbsBehavior($actions) 接收具有访问方法的动作列表并返回行为配置。

RESTful API

每个 API 通常都伴随着额外的检查和行为，确保控制器可以自动为自动化的用户或通过跨域请求（CORS）提供访问。基本 REST 控制器提供必要的配置以应对此类情况。

认证

默认使用 HttpBearerAuth 行为进行认证。它会在控制器中添加两个额外的配置

• authenticatorExcept - 不需要认证的动作数组
• authenticatorOnly - 需要认证的动作数组

如果这两个设置都是空的，则控制器中的所有动作都将需要认证。

ContentNegotiator

对于 RESTful API，通常使用 json 字符串作为通信格式，该行为允许自动将请求转换为 json 格式并返回。还可以进行以下配置

• negotiatorExcept - 不进行格式化的动作数组
• negotiatorOnly - 需要格式化的动作数组

如果这两个设置都是空的，则控制器中的所有动作都将进行格式化。

CORS

为每个 API 控制器配置了跨域访问过滤器，并提供对所有动作的最大访问级别。也可以对其进行影响

• corsMethods - 允许的访问方法数组（POST、GET）

如果设置保持为空，则将使用 VerbFilter 中指定的所有动作的方法。

重写和扩展行为

每个过滤器都有自己的创建行为配置的方法。如果该方法返回空数组或 null 值，则不会将行为连接到控制器。

• 认证: protected function authenticatorBehavior()
• ContentNegotiator: protected function contentNegotiatorBehavior()
• CORS: protected function corsBehavior()

标准化响应

为了标准化服务器响应，使用了两个基本方法

• 处理成功完成：return $this->successResult($code = HTTP::SUCCESS_OK, $message = null)
• 处理过程中发生错误：return $this->errorResult(Model $model, $error)

在所有其他情况下，可以返回任何客户端API请求期望得到的数组。

处理成功完成的结果将返回一个数组

{
    "success" : true,
    "message" : $message
}

在错误消息的结果中，将抛出BadRequestHttpException异常，指明表单/模型验证的第一个错误或错误消息。此外，为异常传递errorStatus以供客户端额外处理验证错误和服务器错误。默认变量设置为1。

行为

• CORS行为