Laravel 开发 RESTful API 的一些心得

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

Start

  • API 开发我们可以看到,有些网站用 token 验证身份,有些用 OAuth2.0,当时我也纠结,然后看到一个不错的说法。大方面,会涉及到给别人用的使用 OAuth,自己使用的用 token 就足够了
  • 设计最初,最好在路由加个版本号,方便以后扩展
    Route::prefix('v1')->group(function () {
    // more
    });
  • 如果前端想跨域,请使用这个很方便的包 barryvdh/laravel-cors

    一个简单的接口示例

    Laravel 开发 RESTful API 的一些心得

     

    验证#

  • 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 开发 RESTful API 的一些心得

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

    数据转换#

  • Laravel 自带的 API Resource
  • 用起来真的很方便,不过发现一个问题,--collection 的格式总是转不过来,后来直接放弃了
  • 单个的使用 Resources
  • 集合的使用 Resources::collection() 发现,特别好用 >_<
  • 不得不说,多对多关联时,Laravel 处理得太好了条件关联

    Laravel 开发 RESTful API 的一些心得

     

  • 在上面这个例子中,如果关联没有被加载,则 posts 键将会在资源响应被发送给客户端之前被删除。
  • 在有不确定是否输出关联数据时,这是一个很有用的功能!!!

    响应输出#

    当时在 laravel-china 看到的这个帖子,然后觉得这个方式不错,所以自己也这样子,使用基类的方法统一响应输出。

    异常#

    异常算是一大手笔了,处理好异常,可以让你的代码优雅很多。
    \App\Exceptions\Handler::render 方法可以捕获到很多有用的异常,例如,我的代码是这样写的:

    Laravel 开发 RESTful API 的一些心得

    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-editorindex.html 改成了 edit.html,然后把这两个东西整合到同一个目录(记得修改 css,js 的位置)
    • 新建两个文件 api.json,api.yaml 大概就和图中差不多
    • 要修改图中箭头所示成为 api.json 的位置

      Laravel 开发 RESTful API 的一些心得

       

  • 访问 edit.html 可以书写文档
  • 访问 index.html 可以查看文档
  • edit.html 写好之后,导出 json,然后粘贴到 api.json 文件

    Laravel 开发 RESTful API 的一些心得

     

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

    自己写了一个 packages#

  • 就方便创建控制器,验证
  • 所有控制器继承重写过的基类,响应输出方便。
  • 例如完整验证只需要三秒钟
    • 第一秒: php artisan api:auth
    • 第二秒:出现图代表成功;

      Laravel 开发 RESTful API 的一些心得

       

    • 第三秒:拿出手臂的劳力士,确定只过了三秒

      Laravel 开发 RESTful API 的一些心得

       

  • 更多的使用:laravel-api-helper

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

    更多参考

    RESTful API 设计指南

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


当神不再是我们的信仰,那么信仰自己吧,努力让自己变好,不辜负自己的信仰!

 

发表回复

您的电子邮箱地址不会被公开。 必填项已用*标注