Laravel 开发 RESTful API 的一些心得

最近用 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-editorindex.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。

觉得本文对你有帮助?请分享给更多人。

原文发布于微信公众号 - 程序员宝库(chengxuyuanbaoku)

原文发表时间:2018-03-09

本文参与腾讯云自媒体分享计划,欢迎正在阅读的你也加入,一起分享。

发表于

我来说两句

0 条评论
登录 后参与评论

相关文章

来自专栏全华班

springcloud学习手册-zuul(概念和内容)

一、什么是Zuulzuul概念和内容 Zuul 框架原理图 官方英文说明 其中重点理解一下,下面这些。 首先Zuul是什么?其实Zuul是基于JVM的路由器和服...

24430
来自专栏张戈的专栏

CVE-2015-0235:Linux glibc高危漏洞的检测及修复方法

这几天复习运维知识,也没怎么关注业界新闻,可等我一关注,又“捅娄子”了,Linux 继上次CVE-2014-6271漏洞爆发以来,再次爆发一个严重漏洞:CVE-...

40740
来自专栏FreeBuf

弹性边界:如何利用环境变量进行提权

简介 尽管进程都设置了环境变量,它们往往被用户,开发者甚至是系统本身所忽略。对于一个像样的系统来说,环境变量就是其最根本,这里的系统包括但不仅限于Unix (...

31270
来自专栏邹立巍的专栏

Linux 的进程间通信:管道

管道,英文为 pipe 。这是一个我们在学习 Linux 命令行的时候就会引入的一个很重要的概念。管道是UNIX 环境中历史最悠久的进程间通信方式。本文主要说明...

1K20
来自专栏進无尽的文章

代码管理 | 创建并管理自己的公有Cocopods库

一是直接将这部分代码copy到绘本阅读这个项目中; 二是将语音评测这部分逻辑给抽取出来,然后在分别在两处使用。

30830
来自专栏建站达人秀

如何部署 Tomcat 站点

Tomcat 是 Apache 软件基金会(Apache Software Foundation)的Jakarta 项目中的一个核心项目,由 Apache、Su...

45820
来自专栏Java帮帮-微信公众号-技术文章全总结

Web-第二十七天 SVN使用【悟空教程】

为保障团队开发过程中人员沟通各方面成本的降低,必须使用一种有效的方式减少沟通环节,提高开发效率,对资源的共享进行管理。

20310
来自专栏轮子工厂

版本控制之助你开始使用 git 的简易指南

为什么要进行版本控制? 最简单的例子,当我们用文字处理软件工作时(如Word)时需要进行修改,而有时候又不确定修改的内容是不是需要的,因此会产生许多个文件,如图...

9940
来自专栏Vamei实验室

Linux开机启动(bootstrap)

计算机开机是一个神秘的过程。我们只是按了开机键,就看到屏幕上的进度条或者一行行的输出,直到我们到达登录界面。然而,计算机开机又是个异常脆弱的过程,我们满心期望的...

27780
来自专栏腾讯移动品质中心TMQ的专栏

JAVA代码覆盖率工具JaCoCo-实践篇

上周 JAVA代码覆盖率工具JaCoCo-原理篇 简单介绍了JaCoCo其生成覆盖率的基本原理,这周的实践篇的主要内容就是将原理应用到实践中,本篇内容全部都是具...

1.1K90

扫码关注云+社区

领取腾讯云代金券