Laravel 開發 RESTful API 的一些心得

最近用 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 設計指南