Action 注解

控制器類 action 注解指的是可以在控制器類中 action 方法中聲明使用的注解標(biāo)簽，包括 Api、Param、ExtendParam 三個(gè)注解標(biāo)簽。用于實(shí)現(xiàn)對(duì)傳遞到 action 方法的參數(shù)的約束邏輯判斷及注解文檔的生成。

Api

標(biāo)記當(dāng)前的 action 為 api。

注解字段說明

apiName

該字段用于說明當(dāng)前 api 在注解文檔中展示的標(biāo)題名稱。

allowMethod

該字段用于限制當(dāng)前 api 允許請(qǐng)求的請(qǐng)求方法，可配置的值可查看枚舉類 \EasySwoole\HttpAnnotation\Enum\HttpMethod ，不配置時(shí)默認(rèn)為 [HttpMethod::GET,HttpMethod::POST]。開發(fā)者可能會(huì)對(duì)部分接口限制只能允許 GET 方法請(qǐng)求，這時(shí)就可以配置這個(gè)字段來限制請(qǐng)求方法。

requestPath

該字段用于說明請(qǐng)求當(dāng)前 api，可注冊(cè)到 fast-route，也作為注解文檔中的 api 請(qǐng)求路徑。

注意：如果不把 Api 注解中的 requestPath 注入到 EasySwoole 框架的 Router ，這個(gè)字段僅能作為注解文檔聲明，沒有其他作用，并不會(huì)使用該字段的值作為路由提供訪問，客戶端實(shí)際請(qǐng)求時(shí)也是執(zhí)行 EasySwoole 框架的默認(rèn)解析。關(guān)于如何將 requestPath 注入到 EasySwoole 框架的 Router 請(qǐng)看下文說明。

requestParam

該字段用于定義當(dāng)前 api action 方法客戶端需要傳遞的參數(shù)及限制約束規(guī)則，該字段接收一個(gè) Param 對(duì)象數(shù)組。實(shí)現(xiàn)對(duì)傳遞的參數(shù)進(jìn)行校驗(yàn)。使用示例如：

<?php

namespace App\HttpController;

use EasySwoole\HttpAnnotation\Attributes\Api;
use EasySwoole\HttpAnnotation\Attributes\Description;
use EasySwoole\HttpAnnotation\Attributes\Param;
use EasySwoole\HttpAnnotation\Enum\HttpMethod;
use EasySwoole\HttpAnnotation\Enum\ParamFrom;
use EasySwoole\HttpAnnotation\Validator\Optional;

class Index extends Base
{
    #[Api(
        apiName: "home",
        allowMethod: HttpMethod::GET,
        requestPath: "/test/index",
        requestParam: [
            new Param(
                name: "account",
                from: ParamFrom::GET,
                validate: [
                    new Optional()
                ],
                value: 1,
                description: new Description("翻頁參數(shù)")
            )
        ],
    )]
    function index(string $account)
    {
        $this->writeJson(200, null, "account is {$account}");
    }
}

responseParam

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

requestExamples

該字段主要用于自動(dòng)生成文檔時(shí)，請(qǐng)求參數(shù)示例的描述說明。

responseExamples

該字段主要用于自動(dòng)生成文檔時(shí)，響應(yīng)參數(shù)示例的描述說明。

description

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

將 `Api` 注解的 `requestPath` 注入路由

修改 App\HttpController\Router.php 類文件，在 initialize 方法中添加 \EasySwoole\HttpAnnotation\Utility::mappingRouter($routeCollector, __DIR__); 即可。

<?php

namespace App\HttpController;

use EasySwoole\Http\AbstractInterface\AbstractRouter;
use EasySwoole\HttpAnnotation\Utility;
use FastRoute\RouteCollector;

class Router extends AbstractRouter
{
    function initialize(RouteCollector $routeCollector)
    {
        // 將所有 `Api` 注解的 `requestPath` 注入路由
        Utility::mappingRouter($routeCollector, __DIR__);
    }
}

