Laravel 开发 RESTful API 的一些心得

Posted 2021-05-02 SegmentFault

最近用 Laravel 写了一段时间的 API，总结一下自己的心得吧。

Start

API开发我们可以看到，有些网站用token验证身份，有些用OAuth2.0，当时我也纠结，然后看到一个不错的说法。大方面，会涉及到给别人用的使用OAuth，自己使用的用token就足够了

设计最初，最好在路由加个版本号，方便以后扩展。

 
   
   
 

  
    
    
  
Route::prefix('v1')->group(function () {
  
    
    
  
    // more
  
    
    
  
});
 
   
   
 

如果前端想跨域，请使用这个很方便的包barryvdh/laravel-cors(https://github.com/barryvdh/laravel-cors)

一个简单的接口示例：

验证

API 开发总会离不开验证，这里推荐使用jwt-auth，1.0 快要来了，新版本的文档也很清晰

刚用 jwt-auth时有疑问，Laravel自带的token验证使用的是数据库apitoken字段验证，而不见 jwt-auth需要这个。然后想自己看源码，结果 QAQ，最后去问了官方 ><，原来用户的信息已经存储在token中加密。一开始有疑问，这样保存，不会被解密吗(真为自己智商担忧 !_!)？后来才想起，jwt一开始就运行 php artisan jwt:secret生成了秘钥，你不泄露就保证安全了~~~

路由

当然使用官方 api的路由 Route::apiResource()，一条更比五条强。

路由的名字当然是RESTful的方式。

保持动词，复数形式，见名知义。

有些长的路由，应该用什么分隔呢？

laravel用的是中划线(-)，因为谷歌收录时，按中划线划分关键字，国内的是按下划线(_)收录，具体看自己了，我是喜欢下划线 >_<

更多看这里： 路由命名规范(https://laravel-china.org/courses/laravel-specification/502/router)

表单验证

可以使用控制器自带的表单验证，更推荐使用表单类(https://laravel-china.org/docs/laravel/5.5/validation#creating-form-requests),能分离都分离出去，控制器不要处理太多事情。

能分离的代码都不要吝啬~~~

数据转换

Laravel自带的API Resource

用起来真的很方便，不过发现一个问题， --collection的格式总是转不过来，后来直接放弃了。

单个的使用 Resources。

集合的使用 Resources::collection()发现，特别好用 >_<

不得不说，多对多关联时， Laravel处理得太好了，条件关联：https://laravel-china.org/docs/laravel/5.5/eloquent-resources#resource-responses。

在上面这个例子中，如果关联没有被加载，则 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(https://github.com/swagger-api/swagger-ui)

• 只需要 dist目录的东西（其他可以删除了）

• 下载swagger-editor(https://github.com/swagger-api/swagger-editor)

• 只要 dist目录的东西和根目录的 index.html

• 我还把 swagger-editor的 index.html改成了 edit.html，然后把这两个东西整合到同一个目录（记得修改css,js的位置）

• 新建两个文件 api.json, api.yaml 大概就和图中差不多

• 要修改图中箭头所示成为 api.json的位置

访问 edit.html可以书写文档，编写语法：https://www.gitbook.com/book/huangwenchao/swagger/details。

访问 index.html可以查看文档。

在 edit.html写好之后，导出 json，然后粘贴到 api.json文件。

记得也把写好的格式保存到 api.yaml，因为清楚缓存之后，下次访问时会消失

自己写了一个packages

就方便创建控制器，验证，所有控制器继承重写过的基类，响应输出方便。

例如完整验证只需要三秒钟：

第一秒： php artisan api:auth

第二秒：出现图代表成功。

第三秒：拿出手臂的劳力士，确定只过了三秒。

更多的使用：laravel-api-helper(https://github.com/DavidNineRoc/laravel-api-helper)

工作和API开发有关，用到其他有经验了再回来补补。

更多参考

RESTful API 设计指南：http://www.ruanyifeng.com/blog/2014/05/restful_api。

---

相关文章推荐

---