控制器類注解
控制器類注解指的是可以在控制器類上聲明使用的注解標簽,包括 Param
、ApiGroup
兩個注解標簽。用于實現(xiàn)對控制器類中成員方法的參數(shù)的約束邏輯判斷及注解文檔的生成。
Param 注解
Param
注解,作用域在控制器類聲明中生效,可作為當前控制器類的全局參數(shù)去使用。例如在以下代碼中:
<?php
namespace App\HttpController;
use EasySwoole\HttpAnnotation\AnnotationController;
use EasySwoole\HttpAnnotation\Attributes\Param;
use EasySwoole\HttpAnnotation\Validator\Required;
#[Param(
name: "signature",
validate: [
new Required()
],
ignoreAction: [
"info"
]
)]
class Profile extends AnnotationController
{
public function info() {
}
public function foo($signature) {
$data = $this->request()->getRequestParam();
$this->response()->write("your name is {$name} and age {$age}");
}
}
那么則規(guī)定了 Profile
這個控制器類除了 info
這個 action
不需要 signature
參數(shù),其他 action
均需要 signature
參數(shù),且校驗規(guī)則分別為 required
即要求必填。
參數(shù)的接收
自動傳參
<?php
namespace App\HttpController;
use EasySwoole\EasySwoole\Trigger;
use EasySwoole\HttpAnnotation\AnnotationController;
use EasySwoole\HttpAnnotation\Attributes\Param;
use EasySwoole\HttpAnnotation\Exception\ValidateFail;
use EasySwoole\HttpAnnotation\Validator\Required;
#[Param(
name: "signature",
validate: [
new Required()
],
ignoreAction: [
"info"
]
)]
class Profile extends AnnotationController
{
public function foo($signature)
{
$this->response()->write("the signature is {$signature}");
}
}
當某個 action
定義了參數(shù),且在控制器類聲明中使用 Param
注解的時候,那么控制器會利用反射機制,根據(jù) action
方法定義的參數(shù)名,去自動獲取取對應(yīng)的參數(shù)。
Param 注解附加的字段
Param
注解除了 name
字段為必填項,還有以下幾個輔助字段。
from
例如在以下注解中:
use EasySwoole\HttpAnnotation\AnnotationController;
use EasySwoole\HttpAnnotation\Attributes\Param;
use EasySwoole\HttpAnnotation\Enum\ParamFrom;
use EasySwoole\HttpAnnotation\Validator\Integer;
use EasySwoole\HttpAnnotation\Validator\MaxLength;
use EasySwoole\HttpAnnotation\Validator\Required;
#[Param(
name: "name",
from: [ParamFrom::GET, ParamFrom::POST],
validate: [
new Required(),
new MaxLength(25),
]
)]
#[Param(
name: "age",
from: [ParamFrom::POST],
validate: [
new Integer(),
]
)]
class Profile extends AnnotationController
{
}
則規(guī)定了 name
字段允許的取參順序為:GET => POST,而 age
參數(shù)就僅僅允許為 POST
傳參。目前 from
的允許值可查看枚舉類 \EasySwoole\HttpAnnotation\Enum\ParamFrom
。在不規(guī)定 from
字段時,默認的 from
值為 [ParamFrom::GET, ParamFrom::POST]
。具體實現(xiàn)可在 \EasySwoole\HttpAnnotation\Attributes\Param
的 parsedValue
方法中查看。
validate
對請求中傳入的參數(shù)設(shè)置驗證規(guī)則,并進行驗證,驗證失敗則拋出異常 \EasySwoole\HttpAnnotation\Exception\ValidateFail
。
value
在客戶端沒有傳遞該參數(shù)的值時,可以用該字段進行默認值的定義。
description
該字段主要用于自動生成文檔時,參數(shù)的描述說明。
type
例如以下注解中:
use EasySwoole\HttpAnnotation\AnnotationController;
use EasySwoole\HttpAnnotation\Attributes\Param;
use EasySwoole\HttpAnnotation\Enum\ParamType;
#[Param(
name: "age",
type: ParamType::INT,
)]
class Profile extends AnnotationController
{
public function echoAge($age)
{
var_dump('the is age');
var_dump($age);
$this->response()->write("the age is {$age}");
}
}
通過 action
方法自動傳參得到的參數(shù)時,會對 age
這個參數(shù)進行 intval()
處理。type
字段可選值可查看枚舉類 \EasySwoole\HttpAnnotation\Enum\ParamType
,具體處理原理可在 \EasySwoole\HttpAnnotation\Attributes\Param
類的 parsedValue
方法中查看。
subObject
該字段用于對當前參數(shù)為字典類型時,對其子屬性進行限制約束。如:
use EasySwoole\HttpAnnotation\AnnotationController;
use EasySwoole\HttpAnnotation\Attributes\Description;
use EasySwoole\HttpAnnotation\Attributes\Param;
use EasySwoole\HttpAnnotation\Enum\ParamFrom;
use EasySwoole\HttpAnnotation\Validator\Required;
#[Param(
name: 'result',
from: ParamFrom::JSON,
validate: [
new Required(),
],
description: new Description('result'),
subObject: [
new Param(
name: "userName",
from: ParamFrom::JSON,
validate: [
new Required()
]
)
]
)]
class Api extends AnnotationController
{
}
上述示例要求客戶端傳參時,必傳參數(shù) result
對象中必須包含子屬性 userName
。
ignoreAction
該字段用于聲明需要對當前控制類的哪些 action
不進行注入,或者不做參數(shù)限制約束。
ApiGroup 注解
該注解用于聲明在控制器類的聲明中,用于注解文檔的生成。
use EasySwoole\HttpAnnotation\Attributes\ApiGroup;
use EasySwoole\HttpAnnotation\Attributes\Description;
use EasySwoole\HttpAnnotation\AnnotationController;
#[ApiGroup(
groupName: "Api",
description: new Description(
desc: EASYSWOOLE_ROOT . "/res/description.md"
),
)]
class ApiBase extends Base
{
}
groupName
該字段用于給接口分組,它會自動把相同分組的接口統(tǒng)一在同一個分類下,方便開發(fā)者查看接口文檔。
description
該字段用于說明接口文檔存放的位置及接口文檔生成格式。