Laravel 專案全自動介面管理（常用註解與對應生成程式碼）

Kamicloud發表於2019-04-03
Laravel

介面工具使用註解來增強介面表達能力。在一般情況下，一個註解只會產生一種效果，如表示資料欄位可以為空（Optional）、強制從Eloquent中指定欄位獲取資料（DBField）、控制器使用指定中介軟體（Middlewares）等。

元註解

@Extendable

該註解只能使用在註解上，被該註解修飾的註解會由父節點向子節點傳遞，而當子節點存在和父節點相同的註解時，子節點的註解會覆蓋父節點註解。典型例子是Middlewares註解，在Contrller上使用Middlewares註解，其下的每個Action都將預設使用相同的Middlewares。

示例

@Retention(RetentionPolicy.RUNTIME)
@Extendable
public @interface Middleware {
String[] value() default "";
}

API級註解

@Middlewares(String[])

指示Controller/Action使用指定的中介軟體

示例

            @Middleware("auth")
            class GetUsers {
            }

生成程式碼效果

Route::match(['POST'], '/v1/user/get_users', 'V1\UserController@GetUsers')->middleware(['auth']);

@Methods(MethodType[])

表示HTTP請求型別

為了測試方便，所有介面都支援POST方式請求，呼叫方可以根據實際情況使用合適的方式。

引數

public enum MethodType {
    GET, POST, PUT, PATCH, DELETE, UPDATE;
}

示例

            @Methods({MethodType.POST})
            class GetUsers {
                @Request
                String[] strings;
                @Request
                int[] ints;
            }

生成程式碼效果

Route::match(['POST', 'POST'], '/v1/admin_user/get_users', 'V1\AdminUserController@GetUsers');

@Request / @Response

標註該資料欄位應出現在請求中或響應中。

示例

            /**
             * 取得一篇文章
             */
            class GetArticle {
                @Request
                Integer id;
                @Response
                Models.Article article;
            }

生成程式碼

    public function requestRules()
    {
        return [
            ['title', 'title', 'bail|String', null],
            ['content', 'content', 'bail|String', null],
        ];
    }

    public function responseRules()
    {
        return [
            ['article', 'article', ArticleModel::class, Constants::IS_MODEL],
        ];
    }

模型註解

@DBField(String)

該註解只能用在欄位上
當從json或Eloquent中初始化資料時，如果介面傳遞資料的key和資料來源的key不同，可以指定資料來源為引數中的key。
如果不使用該註解，預設獲取small snake傳遞small camel。

示例


        /**
         * 模擬一個老師的資訊
         */
        class Teacher {
            @DBField("id")
            int teacherId;
        }

生成效果


    public function getAttributeMap()
    {
        return [
            ['teacherId', 'id', 'bail|int', null],
        ];
    }

欄位級註解

@Optional

表示欄位是可以為空的，在資料欄位自動過濾時，將允許空欄位通過。

示例


        class Article {
            @Optional
            @Mutable
            Integer id;
        }

生成程式碼


    public function getAttributeMap()
    {
        return [
            ['id', 'id', 'nullable|bail|Integer', Constants::IS_OPTIONAL],
        ];
    }

列舉註解

@StringEnum

欄位規則不使用自增ID，而改用實際對應的key。
示例

        @StringEnum
        enum PayWay {
            WECHAT,
            ALIPAY,
        }

生成程式碼

class PayWay extends Enum
{
    public const WECHAT = 'WECHAT';

    public const ALIPAY = 'ALIPAY';

    public const _MAP = [
        self::WECHAT => 'WECHAT',
        self::ALIPAY => 'ALIPAY',
    ];

}

@AsBO

將不止生成帶版本資訊的列舉，還會根據currentTemplate中的資訊生成一份列舉程式碼（BO）。
後續將允許該註解使用在model上。

示例

        @StringEnum
        @AsBO
        enum PayWay {
            WECHAT,
            ALIPAY,
        }

生成程式碼

<?php

namespace App\Generated\BOs\Enums;

use YetAnotherGenerator\BOs\Enum;

class PayWay extends Enum
{
    public const WECHAT = 'WECHAT';

    public const ALIPAY = 'ALIPAY';

    public const _MAP = [
        self::WECHAT => 'WECHAT',
        self::ALIPAY => 'ALIPAY',
    ];

}

測試相關注解

@Mutable

在使用自動迴歸測試時，將會將欄位轉換為*，表示該欄位不需要校驗。

示例

        class Article {
            @Optional
            @Mutable
            Integer id;
            String title;
            @Optional
            String content;
            Models.User user;
            Enums.ArticleStatus status;
            @Optional
            Integer commentsCount;
            /**
             * 需要時用於標記是否收藏
             */
            @Optional
            Boolean favorite;
            /**
             * 是否是新增火熱標記
             */
            @Optional
            Boolean hot;
            Date createdAt;
        }

效果

{
    "status": 0,
    "message": "success",
    "data": {
        "articles": [
            {
                "id": "*",
                "title": "nf1s4836nntQxE2oWWvk",
                "content": null,
                "user": {
                    "name": "Ttdnts",
                    "id": "*",
                    "avatar": "https://avatars3.githubusercontent.com/u/25639206?s=88&v=4"
                },
                "status": 1,
                "commentsCount": 1,
                "favorite": null,
                "hot": null,
                "createdAt": "2018-12-30 16:11:32"
            },

相關文章