五月天激情丁香,国产精品2019,国产成人精品亚洲2020,国产精品免费视频一区二区三区,开心久久婷婷综合中文字幕,天堂视频在线观看免费完整版

Action 注解

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

Api

標記當前的 actionapi

注解字段說明

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 actionParam 注解的參數 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,限制必填參數 param1param2

<?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 類,子類控制器,重寫父類 Baseadd action,聲明 ExtendParam 注解指定要約束的參數,所以 add action 由于受到父類參數約束,所以必填參數 param1param2

<?php
namespace App\HttpController;

use EasySwoole\HttpAnnotation\Attributes\ExtendParam;

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

    }
}
主站蜘蛛池模板: 国产精品久久久久久久免费大片 | 国产第一页精品 | 日本一区二区三区久久久久 | 欧美色爱综合网 | 福利电影视频伦理片 | 国产精品久久久亚洲第一牛牛 | 人人看97| 99在线视频网站 | 免费观看美女网站 | 欧美成人在线观看 | 久久久久国产一级毛片高清版 | 中文字幕久久亚洲一区 | 国产免费高清在线精品一区 | 国产精选一区二区 | 地狱男爵2 | 国产亚洲小视频 | 久久综合精品国产一区二区三区无 | 日本xxxxx久色视频在线观看 | 日本高清不卡中文字幕 | 欧美日本高清 | 国产成人短视频在线观看免费 | 免费看av的网址 | 五月婷婷电影网 | 婷婷激情四月 | 午夜精品久久久 | 日本99视频| 成人短视频在线在线观看 | 欧美日韩在线亚洲国产人 | 欧美性生活视频播放 | 国产交换精品一区二区三区 | 免费萌白酱国产一区二区三区 | 欧美自拍视频 | 久久福利资源国产精品999 | 久久看精品 | 欧美在线区| 午夜精品久久久久久影视riav | 啦啦啦在线观看www 啦啦啦视频在线 | 视频在线观看你懂的 | 精品国产高清久久久久久小说 | 色视频网址 | 玖玖精品在线视频 |