參數(shù)注解校驗(yàn)

Easyswoole控制器總共有三個(gè)參數(shù)注解標(biāo)簽，分別是：

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

ApiAuth與ApiGroupAuth均繼承自Param，對(duì)于任意一個(gè)參數(shù)注解，都要求填寫注解的name字段。

Param對(duì)象實(shí)際上是對(duì)Easyswoole/Validate參數(shù)驗(yàn)證組件驗(yàn)證規(guī)則的封裝，底層是調(diào)用該組件進(jìn)行參數(shù)校驗(yàn)。

當(dāng)校驗(yàn)失敗的時(shí)候，則會(huì)拋出一個(gè)EasySwoole\HttpAnnotation\Exception\Annotation\ParamValidateError異常，可以在控制器的onExcepion中進(jìn)行處理。

@Param

基礎(chǔ)參數(shù)注解，作用域在控制器的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']}");
}

那么則規(guī)定了index這個(gè)action需要name與age這兩個(gè)參數(shù)，且校驗(yàn)規(guī)則分別為required="",lengthMax="25"與integer=""

參數(shù)的接收

在控制器的Request對(duì)象中得到的參數(shù)值，為客戶端提交的原始值，參數(shù)的注解校驗(yàn)或者預(yù)處理，并不會(huì)影響原始值。但是通過控制器自動(dòng)傳參或者是上下文注解標(biāo)簽得到的參數(shù)，則為經(jīng)過預(yù)處理后的參數(shù)。

自動(dòng)傳參

/**
* @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}");
}

當(dāng)某個(gè)action定義了參數(shù)，且有注解的時(shí)候，那么控制器會(huì)利用反射機(jī)制，根據(jù)函數(shù)定義的參數(shù)名，去取對(duì)應(yīng)的參數(shù)。

注解傳參數(shù)

/**
* @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標(biāo)簽，完整命名空間是EasySwoole\HttpAnnotation\AnnotationTag\InjectParamsContext，我們可以把通過驗(yàn)證的參數(shù)，設(shè)置到指定的協(xié)成上下文中，并通過上下文管理器EasySwoole\Component\Context\ContextManager得到對(duì)應(yīng)的參數(shù)。其中，除了必填的key字段，還有如下幾個(gè)字段：

• onlyParamTag

  忽略@ApiAuth與@ApiGroupAuth定義的參數(shù)

• filterNull

  忽略值為null的參數(shù)

• filterEmpty

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

附加字段

@Param注解除了name字段為必填項(xiàng)，還有以下幾個(gè)輔助字段。

from

例如在以下注解中：

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

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

type

例如以下注解中：

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

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

defaultValue

在客戶端沒有傳遞該參數(shù)的值時(shí)，可以用該字段進(jìn)行默認(rèn)值的定義。

preHandler

該字段是用于對(duì)某個(gè)參數(shù)值不為null時(shí)進(jìn)行預(yù)處理。preHandler需要是一個(gè)callable，例如

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

則通過函數(shù)自動(dòng)傳參，或者是@InjectParamsContext得到的參數(shù)時(shí)，password會(huì)被自動(dòng)執(zhí)行md5()

description

該字段主要用戶自動(dòng)生成文檔時(shí)，參數(shù)的描述說明。

@ApiAuth

@ApiAuth注解標(biāo)簽，完整的命名空間是EasySwoole\HttpAnnotation\AnnotationTag\ApiAuth，作用域在控制器的actionMethod與onRequest均為有效，本質(zhì)與@Param標(biāo)簽并無區(qū)別，僅僅是在自動(dòng)生成文檔的時(shí)候，@Param被描述為請(qǐng)求參數(shù)，而@ApiAuth則會(huì)被描述為權(quán)限參數(shù)。

控制器全局參數(shù)

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

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控制器下的任何請(qǐng)求，都需要token這個(gè)參數(shù)。

參數(shù)覆蓋優(yōu)先順序

@Param > @ApiAuth > @ApiGroupAuth