RESTful API接口

WEB发展阶段

        静态内容阶段，在这个最初段，使用 Web 的主要是一些研究机构。 Web 由大量的静态 HTML 文档组成。
        cgi 程序阶段：在这个阶段， Web 服务器增加了一下编程API,通过API编写的应用程序，可以向用户提供动态变化的内容。
        脚本语言阶段：出现了ASP，PHP，JSP等支持SESSION的脚本语言技术，浏览器端出现了Java Applet，JavaScript技术，提供更加丰富的动态内容
        瘦客户端应用阶段：在这个阶段，在服务器端出现了独立于Web服务器的应用服务器，出现webMVC 开发模式，各种 web mVC开发框架逐渐流行，占据统计地位。据于这些框架开发的都是，因为它们是在服务器端生成全部内容。
        RIA应用阶段：在这个阶段，出晚了多种RIA「 Ricch internet Application ）技术，改善了 Web应用的用户体验。应用最为广泛的技术DHTML + Ajax，Ajax技术支持在不刷新页面的情况下动态更新页面中的局部内容。同时至生了大量的 DHTML开发库，prototype. Dojo,extjs，JQuery/jQuery UI,element UI,layer UI

        移动 Web 应用阶段：在这个阶段，出现了大量面向移动设备的Web开发技术。除Android，IOS等操作系统平台原生的开发技术外，基于HTMLS 的开发流行

前后端分离开发技术

传统开发技术

       前端写好静态的html页面交给后端开发，后端把html改成模板，然后使用模板引擎去套模板，比如jsp，freemarker等后人员在开发过程中如果发现页面有问题，要返回给前端修改，前端再交给后端，直至功能实现。

问题：前后产重耦合

1.前端需要改bug调试时，需要在当前电脑安装一整套后端的开发工具，启动后端程序。
2.还要求后端人员会html，js等前端语言。

3.前端页面也会嵌入很多后端的代码。一旦后端换了一套语言，前端也需要重新开发

4.沟通成本，调试成本，前后端开发进度相互影响，从而大大降低开发效率前后端分离

前后端开发技术

       前后端分离并不只是开发模式，也是web应用的一种架构模式

在开发阶段，前后人员约定好数据交互接口，即可并行开发与测试。前端开发完成可以独自进行mock测试，后也可以使用postman等接口测试工具进行测试。最后可进行功能联调测试。

优点：

1.前后责任清晰，后专注于数据上，前端专注于视觉上。

2.无需等待对方的开发工作结束，提高开发效率

3.可应对复杂多变的前端需求

4.增强代码可维护性 

        不使用RESTful API风格，可能会造成不同开发者，PC浏览器、APP、小程序开发者在开发时要不断地查询。同时对于同一个操作比如添加用户：

        http://localhost/employee/new

        http://localhost/employee/create

        http://localhost/employee/add

        http://localhost/employee/xinzeng

        http://localhost/employee/save

接口设计

传统接口设计要考虑的问题

请求路径——望名知意
请求方式——get、post，采用@requestMapping时传统方式会忽略
请求参数
请求响应——模板路径/由需求决定

@Controller
publicclass EmployeeController
{
    @requestMapping("/employee/list") 
    public String list(Model model)
    {
        model.addAttribute("list",employeeService.list());
        return "employee/list";
    }
}

RESTful API设计

请求路径——当前接口操作的资源决定，一般使用资源复数，
请求方式——请求方式+请求路径，决定操作方式和内容(GET,POST,PUT,DELETE)
请求参数
请求响应——JSON格式

@Controller
publicclass EmployeeController
{
    @requestMapping(value="/employees",method=RequestMethod.GET) 
    @ResponseBody
    public List<Employee> list()
    {
        return employeeService.list());
    }
}

参考

REST API 返回码汇总

HTTP CODE	CODE	MESSAGE	DESC
200	3000	success	请求成功
400	3001	missing auth	auth 为空
401	3002	auth failed	auth 鉴权失败
400	3003	missing body	body 为空
403	3004	invalid body	body 无效
400	3005	parameter invalid	参数错误
403	3006	out of freq	请求超频
404	3007	api not found	API 不存在
405	3008	request method not support	请求方法不支持
405	3009	app in black	应用被列为黑名单
405	3010	this is vip function, pls contact to sales@jiguang.cn	vip功能，请联系商务咨询vip功能
500	3011	server error	服务端异常

WEB发展阶段