這樣就可以把所有 Api 注解中的 requestPath 注入到 fast-route，具體用法查看動(dòng)態(tài)路由章節(jié)。

使用示例

<?php

namespace App\HttpController;

use EasySwoole\HttpAnnotation\Attributes\Api;
use EasySwoole\HttpAnnotation\Attributes\Description;
use EasySwoole\HttpAnnotation\Attributes\Param;
use EasySwoole\HttpAnnotation\Document\Document;
use EasySwoole\HttpAnnotation\Enum\HttpMethod;
use EasySwoole\HttpAnnotation\Enum\ParamFrom;
use EasySwoole\HttpAnnotation\Validator\Integer;
use EasySwoole\HttpAnnotation\Validator\IsUrl;
use EasySwoole\HttpAnnotation\Validator\MaxLength;
use EasySwoole\HttpAnnotation\Validator\Min;
use EasySwoole\HttpAnnotation\Validator\MinLength;
use EasySwoole\HttpAnnotation\Validator\Optional;
use EasySwoole\HttpAnnotation\Validator\OptionalIfParamMiss;
use EasySwoole\HttpAnnotation\Validator\OptionalIfParamSet;
use EasySwoole\HttpAnnotation\Validator\Required;

class Index extends Base
{
    #[Api(
        apiName: "home",
        allowMethod: HttpMethod::GET,
        requestPath: "/test/index.html",
        requestParam: [
            new Param(
                name: "account",
                from: ParamFrom::GET,
                validate: [
                    new Optional()
                ],
                value: 1,
                description: new Description("翻頁參數(shù)")
            )
        ],
        description: new Description(__DIR__ . '/../../res/description.md', Description::MARKDOWN_FILE)
    )]
    public function index(string $account)
    {
        $this->writeJson(200, null, "account is {$account}");
    }

    #[Api(
        apiName: "hello",
        allowMethod: [HttpMethod::POST, HttpMethod::GET],
        requestPath: "/test/hello.html",
        requestParam: [
            new Param(name: "account", from: ParamFrom::GET, validate: [
                new Required(),
                new MaxLength(maxLen: 15),
            ], description: new Description("用戶登錄的賬戶Id,這個(gè)參數(shù)一定要有啊"))
        ],
        description: new Description("這是一個(gè)接口說明啊啊啊啊")
    )]
    public function hello(string $account)
    {
        $this->writeJson(200, null, "account is {$account}");
    }

    public function doc()
    {
        $path      = __DIR__;
        $namespace = 'App\HttpController';
        $doc       = new Document($path, $namespace);
        $this->response()->write($doc->scanToHtml());
    }

    #[Api(
        apiName: 'url',
        requestParam: [
            new Param(
                name: "url",
                validate: [
                    new IsUrl()
                ]
            )
        ]
    )]
    public function url()
    {

    }

    #[Api(
        apiName: 'optionalSet',
        requestParam: [
            new Param(
                name: "a",
                validate: [
                    new OptionalIfParamSet("b"),
                    new MinLength("5")
                ]
            ),
            new Param(
                name: "b",
                validate: [
                    new OptionalIfParamSet("a"),
                    new Integer(),
                    new Min(1)
                ]
            )
        ]
    )]
    public function optionalSet()
    {

    }

    #[Api(
        apiName: 'optionalMiss',
        requestParam: [
            new Param(
                name: "a",
                validate: [
                    new Optional(),
                    new MinLength("5")
                ],
            ),
            new Param(
                name: "b",
                validate: [
                    new OptionalIfParamMiss("a"),
                    new Integer(),
                    new Min(1)
                ]
            )
        ]
    )]
    public function optionalMiss()
    {

    }
}

Param

Param 注解的字段說明已經(jīng)在控制器類注解章節(jié)進(jìn)行了說明。這里就不再詳細(xì)說明。這里提到 Param 的使用，是其在 action 方法中的使用說明。

