參數注解校驗

Easyswoole控制器總共有三個參數注解標簽，分別是：

@Param EasySwoole\HttpAnnotation\AnnotationTag\Param
@ApiAuth EasySwoole\HttpAnnotation\AnnotationTag\ApiAuth
@ApiGroupAuth EasySwoole\HttpAnnotation\AnnotationTag\ApiGroupAuth

ApiAuth與ApiGroupAuth均繼承自Param，對于任意一個參數注解，都要求填寫注解的name字段。

Param對象實際上是對Easyswoole/Validate參數驗證組件驗證規則的封裝，底層是調用該組件進行參數校驗。

當校驗失敗的時候，則會拋出一個EasySwoole\HttpAnnotation\Exception\Annotation\ParamValidateError異常，可以在控制器的onExcepion中進行處理。

@Param

基礎參數注解，作用域在控制器的actionMethod與onRequest均為有效。例如在以下代碼中：

/**
* @Param(name="name",required="",lengthMax="25")
* @Param(name="age",integer="")
*/
function index()
{
    $data = $this->request()->getRequestParam();
    $this->response()->write("your name is {$data['name']} and age {$data['age']}");
}

那么則規定了index這個action需要name與age這兩個參數，且校驗規則分別為required="",lengthMax="25"與integer=""

參數的接收

在控制器的Request對象中得到的參數值，為客戶端提交的原始值，參數的注解校驗或者預處理，并不會影響原始值。但是通過控制器自動傳參或者是上下文注解標簽得到的參數，則為經過預處理后的參數。

自動傳參

/**
* @Param(name="name",required="",lengthMax="25",from={GET,POST})
* @Param(name="age",type="int")
*/
function index($age,$name)
{
   $data = $this->request()->getRequestParam();
   $this->response()->write("your name is {$name} and age {$age}");
}

當某個action定義了參數，且有注解的時候，那么控制器會利用反射機制，根據函數定義的參數名，去取對應的參數。

注解傳參數

/**
* @Param(name="name",required="",lengthMax="25",from={GET,POST})
* @Param(name="age",type="int")
* @InjectParamsContext(key="data")
*/
function index()
{
    $data = ContextManager::getInstance()->get('data');
    $this->response()->write("your name is {$data['name']} and age {$data['age']}");
}

通過@InjectParamsContext標簽，完整命名空間是EasySwoole\HttpAnnotation\AnnotationTag\InjectParamsContext，我們可以把通過驗證的參數，設置到指定的協成上下文中，并通過上下文管理器EasySwoole\Component\Context\ContextManager得到對應的參數。其中，除了必填的key字段，還有如下幾個字段：

onlyParamTag

忽略@ApiAuth與@ApiGroupAuth定義的參數
filterNull

忽略值為null的參數
filterEmpty

忽略值被empty()判定為true的參數，注意數字0或者是字符串0與空字符串等問題

附加字段

@Param注解除了name字段為必填項，還有以下幾個輔助字段。

from

例如在以下注解中：

* @Param(name="name",required="",lengthMax="25",from={GET,POST})
* @Param(name="age",integer="",from={POST})

則規定了name字段允許的取參順序為：GET => POST，而age參數就僅僅允許為 POST 傳參。目前from的允許值為： POST，GET，COOKIE,HEADER,FILE,DI,CONTEXT,RAW,JSON,SESSION,ROUTER_PARAMS。在無規定from字段時，默認以$request->getRequestParam($paramName)方法獲得參數值。具體實現可以在EasySwoole\HttpAnnotation\AnnotationController的__handleMethodAnnotation方法中查看。

type

例如以下注解中：

* @Param(name="age",type="int")

通過函數自動傳參，或者是@InjectParamsContext得到的參數時，會對age這個參數進行intval()處理。type字段可選值為：string，int,double,real,float，bool，json，array，具體可以在EasySwoole\HttpAnnotation\AnnotationTag\Param的typeCast方法中查看。

defaultValue

在客戶端沒有傳遞該參數的值時，可以用該字段進行默認值的定義。

preHandler

該字段是用于對某個參數值不為null時進行預處理。preHandler需要是一個callable，例如

* @Param(name="password",preHandler="md5")

則通過函數自動傳參，或者是@InjectParamsContext得到的參數時，password會被自動執行md5()

description

該字段主要用戶自動生成文檔時，參數的描述說明。

@ApiAuth

@ApiAuth注解標簽，完整的命名空間是EasySwoole\HttpAnnotation\AnnotationTag\ApiAuth，作用域在控制器的actionMethod與onRequest均為有效，本質與@Param標簽并無區別，僅僅是在自動生成文檔的時候，@Param被描述為請求參數，而@ApiAuth則會被描述為權限參數。

控制器全局參數

全局注解標簽是@ApiGroupAuth，完整的命名空間是EasySwoole\HttpAnnotation\AnnotationTag\ApiGroupAuth,作用域在整個控制器。

namespace App\HttpController;

use EasySwoole\HttpAnnotation\AnnotationController;
use EasySwoole\HttpAnnotation\AnnotationTag\ApiGroupAuth;

/**
 * Class Index
 * @ApiGroupAuth(name="token",required="")
 * @package App\HttpController
 */
class Index extends AnnotationController
{

}

這樣的注解表示，Index控制器下的任何請求，都需要token這個參數。

參數覆蓋優先順序

@Param > @ApiAuth > @ApiGroupAuth

easyswoole - 基于swoole扩展实现的一款高性能php框架