# 控制器 在創建資源類和指定資源格輸出式化后，下一步就是創建控制器操作將資源通過RESTful APIs展現給終端用戶。 Yii 提供兩個控制器基類來簡化創建RESTful 操作的工作:yii\rest\Controller 和 yii\rest\ActiveController， 兩個類的差別是后者提供一系列將資源處理成[Active Record](http://www.yiichina.com/doc/guide/2.0/db-active-record)的操作。 因此如果使用[Active Record](http://www.yiichina.com/doc/guide/2.0/db-active-record)內置的操作會比較方便，可考慮將控制器類 繼承yii\rest\ActiveController，它會讓你用最少的代碼完成強大的RESTful APIs. yii\rest\Controller 和 yii\rest\ActiveController 提供以下功能，一些功能在后續章節詳細描述： * HTTP 方法驗證; * [內容協商和數據格式化](http://www.yiichina.com/doc/guide/2.0/rest-response-formatting); * [認證](http://www.yiichina.com/doc/guide/2.0/rest-authentication); * [頻率限制](http://www.yiichina.com/doc/guide/2.0/rest-rate-limiting). yii\rest\ActiveController 額外提供一下功能: * 一系列常用操作:?`index`,?`view`,?`create`,?`update`,?`delete`,?`options`; * 對操作和資源進行用戶認證. ## 創建控制器類 當創建一個新的控制器類，控制器類的命名最好使用資源名稱的單數格式，例如，提供用戶信息的控制器 可命名為`UserController`. 創建新的操作和Web應用中創建操作類似，唯一的差別是Web應用中調用`render()`方法渲染一個視圖作為返回值， 對于RESTful操作直接返回數據，yii\rest\Controller::serializer 和 yii\web\Response 會處理原始數據到請求格式的轉換，例如 ~~~ public function actionView($id) { return User::findOne($id); } ~~~ ## 過濾器 yii\rest\Controller提供的大多數RESTful API功能通過[過濾器](http://www.yiichina.com/doc/guide/2.0/structure-filters)實現. 特別是以下過濾器會按順序執行： * yii\filters\ContentNegotiator: 支持內容協商，在?[響應格式化](http://www.yiichina.com/doc/guide/2.0/rest-response-formatting)?一節描述; * yii\filters\VerbFilter: 支持HTTP 方法驗證; the?[Authentication](http://www.yiichina.com/doc/guide/2.0/rest-authentication)?section; * yii\filters\AuthMethod: 支持用戶認證，在[認證](http://www.yiichina.com/doc/guide/2.0/rest-authentication)一節描述; * yii\filters\RateLimiter: 支持頻率限制，在[頻率限制](http://www.yiichina.com/doc/guide/2.0/rest-rate-limiting)?一節描述. 這些過濾器都在yii\rest\Controller::behaviors()方法中聲明， 可覆蓋該方法來配置單獨的過濾器，禁用某個或增加你自定義的過濾器。 例如，如果你只想用HTTP 基礎認證，可編寫如下代碼： ~~~ use yii\filters\auth\HttpBasicAuth; public function behaviors() { $behaviors = parent::behaviors(); $behaviors['authenticator'] = [ 'class' => HttpBasicAuth::className(), ]; return $behaviors; } ~~~ ## 繼承?`ActiveController` 如果你的控制器繼承yii\rest\ActiveController，應設置yii\rest\ActiveController::modelClass 屬性 為通過該控制器返回給用戶的資源類名，該類必須繼承yii\db\ActiveRecord. ### 自定義操作 yii\rest\ActiveController 默認提供一下操作: * yii\rest\IndexAction: 按頁列出資源; * yii\rest\ViewAction: 返回指定資源的詳情; * yii\rest\CreateAction: 創建新的資源; * yii\rest\UpdateAction: 更新一個存在的資源; * yii\rest\DeleteAction: 刪除指定的資源; * yii\rest\OptionsAction: 返回支持的HTTP方法. 所有這些操作通過yii\rest\ActiveController::actions() 方法申明，可覆蓋`actions()`方法配置或禁用這些操作， 如下所示： ~~~ public function actions() { $actions = parent::actions(); // 禁用"delete" 和 "create" 操作 unset($actions['delete'], $actions['create']); // 使用"prepareDataProvider()"方法自定義數據provider $actions['index']['prepareDataProvider'] = [$this, 'prepareDataProvider']; return $actions; } public function prepareDataProvider() { // 為"index"操作準備和返回數據provider } ~~~ 請參考獨立操作類的參考文檔學習哪些配置項有用。 ### 執行訪問檢查 通過RESTful APIs顯示數據時，經常需要檢查當前用戶是否有權限訪問和操作所請求的資源， 在yii\rest\ActiveController中，可覆蓋yii\rest\ActiveController::checkAccess()方法來完成權限檢查。 ~~~ /** * Checks the privilege of the current user. 檢查當前用戶的權限 * * This method should be overridden to check whether the current user has the privilege * to run the specified action against the specified data model. * If the user does not have access, a ForbiddenHttpException should be thrown. * 本方法應被覆蓋來檢查當前用戶是否有權限執行指定的操作訪問指定的數據模型 * 如果用戶沒有權限，應拋出一個ForbiddenHttpException異常 * * @param string $action the ID of the action to be executed * @param \yii\base\Model $model the model to be accessed. If null, it means no specific model is being accessed. * @param array $params additional parameters * @throws ForbiddenHttpException if the user does not have access */ public function checkAccess($action, $model = null, $params = []) { // 檢查用戶能否訪問 $action 和 $model // 訪問被拒絕應拋出ForbiddenHttpException } ~~~ `checkAccess()`?方法默認會被yii\rest\ActiveController默認操作所調用，如果創建新的操作并想執行權限檢查， 應在新的操作中明確調用該方法。 > 提示: 可使用[Role-Based Access Control (RBAC) 基于角色權限控制組件](http://www.yiichina.com/doc/guide/2.0/security-authorization)實現`checkAccess()`。