Laravel 專案全自動介面管理（介面部分）

Kamicloud發表於2019-03-13
Laravel

本工具旨在通過一個包含簡單完備的介面描述，自動生成介面校驗、資料字典和其對應文件。
本工具包含介面管理和迴歸測試兩部分功能，本文只覆蓋介面管理功能。

運作方式

輸入 - 模板
↓
輸出 - 介面程式碼、資料字典程式碼、介面文件、postman檔案、客戶端程式碼（暫未支援）、異常響應（i18n暫未支援）

已支援資料型別

標量：Integer, String
列舉：任意自定義的列舉（字串 / 數字）
模型：包含多個欄位的組合型別
陣列：同級同結構的資料可以描述為陣列
介面：介面類似於模型，但資料需要被標記為Request或Response，用於區分是輸入資料還是輸出資料。
異常碼：全域性異常碼，可以在介面任意執行階段丟擲，終止執行並返回響應。

介面

假設我們需要一個獲取使用者歷史記錄的介面。
該介面使用auth中介軟體，請求POST，地址為http://{{host}}/api/v1/xxxxx/get_class_histories
請求引數為年月和分頁的頁數，都為可選引數，響應為ClassRecord的陣列。

        class Xxxxx {
            /**
             * 獲取歷史記錄，不限制時間區間
             * 先搜年月，後根據時間倒序獲取分頁
             */
            @Middleware("auth")
            @API(methods = {MethodType.POST})
            class GetClassHistories {
                /** 不填預設本年 */
                @Request
                @Optional
                Integer year;
                /** 不填預設本月 */
                @Request
                @Optional
                String month;
                /**
                 * 第幾頁
                 */
                @Request
                @Optional
                Integer page;
                @Response
                Models.ClassRecord[] histories;
            }
        }

模型

在上面的介面中提到了ClassRecord模型
下面為其資料描述，包含多個資料欄位，既有標量型別也有列舉和模型。
其中的Optional註解表示該欄位可以為null，其他模型略。

        class ClassRecord {
            Integer id;
            /** 註釋 */
            @Optional
            Integer sid;
            Integer pay;
            Integer useTool;
            /** 有時候需要用它搜尋 */
            Integer beginTime;
            /** Y-m-d H:i:s */
            String datetimeOfBeginTime;
            /** 開始時間周幾 */
            Enums.DayOfWeek dayOfBeginTime;
            /**
             * 註釋
             */
            @Optional
            Enums.ClassRecordFreeTry freeTry;
            /** 狀態 */
            Enums.ClassRecordStatus status;
            @Optional
            Models.Material material;
            /** 評價，可以為空 */
            @Optional
            Models.ClassComment classComment;
            @Optional
            Enums.ClassType classType;

            @Optional
            Models.Teacher teacher;
        }

列舉

從0開始自增的列舉資料

    /** 周幾，從週日開始 */
    enum DayOfWeek {
        SUNDAY,
        MONDAY,
        TWESDAY,
        WEDNESDAY,
        THURSDAY,
        FRIDAY,
        SATURDAY,
    }

手動指定了value的int列舉

    /**
     * 使用者狀態
     */
    enum UserStatus implements FixedEnumValueInterface {
        INIT(0),
        DISABLED(2),
        IN_CLASS(4),
        ;
        int value;

        UserStatus(int value) {
            this.value = value;
        }

        @Override
        public int getValue() {
            return value;
        }
    }

全域性錯誤碼

    /** 伺服器內部錯誤，等同於500 */
    SERVER_INTERNAL_ERROR(-1),
    /** 引數不合法 */
    INVALID_PARAMETER(-2),
    /** 介面已失效，應校驗是否是該版本介面已禁用，若已禁用客戶端應觸發升級提示 */
    API_DEPRECATED(-10),
    /** 等同於404 */
    API_NOT_FOUND(-11),
    /** 維護模式 */
    MAINTAIN_MODE(-20),
    /** 使用者未登入 */
    AUTH_FAILED(-100),
    /** 自定義的ERROR資訊 */
    CUSTOM_ERROR_MESSAGE(-10000),

JDK8
php 7.2
laravel 5.7
larecipe
php-parser
由於未釋出正式版，請使用composer指定github引入
{
"type": "vcs",
"url": "https://github.com/Kamicloud/api-generator.git"
}
建議使用vscode並安裝java lang support擴充套件，他可以提供模板的hint

配置JAVA_HOME環境變數，指向安裝的jdk
file
引入工具和larecipe
執行
php artisan larecipe:install
php artisan generator:install
將所需的檔案釋出到當前專案中
可以看到resources下generator出現templates、config、defines三個資料夾
templates即介面描述目錄，參考已存在的描述設計自己的介面
config中為配置資訊，建議使用預設配置

app/bin下是釋出後的命令
initGenerator會初始模板解析環境，如果使用composer update進行工具更新，需要重新執行該命令
generate將根據模板生成程式碼和文件

localhost/docs下為文件目錄
app/Http/Services/下為業務程式碼目錄，在$message中獲取對應的請求資料和setResponse
$message->setResponse(xxxxxModel::initFromEloquents($xxxx));

介面文件
file
file
生成的程式碼
file
生成的測試用例檔案


# __api: /api/api/v1/xxxxxxxxxx/get_class_histories
__enabled: true
__role: User
__user: 1
__anchor:
__params:
__testcases:
  -
    __params:
      year:
      month:
      page:
  -
    __params:
      year: 2019
      month: 3
      page:
  -
    __params:
      year: 2018
      month: 12
      page:

使用生成的postman除錯介面
file
從Eloquent模型到DTO
\App\Generated\xxxx\xxxModel::initFromEloquent($eloquentModel)
如果對應的key不相同，可以使用@DBField("name")指定對映，如果不指定，預設指向low dash的欄位

目前還沒想好如何在客戶端同步呼叫介面的程式碼，所以暫時不支援生成客戶端程式碼。而且服務端在開發時會建立獨立的分支，如何讓客戶端方便的同步其他分支的程式碼也是要考慮的地方。
本工具還在開發中，募集貢獻者，釋出正式版前，不建議應用於生產環境。

相關文章