Laravel 開發 RESTful API 的一些心得

DavidNineRoc發表於2018-03-01

最近用 Laravel 寫了一段時間的 API，總結一下自己的心得吧。

Start

API開發我們可以看到，有些網站用token驗證身份，有些用OAuth2.0，當時我也糾結，然後看到一個不錯的說法。大方面，會涉及到給別人用的使用OAuth，自己使用的用token就足夠了
設計最初，最好在路由加個版本號，方便以後擴充套件
```
Route::prefix('v1')->group(function () {
// more
});
```
如果前端想跨域，請使用這個很方便的包barryvdh/laravel-cors
一個簡單的介面示例

驗證
API 開發總會離不開驗證，這裡推薦使用jwt-auth，1.0 快要來了，新版本的文件也很清晰
剛用jwt-auth時有疑問，Laravel自帶的token驗證使用的是資料庫api_token欄位驗證，而不見jwt-auth需要這個
- 然後想自己看原始碼，結果QAQ
- 最後去問了官方 >_<
- 原來使用者的資訊已經儲存在token中加密
- 一開始有疑問，這樣儲存，不會被解密嗎(真為自己智商擔憂 !_!)
- 後來才想起，jwt一開始就執行php artisan jwt:secret生成了祕鑰
- 你不洩露就保證安全了~~~
  路由
當然使用官方api的路由Route::apiResource(),一條更比五條強
路由的名字當然是RESTful的方式
保持動詞，複數形式，見名知義
有些長的路由，應該用什麼分隔呢？
laravel用的是中劃線(-)，因為谷歌收錄時，按中劃線劃分關鍵字，國內的是按下劃線(_)收錄，具體看自己了，我是喜歡下劃線 >_<
更多看這裡：路由命名規範
表單驗證

可以使用控制器自帶的表單驗證，更推薦使用表單類,能分離都分離出去，控制器不要處理太多事情。

能分離的程式碼都不要吝嗇~~~

資料轉換
Laravel自帶的API Resource
用起來真的很方便，不過發現一個問題，--collection的格式總是轉不過來，後來直接放棄了
單個的使用Resources
集合的使用Resources::collection()發現，特別好用 >_<
不得不說，多對多關聯時，Laravel處理得太好了條件關聯
在上面這個例子中，如果關聯沒有被載入，則 posts 鍵將會在資源響應被髮送給客戶端之前被刪除。
在有不確定是否輸出關聯資料時，這是一個很有用的功能！！！
響應輸出

當時在 laravel-china 看到的這個帖子，然後覺得這個方式不錯，所以自己也這樣子，使用基類的方法統一響應輸出。

異常

異常算是一大手筆了，處理好異常，可以讓你的程式碼優雅很多。
\App\Exceptions\Handler::render方法可以捕獲到很多有用的異常，例如，我的程式碼是這樣寫的：

UnauthorizedHttpException這個是捕獲jwt異常
ValidationException這個是表單異常，捕獲之後，表單錯誤訊息可以很好的格式化，
ModelNotFoundException這個是模型找不到的異常，捕獲之後，可以直接在控制器直接這樣

// 未捕獲之前的寫法
public function show($id)
{
    $user = User::find($id);
    if (! $user) {

    }

    // do something
}

// 現在
public function show($id)
{
    $user = User::findOrFail($id);
}
// 甚至這樣
public function show(User $user)
{
    // do something
}

下面這兩個異常可以不捕獲，只是方便開發中檢視錯誤訊息
NotFoundHttpException404路由找不到的異常，沒什麼好說的了
MethodNotAllowedHttpException這個是方法不對應，比如你是get路由，卻post請求
文件
差點忘了這個，文件非常非常重要
我是不怎麼喜歡在註釋寫文件的
使用swagger-ui+swagger-edit
- 下載swagger-ui
- 只需要dist目錄的東西（其他可以刪除了）
- 下載swagger-editor
- 只要dist目錄的東西和根目錄的index.html
- 我還把swagger-editor的index.html改成了edit.html，然後把這兩個東西整合到同一個目錄（記得修改css,js的位置）
- 新建兩個檔案api.json,api.yaml 大概就和圖中差不多
- 要修改圖中箭頭所示成為api.json的位置
訪問edit.html可以書寫文件
- 編寫語法
訪問index.html可以檢視文件
在edit.html寫好之後，匯出json，然後貼上到api.json檔案
記得也把寫好的格式儲存到api.yaml，因為清楚快取之後，下次訪問時會消失
自己寫了一個packages
就方便建立控制器，驗證
所有控制器繼承重寫過的基類，響應輸出方便。
例如完整驗證只需要三秒鐘
- 第一秒: php artisan api:auth
- 第二秒: 出現圖代表成功;
- 第三秒: 拿出手臂的勞力士，確定只過了三秒
更多的使用：laravel-api-helper
工作和API開發有關，用到其他有經驗了再回來補補。

更多參考

RESTful API 設計指南