格式

        http（s）：/域名：端口[/版本]/资源1[/子资源2/../子资源n][/路径变量]

        多版本控制

GET http(s): //edu.51cto.com/v1.1/blog/article/10

        返回数据集合时，资源名为复数

GET http(s)://edu.51cto.com/v1.1/blog/articles?categoryld=10

        反面典型

GET http(s): //edu.51cto.com/article/select_by_id?id=10

URL: http://somehost/tvseries

GET /tvseries 获取电视剧列表

POST /tvseries 创建一个新电视剧

GET /tvseries/101获取编号为101的电视剧信息

PUT /tvseries/101修改编号为101的电视剧信息

DELETE /tvseries/101删除编号为101的电视剧

GEI /tvseries/101/characters获取编号为101的电视剧的人物列表

GET /tveries/{id}/**s

请求类型的含义

• GET(SELECT):从服务器取出资源
• POST(CREATE):在服务器新建一个资源
• PUT(UPDATE):在服务器更新资源（跟新所有属性）
• PATCH(UPDATE):更新部分属性，一般不用，用put
• DELETE(DELETE):从服务器删除资源

相同的URL请求类型不同，功能也不同

GET http(s): //edu.51cto. com/employee/10

表示查询10号员工的信息，但是请求换成POST，同时在请求体附加员工JSON数据，就代表在服务器数据库中新增一个编号为10的员工。

POST http(s): //edu.51cto.com/employee/10

("id":10,"name":"张三"，"age”:36} 

类似的，PUT代表更新员工数据。

PUT http(s): //edu.51cto. com/employee/10
("id":10,"name”:“张三”，"age”:38) 

DELETE代表删除员工数据。

DELETE http(s): //edu.51cto.com/employee/10

RESTful API接口设计规则和注意事项

保证幂等性设计

        幂等性：当多次重复请求时，接口能够保证与预期相符的结果        例如：我们设计了一个为员工涨薪的接口，本次请求发送后为1号员工涨薪500元。基于版本号的乐观锁机制

PUT https: //edu.lagou.com/employee/salary

{"id": "1, "incr_salary": 500}

       在分布式环境下，为了保证消息的高可靠性，往往客户端会采用重试或者消息补偿的形式重复发送同一个请求，那在这种情况下这段代码就会出严重问题，每一个重复请求被发送到服务器都会让该员工工资加500，最终该员工工资会大于要求实际应收工资。

        在行业中有一种乐观锁设计，在工资表额外增加一个version的字段，代表当前数据的版本，任何对该数据修改操作都会让version字段值+1，这个version的数值要求附加在请求中。

PUT https: //edu.lagou.com/employee/salary ("id":"1",incr_salary":500,"version":1}

        而服务器端代码也作出如下调整，SOL语句要增加版本号的比对。

//查询1号员工数据
Employee employee = employeeService.selectById(1)；
//更新工资
employee.setSalary(employee.getSalary()+incrSalary)；
//update执行成功，版本号+1
employee.setVersion(employee.getVersion() + 1);
//执行更新语句
employeeService.update(employee)
update方法除了id条件外，还要增加yersion的判断，如下所示：
当执行成功后，1号员工原始数据将工资更新为3500，版本为2
update employeee set salary = 3500, version=2 where id = 1 and version = 1

标准化响应结果集

     

       在标准化的响应结构中要包含code、message两项，分别对应了服务器处理结果与返回的消息内容，除此以外data属性是可选项，包含从响应返回的额外数据，如查询结果、新增或更新后的数据。

       在语义层面，也要遵循相同的规则。例如当服务器处理成功，code固定等于0，如果遇到异常情况，公司内部也要遵循统一的code命名标准例如：code以1xxx开头代表参数异常，2xxx开头代表数据库处理异常。当然不同的公司有不同的命名规则，一定要提前定义好并严格要求开发团队严格按语义使用编码。

接口设计采用无状态方案

       当后台有多个tomcat，如果身份验证采用session验证，在不同的tomcat服务器上可能出现状态不一样。

解决方案1：客户端存储认证数据，如cookie，但是不安全，容易窃取和仿造，需加密存储，如jwt

解决方案2：服务端统一存储状态数据，如redis则可以避免该问题实现统一验证。

资源表现形式

1.Content-Type可以放在request headers，也可以放在response headers，分别表示客户端/服务端本次发送的数据类型
2.Accept表示客户端希望接收的数据类型，只能在request的头部