注意：Param 注解在 action 中使用時(shí)，不能既在 Api 注解的 requestParam 字段中使用 Param 注解，又在 action 方法上單獨(dú)聲明 Param 注解，這樣做時(shí)會(huì)導(dǎo)致后者失效。所以推薦要么在 Api 注解的 requestParam 字段中使用 Param 注解，要么在不使用 Api 注解的情況下直接單獨(dú)使用 Param 注解，后者這種就不能把定義的 requestPath 注入路由，而是執(zhí)行 EasySwoole 框架默認(rèn)的路由解析模式。

錯(cuò)誤示例：

<?php
namespace App\HttpController;

use EasySwoole\HttpAnnotation\Attributes\Api;
use EasySwoole\HttpAnnotation\Attributes\Param;
use EasySwoole\HttpAnnotation\Validator\MinLength;
use EasySwoole\HttpAnnotation\Validator\Optional;

class User extends Base
{
    #[Api(
        apiName: 'optionalMiss',
        requestParam: [
            new Param(
                name: "a",
                validate: [
                    new Optional(),
                    new MinLength(5)
                ],
            )
        ]
    )]
    #[Param(
        name: "b",
        validate: [
            new Optional(),
            new MinLength(5)
        ],
    )]
    public function optionalMiss()
    {

    }
}

上述 optionalMiss action 中 Param 注解的參數(shù) b 會(huì)被忽略，既不會(huì)被驗(yàn)證，也不會(huì)注入?yún)?shù)傳參。

正確示例：

<?php
namespace App\HttpController;

use EasySwoole\HttpAnnotation\Attributes\Api;
use EasySwoole\HttpAnnotation\Attributes\Param;
use EasySwoole\HttpAnnotation\Validator\MinLength;
use EasySwoole\HttpAnnotation\Validator\Optional;

class User extends Base
{
    #[Api(
        apiName: 'optionalMiss',
        requestParam: [
            new Param(
                name: "a",
                validate: [
                    new Optional(),
                    new MinLength(5)
                ],
            ),
            new Param(
                name: "b",
                validate: [
                    new Optional(),
                    new MinLength(5)
                ],
            )
        ]
    )]
    public function optionalMiss()
    {

    }
}

使用示例

<?php

namespace App\HttpController\Api;

use EasySwoole\HttpAnnotation\Attributes\Api;
use EasySwoole\HttpAnnotation\Attributes\ApiGroup;
use EasySwoole\HttpAnnotation\Attributes\Description;
use EasySwoole\HttpAnnotation\Attributes\Example;
use EasySwoole\HttpAnnotation\Attributes\Param;
use EasySwoole\HttpAnnotation\Enum\HttpMethod;
use EasySwoole\HttpAnnotation\Enum\ParamFrom;
use EasySwoole\HttpAnnotation\Enum\ParamType;
use EasySwoole\HttpAnnotation\Validator\MaxLength;
use EasySwoole\HttpAnnotation\Validator\Required;

