什麼是StubApi
StubApi旨在為Laravel專案及其客戶端提供一個功能強大、便捷、無侵入、可插拔的介面管理工具。
注：該工具推薦中高階Laravel開發者引入，因為要熟悉Laravel專案結構和原理。實際使用
不需要掌握java，因為介面描述參照已有的寫就可以了。
功能強大
在StubApi中，有五種核心的資料元素：介面、傳輸資料模型（DTO）、標量資料、列舉、異常碼。基於這些資料元素，實現了介面資料型別規範、介面版本控制、全域性列舉值等功能。
便捷、無侵入
與傳統的介面管理工具不同，StubApi不要求使用者在模型中寫繁瑣的校驗規則，也不要求使用者為了資料響應建各種資源類，更不會用service provider或middleware汙染其他介面。
介面所有的功能，都可以通過一小段宣告式的程式碼達到目的。
可插拔
即便有一天你不需要StubApi，只需要保留三四個必要的基類檔案，移除整個包都可以！
新版特色
不再依賴javadoc，支援jdk8-12
在預覽版中，為了從介面模板同步註釋到程式碼和文件中，使用了javadoc。而從jdk9開始javadoc做了一個大重構，為了避免限制使用者jdk版本，我改回使用javaparser（僅對於註釋），因而不再需要手動設定JAVA_HOME環境變數。
service層改為成員方法
在controller -> service 的呼叫中，原本是呼叫service中的靜態方法，改為呼叫成員函式，service支援建構函式依賴注入（考慮過成員方法也支援依賴注入，但覺得不太常用，所以沒有去支援）。
豐富了配置項
現在包括生成程式碼的基類等都可以自定義並更換。
場景舉例：希望更改響應格式規則，可以自定義Message基類，生成的程式碼將會使用你新增的基類。
完善了模板繼承規則
現在DTO可以相互繼承，模板表達力更強。繼承只為表達資料結構的關係和特點，所以生成後的程式碼只會繼承結構，而不保留繼承關係。
支援了message getter的型別提示
在service層獲取請求引數會有型別提示
/**
* 頁面路徑
* @return string
*/
public function getPath()
{
return $this->path;
}
支援自定義資料型別
可以自由新增需要的引數規則，如Y-m格式的時間，或對mime有特殊要求的檔案。這些校驗規則與自定義的laravel validator相容。
支援通過模板方式生成程式碼（暫未開放）
舊版本都是通過Writter方式，用java拼字串並匯出成檔案的方式生成程式碼，未來會改為都用模板生成，使用者可以自定義（模板引擎為thymeleaf）。
介面響應流程
一個成功響應的生命週期
// 從請求中封裝Message
public function feedback(FeedbackMessage $message)
{
// 驗證請求資料
$message->validateInput();
// 呼叫使用者邏輯層
$this->handler->feedback($message);
// 驗證使用者設定的響應是否符合介面規則
$message->validateOutput();
// 返回響應
return $message->getResponse();
}
使用者邏輯實現
/**
* @param PublishesMessage $message
* @throws CustomErrorMessageException
*/
public function publishes(PublishesMessage $message)
{
// 獲取請求引數
$page = $message->getPage();
$type = $message->getType();
$city = $message->getCity();
$serviceTypes = $message->getServiceTypes();
$workerTypes = $message->getWorkerTypes();
$user = Auth::user();
// 一些邏輯相關的校驗，如訂單未結束不能發起退款，可以直接用一個異常響應結束請求
if (!$user) {
throw new CustomErrorMessageException('使用者不存在時的異常');
}
// 注入一個邏輯Manager，這樣多版本service將會重複更少的程式碼
$publishes = $this->publishManager->getPublishes(
$user,
$city,
$type,
$workerTypes,
$serviceTypes,
$page
);
// 設定響應，請求結束
$message->setResponse(PublishModel::initFromEloquents($publishes));
}
正式版使用方式
安裝
引入
composer require kamicloud/stub-api安裝jdk （可用oracle jdk代替）
brew tap adoptopenjdk/openjdk
brew cask install adoptopenjdk8
使用
php artisan stub-api:install此時會在根目錄建立一個bin檔案
cd bin
./initGenerator使用jdk編譯工具
./generate當工具編譯完成後，編譯自己的模板並生成程式碼
配置
路由（假設直接使用Laravel下的api路由）
這裡的目的是把路由指向自動生成的控制器
app/Providers/RouteServiceProvider.php
protected function mapApiRoutes()
{
Route::prefix('api')
->middleware('api')
->namespace('App\Generated\Controllers')
->group(base_path('routes/api.php'));
}引入路由檔案
routes/api.php
include_once 'generated_routes.php';在對應的路由規則中加入一個工具中介軟體
\Kamicloud\StubApi\Http\Middleware\GeneratorMiddleware
他只在你env 為testing時或開啟debug才有用，所以也可以不引入這個中介軟體。功能如傳__test_mode會自動回滾資料庫，具體請看實現程式碼。
更換異常處理基類，或者參考工具提供的基類自己實現
Kamicloud\StubApi\Exceptions\Handler
寫程式碼
模板預設在 resources/generator/templates 下
參考舊模板使用教程
一些注意事項
列舉值的getter
由於列舉值可以用@StringEnum傳輸字串列舉，所以getter的返回值可能是integer也可能是string，不太好修就暫時標記返回為mixed。
時間傳輸格式和對應的getter
工具提供了兩個配置項，getter返回值也是mixed
/**
* 預設時間的傳輸格式為字串
*
* 開啟後傳輸格式為整型
*/
'request-date-timestamp' => false,
'response-date-timestamp' => false,
建議引入工具時按需引入，指定版本號
版本更新相容性說明
由於釋出正式版，未來在小版本更新時如1.0.10 到 1.0.11，除為修復bug，將相容舊版本模板、註解、配置項。
中版本更新如1.0 到 1.1將相容舊版本的模板和註解，配置項變動將提供更新指南。
大版本更新可能修改模板格式、一些註解和生成規則等。