程序员入职避免挨骂小知识-RESTful风格

一、什么是API(应用程序编程接口)

    API（Application Programming Interface，应用程序接口）是一些预先定义的接口（如函数、HTTP接口），或指软件系统不同组成部分衔接的约定。 用来提供应用程序与开发人员基于某软件或硬件得以访问的一组例程，而又无需访问源码，或理解内部工作机制的细节。

    应用接口：很多情况下,需要把系统的功能作为服务暴露给外部的其他应用使用,就需要把系统中的服务作为API接口暴露出去,一般分为公共接口(发短信,天气服务)和私用接口(公司内部使用的)。

二、Web 技术的发展阶段

    Web 开发技术的发展可以粗略划分成以下几个阶段

1. 静态内容阶段：在这个最初的阶段，使用 Web 的主要是一些研究机构。Web 由大量的静态 HTML 文档组成。
2. CGI 程序阶段：在这个阶段，Web 服务器增加了一些编程 API。通过这些 API 编写的应用程序，可以向客户端提供一些动态变化的内容。。
3. 脚本语言阶段：在这个阶段，服务器端出现了 ASP、PHP、JSP、ColdFusion 等支持 session 的脚本语言技术，浏览器端出现了 Java Applet、JavaScript 等技术。使用这些技术，可以提供更加丰富的动态内容。
4. 瘦客户端应用阶段：在这个阶段，在服务器端出现了独立于 Web 服务器的应用服务器。同时出现了 Web MVC 开发模式，各种 Web MVC 开发框架逐渐流行，并且占据了统治地位。基于这些框架开发的 Web 应用，通常都是瘦客户端应用，因为它们是在服务器端生成全部的动态内容。
5. RIA 应用阶段：在这个阶段，出现了多种 RIA（Rich Internet Application）技术，大幅改善了 Web 应用的用户体验。应用最为广泛的 RIA 技术是 DHTML+Ajax。Ajax 技术支持在不刷新页面的情况下动态更新页面中的局部内容。同时诞生了大量的 Web 前端 DHTML 开发库，例如 Prototype、Dojo、ExtJS、jQuery/jQuery UI 等等。
6. 移动 Web 应用阶段：在这个阶段，出现了大量面向移动设备的 Web 应用开发技术。除了 Android、iOS、Windows Phone 等操作系统平台原生的开发技术之外，基于 HTML5 的开发技术也变得非常流行。

三、前后端分离模式与传统模式

3.1、传统模式

    前端写好静态的html页面交给后端开发，后端把html改成模板，然后使用模板引擎去套模板，比如jsp，freemarker等，而后端人员在开发过程中如果发现页面有问题，要返回给前端修改，前端再交给后端，直至功能实现。
    我们可以发现这种模式耦合很严重，他存在的问题有：

1. 前端需要改bug调试时，需要在当前电脑安装一整套后端的开发工具，启动后端程序。
2. 还要求后端人员会html，js等前端语言。
3. 前端页面也会嵌入很多后端的代码。
4. 一旦后端换了一套语言，前端也需要重新开发。
5. 沟通成本，调试成本，前后端开发进度相互影响，从而大大降低开发效率。

3.2、前后端分离

    前后端分离并不只是开发模式，也是web应用的一种架构模式。在开发阶段，前后端人员约定好数据交互接口，即可并行开发与测试。
    前端开发完成可以独自进行mock测试，后端也可以使用postman等接口测试工具进行测试。最后可进行功能联调测试。

    我们可以发现这种模式有很大的优势：

1. 前后端责任清晰，后端专注于数据上，前端专注于视觉上。
2. 无需等待对方的开发工作结束，提高开发效率。
3. 可应对复杂多变的前端需求。
4. 增强代码可维护性。

四、RESTful风格

    REST是一种设计API的模式(风格)。最常用的数据格式是JSON。由于JSON能直接被JavaScript读取，所以，使用JSON格式的REST风格的API具有简单、易读、易用的特点。满足这些约束条件和原则的应用程序或设计就是 RESTful 应用。

4.1、传统的API设计

    客户端虽然有很多类型, 但是只要服务端统一提供API接口, 多个客户端基于相同的协议来调用该API接口即可获取数据，不同开发者对API接口的设计习惯不同 ，拿员工新增举例，可能会出现以下几种API接口设计，且发送的请求方式以及响应结果也比较可能随意 ：

