參數(shù)注解校驗

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

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

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

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

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

@Param

基礎參數(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這個action需要name與age這兩個參數(shù)，且校驗規(guī)則分別為required="",lengthMax="25"與integer=""

參數(shù)的接收

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

自動傳參

/**
* @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定義了參數(shù)，且有注解的時候，那么控制器會利用反射機制，根據(jù)函數(shù)定義的參數(shù)名，去取對應的參數(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標簽，完整命名空間是EasySwoole\HttpAnnotation\AnnotationTag\InjectParamsContext，我們可以把通過驗證的參數(shù)，設置到指定的協(xié)成上下文中，并通過上下文管理器EasySwoole\Component\Context\ContextManager得到對應的參數(shù)。其中，除了必填的key字段，還有如下幾個字段：

• onlyParamTag

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

• filterNull

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

• filterEmpty

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

附加字段

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

from

例如在以下注解中：

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

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

type

例如以下注解中：

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

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

defaultValue

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

preHandler

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

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

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

description

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

@ApiAuth

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

控制器全局參數(shù)

全局注解標簽是@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這個參數(shù)。

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

@Param > @ApiAuth > @ApiGroupAuth