Action 注解

控制器類 action 注解指的是可以在控制器類中 action 方法中聲明使用的注解標簽，包括 Api、Param、ExtendParam 三個注解標簽。用于實現對傳遞到 action 方法的參數的約束邏輯判斷及注解文檔的生成。

Api

標記當前的 action 為 api。

注解字段說明

apiName

該字段用于說明當前 api 在注解文檔中展示的標題名稱。

allowMethod

該字段用于限制當前 api 允許請求的請求方法，可配置的值可查看枚舉類 \EasySwoole\HttpAnnotation\Enum\HttpMethod ，不配置時默認為 [HttpMethod::GET,HttpMethod::POST]。開發者可能會對部分接口限制只能允許 GET 方法請求，這時就可以配置這個字段來限制請求方法。

requestPath

該字段用于說明請求當前 api，可注冊到 fast-route，也作為注解文檔中的 api 請求路徑。

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

requestParam

該字段用于定義當前 api action 方法客戶端需要傳遞的參數及限制約束規則，該字段接收一個 Param 對象數組。實現對傳遞的參數進行校驗。使用示例如：

<?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("翻頁參數")
            )
        ],
    )]
    function index(string $account)
    {
        $this->writeJson(200, null, "account is {$account}");
    }
}

responseParam

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

requestExamples

該字段主要用于自動生成文檔時，請求參數示例的描述說明。

responseExamples

該字段主要用于自動生成文檔時，響應參數示例的描述說明。

description

該字段主要用于自動生成文檔時，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，具體用法查看動態路由章節。

使用示例

<?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("翻頁參數")
            )
        ],
        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,這個參數一定要有啊"))
        ],
        description: new Description("這是一個接口說明啊啊啊啊")
    )]
    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 注解的字段說明已經在控制器類注解章節進行了說明。這里就不再詳細說明。這里提到 Param 的使用，是其在 action 方法中的使用說明。

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

錯誤示例：

<?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 注解的參數 b 會被忽略，既不會被驗證，也不會注入參數傳參。

正確示例：

<?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("驗證碼"),
                type: ParamType::OBJECT,
                subObject: [
                    new Param(name: "code", from: ParamFrom::JSON, validate: [
                        new Required(),
                        new MaxLength(maxLen: 15),
                    ], description: "防偽編號"),
                    new Param(name: "phone", from: ParamFrom::JSON, description: "手機號")
                ])
        ],
        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: "賬號"),
                    new Param(name: "password", value: "1111", description: "密碼"),
                    new Param(name: "verify", value: "1111", description: new Description('驗證碼')),
                ]
            ),
            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: "結果", subObject: [
                        new Param(name: "id", value: 1, description: "用戶Id"),
                        new Param(name: "name", value: "八九", description: "昵稱")
                    ]),
                    new Param(name: "code", value: "200", description: "狀態碼"),
                ]
            ),
            new Example(
                [
                    new Param(name: "result", value: "fail", description: "結果"),
                    new Param(name: "code", value: "500", description: "狀態碼"),
                ]
            ),
            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("這是一個接口說明")
    )]
    public function login()
    {

    }
}

ExtendParam

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

使用示例

Base 類，父類有一個 add action，限制必填參數 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 注解指定要約束的參數，所以 add action 由于受到父類參數約束，所以必填參數 param1、param2。

<?php
namespace App\HttpController;

use EasySwoole\HttpAnnotation\Attributes\ExtendParam;

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

    }
}

黄p网站_在线看中文字幕_亚洲电影免费观看_成人激情视频_欧美成视频_中国av在线

Action 注解

Api

注解字段說明

apiName

allowMethod

requestPath

requestParam

responseParam

requestExamples

responseExamples

description

將 Api 注解的 requestPath 注入路由

使用示例

Param

使用示例

ExtendParam

使用示例

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