springboot构建RESTful 风格应用

Spring Boot 构建 RESTful 风格应用

1.Web开发的两种模式：

前后端不分离：

以前没有移动互联网时，我们做的大部分应用都是前后端不分的，比如jsp，或者thymeleaf等后端分离模板，在这种架构的应用中，数据基本上都是在后端渲染好返回给前端展示的，也就是后端需要控制前端的展示，前端与后端的耦合度很高。
这种应用模式比较适合纯网页应用，但是当后端对接App时，App可能并不需要后端返回一个HTML网页，而仅仅是数据本身，所以后端原本返回网页的接口不再适用于前端App应用，为了对接App后端还需再开发一套接口。这样前后端不分离就有局限性了。
1
2

前后端分离：

在前后端分离的应用模式中，后端仅返回前端所需的数据，不再渲染HTML页面，不再控制前端的效果。至于前端用户看到什么效果，从后端请求的数据如何加载到前端中，都由前端自己决定，网页有网页的处理方式，App有App的处理方式，但无论哪种前端，所需的数据基本相同，后端仅需开发一套逻辑对外提供数据即可。
在前后端分离的应用模式中 ，前端与后端的耦合度相对较低。
我们通常将后端开发的每个视图都称为一个接口，或者API，前端通过访问接口来对数据进行增删改查。
1
2
3

前面我们讲解了前后端不分离不分离模式，现在来讲解一下前后端分离模式怎么实现.

2.什么是API？

API：全称是 Application Programming Interface，应用程序编程接口。API是一些预先定义的函数，目的是提供应用程序与开发人员基于某软件或硬件得以访问一组例程的能力，而又无需访问源码，或理解内部工作机制的细节。简单的说API 是一套协议，规定了我们与外界的沟通方式：如何发送请求和接收响应。
比如我们平时在QQ上可以看到天气信息，而这些天气信息不是腾讯公司用卫星监测到的，而是去调用气象局的天气信息的。但腾讯公司不需要也不能访问气象局的数据库和源码，而是通过调用气象局提供的一个公共函数来实现，我们只需要知道这个函数需要传递什么参数，以及返回什么样的数据就行，函数的内部结构我们并不需要知道。这个函数就是API。
1
2

3.什么是RESTful

为了在团队内部形成共识、防止个人习惯差异引起的混乱，我们需要找到一种大家都觉得很好的接口实现规范，
而且这种规范能够让后端写的接口，用途一目了然，减少双方之间的合作成本。所以出现了接口服务架构，目前市面上大部分公司开发人员使用的接口服务架构主要有：restful、rpc。

REST：那Rest是什么呢，它是一种架构风格，就像气象局建立API时要遵守的一种规则，可以是Rest也可以是其它规则。这种规则是为web应用服务的，也就是用URL定位资源，用HTTP动词（GET,POST,DELETE,PUT）描述操作，用HTTP Status Code返回结果状态的这种client和server的交互方式。实现看Url就知道要什么，看http 方法就知道干什么，看http status code就知道结果如何。

RESTFul：RESTful是一种定义Web API接口的设计风格，尤其适用于前后端分离的应用模式中。RESTFul就是为了实现REST这种交互方式而制定的一套约束条件和规则，符合这些约束条件和原则的应用程序或设计就是RESTful。也就是REST本身不实用，实用的是如何设计 RESTful API（REST风格的网络接口）。这种风格的理念认为后端开发任务就是提供数据的，对外提供的是数据资源的访问接口，所以在定义接口时，客户端访问的URL路径就表示这种要操作的数据资源。

4.RESTful设计规范

那么RESTFul有哪些设计规范呢？

1、协议

API与用户的通信协议，使用HTTPs协议或者HTTP协议，统一确定用一种。
1

2、域名

应该尽量将API部署在专用域名之下，如https://xxx.xxx.com；

如果多个项目创建API，把项目名称带上 如[https://项目名.XXX.com
1
2
3

3、版本

应该将API的版本号放入URL。

http://www.example.com/app/1.0/foo

http://www.example.com/app/1.1/foo

http://www.example.com/app/2.0/foo


另一种做法是，将版本号放在HTTP头信息中，但不如放入URL方便和直观。Github就采用了这种做法。
1
2
3
4
5
6
7
8
9
10

因为不同的版本，可以理解成同一种资源的不同表现形式，所以应该采用同一个URL。版本号可以在HTTP请求头信息的Accept字段中进行区分

Accept: vnd.example-com.foo+json; version=1.0

Accept: vnd.example-com.foo+json; version=1.1
1
2
3
4

4、路径

路径又称"终点"（endpoint），表示API的具体网址，每个网址代表一种资源（resource）

(1) 资源作为网址，只能有名词，不能有动词，而且所用的名词往往与数据库的表名对应。

举例来说，以下是不好的例子:
/selectGoods
/listOrders
/retreiveClientByOrder?orderId=1

对于一个简洁结构，你应该始终用名词。 此外，利用的HTTP方法可以分离网址中的资源名称的操作。

GET  /goods ：将返回所有商品清单
POST /goods ：将商品新建到集合
GET  /goods/4 ：将获取商品 4
PATCH（或）PUT /goods/4 ：将更新商品 4


(2) API中的名词应该使用复数。无论子资源或者所有资源。

举例来说，获取产品的API可以这样定义

获取单个产品：http://127.0.0.1:8080/AppName/goods/1
获取所有产品: http://127.0.0.1:8080/AppName/goods
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

5、HTTP动词

对于资源的具体操作类型，由HTTP动词表示。

常用的HTTP动词有下面四个（括号里是对应的SQL命令）。

- GET（SELECT）：从服务器取出资源（一项或多项）。
- POST（CREATE）：在服务器新建一个资源。
- PUT（UPDATE）：在服务器更新资源（客户端提供改变后的完整资源）。
- DELETE（DELETE）：从服务器删除资源。

还有三个不常用的HTTP动词。

- PATCH（UPDATE）：在服务器更新(更新)资源（客户端提供改变的属性）。
- HEAD：获取资源的元数据。
- OPTIONS：获取信息，关于资源的哪些属性是客户端可以改变的。

下面是一些例子。

GET /goods：列出所有商品清单
POST /goods：新建一个商品（上传文件）
GET /goods/ID：获取某个指定商品的信息
PUT /goods/ID：更新某个指定商品的信息（提供该商品的全部信息）
PATCH /goods/ID：更新某个指定商品的信息（提供该商品的部分信息）
DELETE /goods/ID：删除某个商品
GET /goods/ID/attributes：列出某个指定商品的所有属性信息
DELETE /goods/ID/attributes/ID：删除某个指定商品的指定属性
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

6、过滤信息

如果记录数量很多，服务器不可能都将它们返回给用户，API会提供参数，过滤返回结果，用于补充规范一些通用字段，常见的参数有：
1. ?limit=20：指定返回记录的数量为20；
2. ?offset=8：指定返回记录的开始位置为8；
3. ?page=1&per_page=50：指定第1页，以及每页的记录数为50；
4. ?sortby=name&order=asc：指定返回结果按照name属性进行升序排序；
5. ?attr_id=2：指定筛选条件。
1
2
3
4
5
6

7、状态码

服务器会向用户返回状态码和提示信息，以下是常用的一些状态码，可以根据实际业务添加对应的状态码，需和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 - [*]࿱
1
2
3
4
5
6