#[ApiGroup(
    groupName: "Api.Auth", description: new Description(__DIR__ . '/../../../res/description.md', Description::MARKDOWN_FILE)
)]
class Auth extends ApiBase
{
    #[Api(
        apiName: "login",
        allowMethod: HttpMethod::GET,
        requestPath: "/auth/login.html",
        requestParam: [
            new Param(name: "account", from: ParamFrom::GET, validate: [
                new Required(),
                new MaxLength(maxLen: 15),
            ], description: new Description("用戶登錄的賬戶Id")),
            new Param(name: "password", from: ParamFrom::GET, validate: [
                new Required(),
                new MaxLength(maxLen: 15),
            ], description: new Description("密碼")),
            new Param(name: "verify", from: ParamFrom::JSON,
                description: new Description("驗(yàn)證碼"),
                type: ParamType::OBJECT,
                subObject: [
                    new Param(name: "code", from: ParamFrom::JSON, validate: [
                        new Required(),
                        new MaxLength(maxLen: 15),
                    ], description: "防偽編號(hào)"),
                    new Param(name: "phone", from: ParamFrom::JSON, description: "手機(jī)號(hào)")
                ])
        ],
        responseParam: [
            new Param(
                name: "code", type: ParamType::STRING
            ),
            new Param(
                name: "Result",
                type: ParamType::LIST,
                subObject: [
                    new Param("token"),
                    new Param("expire")
                ]
            ),
            new Param("msg")
        ],
        requestExamples: [
            new Example(
                [
                    new Param(name: "account", value: "1111", description: "賬號(hào)"),
                    new Param(name: "password", value: "1111", description: "密碼"),
                    new Param(name: "verify", value: "1111", description: new Description('驗(yàn)證碼')),
                ]
            ),
            new Example(
                new Description(__DIR__ . '/../../../res/json.json', Description::JSON_FILE)
            ),
            new Example(
                new Description(__DIR__ . '/../../../res/xml.xml', Description::XML_FILE)
            ),
        ],
        responseExamples: [
            new Example(
                [
                    new Param(name: "result", description: "結(jié)果", subObject: [
                        new Param(name: "id", value: 1, description: "用戶Id"),
                        new Param(name: "name", value: "八九", description: "昵稱")
                    ]),
                    new Param(name: "code", value: "200", description: "狀態(tài)碼"),
                ]
            ),
            new Example(
                [
                    new Param(name: "result", value: "fail", description: "結(jié)果"),
                    new Param(name: "code", value: "500", description: "狀態(tài)碼"),
                ]
            ),
            new Example(
                new Description(__DIR__ . '/../../../res/json.json', Description::JSON_FILE)
            ),
            new Example(
                new Description(__DIR__ . '/../../../res/xml.xml', Description::XML_FILE)
            ),
        ],
        description: new Description("這是一個(gè)接口說明")
    )]
    public function login()
    {

    }
}

ExtendParam

用于子類控制器類在重寫父類控制類的 action 方法時(shí)限制約束傳入子類控制器類的 action 方法參數(shù)。且 ExtendParam 注解只能在 action 中使用一次。

使用示例

Base 類，父類有一個(gè) add action，限制必填參數(shù) param1、param2。

<?php
namespace App\HttpController;

use EasySwoole\HttpAnnotation\AnnotationController;
use EasySwoole\HttpAnnotation\Attributes\Param;
use EasySwoole\HttpAnnotation\Exception\Annotation;
use EasySwoole\HttpAnnotation\Exception\ValidateFail;
use EasySwoole\HttpAnnotation\Validator\Required;

class Base extends AnnotationController
{
    #[Param(
        name: "param3",
        validate: [
            new Required()
        ]
    )]
    #[Param(
        name: "param4",
        validate: [
            new Required()
        ]
    )]
    public function add()
    {

    }

    protected function onException(\Throwable $throwable): void
    {
        if ($throwable instanceof ValidateFail) {
            $this->writeJson(400, null, $throwable->getMessage());
        } else {
            if ($throwable instanceof Annotation) {
                $this->writeJson(400, null, $throwable->getMessage());
            } else {
                throw $throwable;
            }
        }
    }
}

Index 類，子類控制器，重寫父類 Base 的 add action，聲明 ExtendParam 注解指定要約束的參數(shù)，所以 add action 由于受到父類參數(shù)約束，所以必填參數(shù) param1、param2。

<?php
namespace App\HttpController;

use EasySwoole\HttpAnnotation\Attributes\ExtendParam;

class Index extends Base
{
    #[ExtendParam(parentParams: ['param1', 'param2'])]
    public function add()
    {

    }
}

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

Action 注解

Api

注解字段說明

apiName

allowMethod

requestPath

requestParam

responseParam

requestExamples

responseExamples

description

將 Api 注解的 requestPath 注入路由

使用示例

Param

使用示例

ExtendParam

使用示例

將 `Api` 注解的 `requestPath` 注入路由