本工具旨在通過一個包含簡單完備的介面描述，自動生成介面校驗、資料字典和其對應文件。
本工具包含介面管理和迴歸測試兩部分功能，本文只覆蓋介面管理功能。
運作方式
輸入 - 模板
↓
輸出 - 介面程式碼、資料字典程式碼、介面文件、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..."
}
建議使用vscode並安裝java lang support擴充套件，他可以提供模板的hint
配置JAVA_HOME環境變數，指向安裝的jdk
引入工具和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));
介面文件
生成的程式碼
生成的測試用例檔案
# __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除錯介面
從Eloquent模型到DTO
\App\Generated\xxxx\xxxModel::initFromEloquent($eloquentModel)
如果對應的key不相同，可以使用@DBField("name")指定對映，如果不指定，預設指向low dash的欄位
目前還沒想好如何在客戶端同步呼叫介面的程式碼，所以暫時不支援生成客戶端程式碼。而且服務端在開發時會建立獨立的分支，如何讓客戶端方便的同步其他分支的程式碼也是要考慮的地方。
本工具還在開發中，募集貢獻者，釋出正式版前，不建議應用於生產環境。
本作品採用《CC 協議》，轉載必須註明作者和本文連結