• 1. Laravel5 学习分享 Auth: helei Date: 2015年7月——API设计与自动化API文档生成
  • 2. 分享主题 为什么用Laravel5 RESTful 风格API简介 Laravel5 API自动文档介绍
  • 3. Laravel5框架团队开发框架
  • 4. 个人开发框架个人使用后的感觉: Laravel是PHP 5.3之后开发的新框架,充分使用了PHP 5.3之后的新特性,不像很多老牌框架有一大堆历史包袱。 使用composer来进行项目管理 全栈式框架,可管理前端资源,可进行自动化测试 便于开发出低耦合的项目 优质的文档,社区活跃,便于找到问题的解决方案
  • 5. RESTful 风格API简介Laravel为什么要自定义路由 有过tp开发经验,或者用过java SSH2框架的,都知道只要按照规则写好控制器,那么通过制定的uri就可以访问相应的控制器了。在laravel中则不行,写好控制器,想要访问其中的方法,还必须定义好相关的路由,才能访问控制器中的方法。 例子: TP访问的URI:http://yourdomain/Home/index开箱即用,方便但不灵活 Eg1:如果想使用http://yourdomain/home/1访问Home控制器中的show方法,并传入参数1,需要经过复杂配置 Eg2:限制个别方法只能通过post或者get方法访问到,TP需要做出复杂的改变,甚至需要修改框架内核
  • 6. 为了解决以上存在的问题,所以有了laravel的路由自定义 能够设定路由组,在路由组中增加中间件,以实现对一组路由的处理 自带RESTful风格路由,laravel已经完美封装了各类请求携带的参数 限制某些方法只能通过特定请求方式进行访问(如只能get,不能post等)。RESTful的前世今生首次出现在 2000 年 Roy Fielding 的博士论文中,他是 HTTP 规范的主要编写者之一。 简单来说,RESTful架构就是一组约束条件和规则: 1. 每一个URI代表一种资源。 2. 客户端和服务器之间,传递这种资源的某种表现层。 3. 客户端通过四个HTTP动词(GET、POST、PUT、DELETE),对服务器端资源进行操作,实现"表现层状态转化"。
  • 7. 比如一个电影的网站,REST 的 URI 可设计为: GET        http://api.douban.com/movies              //电影列表 GET        http://api.douban.com/movies/123      //查看某部电影 POST      http://api.douban.com/movies              //添加电影 PUT        http://api.douban.com/movies/123      //修改某部电影 DELETE  http://api.douban.com/movies/123      //删除某部电影 错误的REST 的 URI 设计 就是URI包含动词,因为"资源"表示一种实体,所以应该是名词,URI不应该有动词,动词应该放在HTTP协议中。 某个URI是/posts/show/1,其中show是动词,这个URI就设计错了,正确的写法应该是/posts/1,然后用GET方法表示show。 如果某些动作是HTTP动词表示不了的,你就应该把动作做成一种资源。比如网上汇款,从账户1向账户2汇款500元,错误的URI是: POST /accounts/1/transfer/500/to/2 正确的写法是把动词transfer改成名词transaction,资源不能是动词,但是可以是一种服务: POST /transaction HTTP/1.1 Host: 127.0.0.1    from=1&to=2&amount=500.00这里主要注意,PUT|DELETE|PATCH请求不被form表单原生支持。但是laravel框架已经支持。可通过方法欺骗来进行使用。
  • 8. RESTful API 设计 处理单个资源 GET /movies # 获取movie列表 GET /movies/12 # 查看某个具体的movie POST /movies # 新建一个movie PUT /movies/12 # 更新movie 12. DELETE /movies/12 #删除movie 12 拆分资源原则:它们应该是有意义于 API 使用者的名词(不是动词)——API的就是程序员的UI,和其他UI一样,你必须仔细考虑它的用户体验!设计要求 1. 当标准合理的时候遵守标准。(RESTful设计原则) 2. API应该对程序员友好,并且在浏览器地址栏容易输入。 3. API应该简单,直观,容易使用的同时优雅。 4. API应该具有足够的灵活性来支持上层ui。 5. API设计权衡上述几个原则。可以看出使用REST的好处在于可以充分利用http的强大实现对资源的CURD功能。而这里你只需要一个endpoint:/movies,再没有其他什么命名规则和url规则了,cool!API概念: 它是一个桥梁作用。想要达到某个目的,需要通过一个路径,把达到这个目的的条件传递过去。
  • 9. 处理资源之间的关系 GET /movies/12/messages - 获取movie #12下的消息列表 GET /movies/12/messages/5 - 获取movie #12下的编号为5的消息 POST /movies/12/messages - 为movie #12创建一个新消息 PUT /movies/12/messages/5 - 更新movie #12下的编号为5的消息 PATCH /movies/12/messages/5 - 部分更新movie #12下的编号为5的消息 DELETE /movies/12/messages/5 - 删除movie #12下的编号为5的消息 版本控制 方式一:应该将API的版本号放入URL。(微博与github放置主版本号) 方式二:将版本号放在HTTP头信息中。(不直观) 采用方式一 + 方式二的设计: URL包含一个主版本号(比如http://domain /v1/movies/12) 通过配置HTTP请求头设置此版本号 这种情况下,主版本确保API结构总体稳定性,而子版本会考虑细微的变化(field deprecation、接入点变化等)。 结果过滤,排序和搜索 ?state=open;指定筛选条件 ?sortby=name&order=asc;指定返回结果按照哪个属性排序,以及排序顺序。 ?limit=10;指定返回记录的数量 ?offset=10;指定返回记录的开始位置。 ?page=2&per_page=100;指定第几页,以及每页的记录数。 ?fields=id,subject,customer_name,updated_at;限制api返回哪些字段——通过基本URL之上的查询参数来轻松实现
  • 10. 自动装载相关的资源描述 在很多种情况下,API的使用者需要加载和被请求资源相关的数据(或被请求资源引用的数据)。与要求使用者反复访问API来获取这些信息相比,允许在请求原始资源的同时一并返回和装载相关资源,将会带来明显的效率提升。 Eg:如获取某一个商品的同时,不仅仅传递出商品的基本信息,还会传递出商品卖家的一些信息, 此处需要注意的是N+1 select问题 访问频率限制(本期暂不使用) 为了防止滥用,标准的做法是给API增加相关的访问频率限制(eg:微信某些关键接口就增加了每天调用次数的限制)。 可使用一下http头来达到目的: X-Rate-Limit-Limit - 当期允许请求的次数 X-Rate-Limit-Remaining - 当期剩余的请求次数 X-Rate-Limit-Reset - 当期剩余的秒数 缓存机制 Http提供了etag标签来进行缓存的判别,执行流程: 1. 客户端首次访问一个Rest API,后端返回一串JSON数据,并在请求头中添加一个Etag标签,这个标签对应的是一个用MD5或者SHA1等哈希算法来生成的信息指纹(关键是唯一标识,如常见的GUID)。 2. 客户端保存这个Etag值,再次发起请求的时候,以If-None-Match作为Key添加到请求头中 3. 服务端校验请求头中的Etag数据,并跟当前将要输出数据的指纹做校验,如果一致,则表明没有更改,返回状态码为304,如果不一致, 则返回200,并将新的Etag同时返回,以便下次客户端请求时使用
  • 11. 错误处理 如果状态码是4xx或5xx,就应该向用户返回出错信息。这里需要注意的是错误分为给前端开发人员查看及用户查看两类。 对PUT, PATCH和POST请求进行错误验证将需要一个字段分解。下面可能是最好的模式:使用一个固定的顶层错误代码来验证错误,并在额外的字段中提供详细错误信息,就像这样: 对于普通的GET请求服务器返回结果 GET /collection:返回资源对象的列表(数组) GET /collection/resource:返回单个资源对象 POST /collection:返回新生成的资源对象 PUT /collection/resource:返回完整的资源对象 PATCH /collection/resource:返回完整的资源对象 DELETE /collection/resource:返回一个空文档
  • 12. 状态码 服务器向用户返回的状态码和提示信息,常见的有以下一些(方括号中是该状态码对应的HTTP动词)。 200 OK  - [GET] -服务器成功返回用户请求的数据 201 Created - [POST/PUT/PATCH] -用户新建或修改数据成功。(规范要求返回一个指向该资源的URI) 202 Accepted - [*]:表示一个请求已经进入后台排队(异步任务) 204 No Content - [DELETE] - 对一次没有返回主体信息(像一次DELETE请求)的请求的响应 304 Not Modified - [GET] - 当使用HTTP缓存头信息时使用304 400 Bad Request - [POST/PUT/PATCH] - 请求是畸形的, 比如无法解析请求体 401 Unauthorized - [*] - 当没有提供或提供了无效认证细节时。如果从浏览器使用API,也可以用来触发弹出一次认证请求 403 Forbidden - [*] -表示用户得到授权(与401错误相对),但是访问是被禁止的(访问私有方法)。 404 Not Found - [*] -用户发出的请求针对的是不存在的记录,服务器没有进行操作 405 Method Not Allowed - [*] - 当一个对认证用户禁止的HTTP方法被请求时(本该用post访问,结果使用了get方法) 406 Not Acceptable - [GET]:用户请求的格式不可得(比如用户请求JSON格式,但是只有XML格式)。 410 Gone - [GET] - 表示资源在终端不再可用。当访问老版本API时,作为一个通用响应很有用 415 Unsupported Media Type - [GET] - 如果请求中包含了不正确的内容类型 422 Unprocessable Entity - [POST/PUT/PATCH] - 出现验证错误时使用 429 Too Many Requests - [*] - 当请求由于访问频率限制而被拒绝时 500 INTERNAL SERVER ERROR - [*]:服务器发生错误,用户将无法判断发出的请求是否成功。
  • 13. Api升级 当app做了大改版后,可能会出现一个问题,发现现在的api已经不适了,就考虑到api的升级,同时为了兼容已经发布的app,原来的api必须要保留。为了避免同一个app中调用不同版本的api,一般就会全部升级api的版本,例如:原来的是“test.com/v1/statuses/destroy”,升级为“test.com/v2/statuses/destroy”。 这里升级有两点需要控制好: 1. v2版本的api的controller必须要继承v1版的controller,v2版本的api只重写需要改动的api。 2. 在线api测试文档中详细标明返回内容,已作对比,方便客户端人员的调试。
  • 14. Laravel5 API自动文档介绍本工具采用Swagger-UI + Swagger-PHP开发而成,仅适用于Laravel5 工具主要使用注解来自动生成前端页面需要的json。只要在Controller与Model中写好注释即可。 该文档工具,可在线进行测试 文档实时更新,便于前端开发人员获取最新接口信息
  • 15. (本页无文本内容)
  • 16. (本页无文本内容)