V2EX = way to explore
V2EX 是一个关于分享和探索的地方
现在注册
已注册用户请  登录
waitmoonman
V2EX  ›  PHP

Laravel 开发 RESTful API 的一些心得

  •  
  •   waitmoonman · 2018-03-01 22:32:24 +08:00 · 3052 次点击
    这是一个创建于 2219 天前的主题,其中的信息可能已经有所发展或是发生改变。

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

    Start

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

    一个简单的接口示例 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自带的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请求

    自己写了一个packages

    • 就方便创建控制器,验证
    • 所有控制器继承重写过的基类,响应输出方便。 laravel-api-helper
    • 例如完整验证只需要三秒钟
      • 第一秒: php artisan api:auth
      • 第二秒: 出现图代表成功; laravel-api-helper
      • 第三秒: 拿出手臂的劳力士,确定只过了三秒 手臂的手表
    • 更多的使用:laravel-api-helper

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

    更多参考

    RESTful API 设计指南

    第 1 条附言  ·  2018-03-01 23:15:32 +08:00
    ## 文档
    * 差点忘了这个,文档非常非常重要
    * 我是不怎么喜欢在注释写文档的
    * 使用`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`的位置
    ![api]( http://blog.shiguopeng.cn/wp-content/uploads/2018/03/a7f0534994a4abf19b686ded5195e367.png)
    * 访问`edit.html`可以书写文档
    * [编写语法]( https://www.gitbook.com/book/huangwenchao/swagger/details)
    * 访问`index.html`可以查看文档
    * 在`edit.html`写好之后,导出`json`,然后粘贴到`api.json`文件
    ![api]( http://blog.shiguopeng.cn/wp-content/uploads/2018/03/28833a92cc185b74dd5ad529d9ddcb7e.png)
    * 记得也把写好的格式保存到`api.yaml`,因为清楚缓存之后,下次访问时会消失
    第 2 条附言  ·  2018-03-01 23:15:54 +08:00

    文档

    • 差点忘了这个,文档非常非常重要
    • 我是不怎么喜欢在注释写文档的
    • 使用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的位置 api
    • 访问edit.html可以书写文档
    • 访问index.html可以查看文档
    • edit.html写好之后,导出json,然后粘贴到api.json文件 api
    • 记得也把写好的格式保存到api.yaml,因为清楚缓存之后,下次访问时会消失
    xxstop
        1
    xxstop  
       2018-03-01 22:47:22 +08:00
    mark laravel 的开发指南还是不错~
    关于   ·   帮助文档   ·   博客   ·   API   ·   FAQ   ·   我们的愿景   ·   实用小工具   ·   1063 人在线   最高记录 6543   ·     Select Language
    创意工作者们的社区
    World is powered by solitude
    VERSION: 3.9.8.5 · 31ms · UTC 19:07 · PVG 03:07 · LAX 12:07 · JFK 15:07
    Developed with CodeLauncher
    ♥ Do have faith in what you're doing.