1. http://localhost/employee/save
2. http://localhost/employee/add
3. http://localhost/employee/new
4. http://localhost/employee/xinzeng
5. http://localhost/employee/append
6. http://localhost/employee?cmd=add
       所以RESTful风格的API 就诞生了。

4.2、RESTful风格API

    RESTful风格API大约遵循三点

4.2.1、网络上的所有事物都被抽象为资源**

    每个资源都有一个唯一的资源定位符（URI）。每个URI代表一种资源（resource），所以URI中不能有动词，只能有名词，而且所用的名词往往与数据库的表名对应。一般来说，数据库中的表都是同种记录的"集合"（collection），所以URI中的名词也应该使用复数。

@RequestMapping("/employees")

4.2.2、资源状态转换

    就代表了客户端和服务器的一个互动过程。在这个过程中，势必涉及到资源和资源状态变化。互联网通信协议HTTP协议，是一个无状态协议。这意味着，所有资源的状态都保存在服务器端。因此，如果客户端想要操作服务器，须使用HTTP方法去促使服务器端资源发生状态改变。

4.2.3、使用统一接口

    REST要求，必须通过统一的接口来对资源执行各种操作。
    HTTP1.1协议为例：他有7个HTTP方法：GET/POST/PUT/DELETE/PATCH/HEAD/OPTIONS

1. GET（SELECT）：从服务器取出资源（一项或多项）。
2. POST（CREATE）：在服务器新建一个资源。
3. PUT（UPDATE）：在服务器更新资源（客户端提供改变后的完整资源）。PUT更新整个对象
4. PATCH（UPDATE）：在服务器更新资源（客户端提供改变的属性【补丁】）。 PATCH更新个别属性
5. DELETE（DELETE）：从服务器删除资源。
6. HEAD：获得一个资源的元数据，比如一个资源的hash值或者最后修改日期。
7. OPTIONS：获得客户端针对一个资源能够实施的操作；(获取该资源的api(能够对资源做什么操作的描述))

4.2.4、举例

1. GET /zoos：列出所有动物园。
2. PATCH /zoos/{id}：更新某个指定动物园的信息（提供该动物园的部分信息）。
3. GET /zoos/{id}/animals：列出某个指定动物园的所有动物 。

4.2.5、总结

    REST只是一种设计风格 , 而不是标准 , 只是提供了一组设计原则和约束条件。
    主要用于客户端和服务器交互, 让设计者和使用更方便 , 让API更简洁, 更有层次 , 更易于实现缓存等机制。

五、HTTP常见的响应状态码

1. 200 OK - [GET]：服务器成功返回用户请求的数据。
2. 201 CREATED - [POST/PUT/PATCH]：用户新建或修改数据成功。
3. 202 Accepted - [*]：表示一个请求已经进入后台排队（异步任务）
4. 204 NO CONTENT - [DELETE]：用户删除数据成功。
5. 400 INVALID REQUEST - [POST/PUT/PATCH]：用户发出的请求有错误，服务器没有进行新建或修改数据的操作，该操作是幂等的。
6. 401 Unauthorized - [*]：表示用户没有权限（令牌、用户名、密码错误）。
7. 403 Forbidden - [*] 表示用户得到授权（与401错误相对），但是访问是被禁止的。
8. 404 NOT FOUND - [*]：用户发出的请求针对的是不存在的记录，服务器没有进行操作，该操作是幂等的。
9. 406 Not Acceptable - [GET]：用户请求的格式不可得（比如用户请求JSON格式，但是只有XML格式）。
10. 410 Gone -[GET]：用户请求的资源被永久删除，且不会再得到的。
11. 422 Unprocesable entity - [POST/PUT/PATCH] 当创建一个对象时，发生一个验证错误。
12. 500 INTERNAL SERVER ERROR - [*]：服务器发生错误，用户将无法判断发出的请求是否成功。

六、常用注解

6.1、@RestController

    由@Controller +@ResponseBody组成，一般贴在类上，表示该类的所有方法都不返回视图，直接返回JSON。

6.2、@PathVariable

通过 @PathVariable 可以将 URL 中占位符参数绑定到控制器处理方法的入参中，URL 中的 {xxx} 占位符可以通过@PathVariable(“xxx“) 绑定到操作方法的入参中。