Laravel 开发 RESTful API 的一些心得

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

Start#

• API 开发我们可以看到，有些网站用 token 验证身份，有些用 OAuth2.0，当时我也纠结，然后看到一个不错的说法。大方面，会涉及到给别人用的使用 OAuth，自己使用的用 token 就足够了
• 设计最初，最好在路由加个版本号，方便以后扩展

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

• 如果前端想跨域，请使用这个很方便的包 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
}Copy

• 下面这两个异常可以不捕获，只是方便开发中查看错误消息
  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 设计指南

本作品采用《CC 协议》，转载必须注明作者和本文链接