Restful风格编程实现

发布时间 2023-04-02 14:48:20作者: Linqylin

1、RESTful 风格应用

1.1 前后端不分离
  在Web 1.0时代,网页是在服务器端使用动态脚本语言和模板引擎渲染出来,后端需要控制前端的展示,所以传统的 WEB 应用不分前后端,如 JSP 和 Themleaf 技术,因此前端和后端的耦合度很高。
 
1.2 前后端分离
  随着互联网技术的发展和移动应用的广泛应用,Web 项目的体量迅速增大,手机端、智能设备等应用需求剧增、公司的业务越来越复杂,前端的样式更新需求越来越多、越来越快,这些都要求前端开发必须与后端开发分离,实施工程化开发模式。因此,大前端时代到来了。
  Ajax技术的发展,使得前后端分离成为可能。前端可以不再依赖后台环境生存,所有服务器端数据都可以通过异步交互获取。只要能从后台取得一个规范定义的RESTful风格接口,前后两端就可以并行完成项目开发任务。
  在前后端分离的应用模式中,后端仅返回前端所需的数据,不再渲染HTML页面,不再控制前端的效果。至于前端用户看到什么效果,从后端请求的数据如何加载到前端中,都由前端自己决定。网页有网页的处理方式,APP有APP的处理方式,但无论哪种前端,所需的数据基本相同,后端仅需开发一套逻辑对外提供数据即可。
 
1.3 RESTful 风格
  前后端分离前,后端服务器既要转发页面、重定向,又要返回各种数据类型,因此URL会被定义成动词、名词和动宾短语,非常混乱。
  前后端分离后,前端页面由前端服务器统一维护,后端服务器只需要对外提供数据,即提供给前端网页Ajax访问的接口,并返回JSON。此时,后端程序可以使用 RESTful 风格来定义 URL,一般会以功能模块的名词作为 URL,以HTTP协议的请求方法 GET,POST,PUT,DELETE 等来表示行为。
  这样,可以规范接口的定义,防止个人习惯差异引起的混乱,对项目中庞大的URL进行分类有序管理。同时,对访问者来说,根据规范实现的接口的名字和用途一目了然,简明扼要,清晰易懂。
  REST(Representational State Transfer,(资源的)表象层状态转移):描述了一组架构约束条件和原则,代表了分布式服务访问的架构风格。REST的含义可以从以下三点来理解:
(1) 每一个URL代表一种资源
  所谓“资源”,就是网络上的一个实体,或者说是网络上的一个具体信息。它可以是一段文本、一张图片、一首歌曲、一种服务,总之就是一个具体的实在。我们可以用一个URI(统一资源定位符)指向它,每种资源对应一个特定的URI。要获取这个资源,访问它的URI就可以,因此URI就成了每一个资源的地址或独一无二的识别符。
(2)在客户端和服务器之间,传递这种资源的某种表现层
  “资源”是一种信息实体,它可以有多种外在表现形式。”资源”具体呈现出来的形式,叫做它的"表现层"(Representation)。比如,文本可以用txt格式表现,也可以用HTML格式、XML格式、JSON格式表现,甚至可以采用二进制格式;图片可以用JPG格式表现,也可以用PNG格式表现。
(3)客户端通过HTTP协议提供请求方法,并对服务器端的资源进行操作,以实现“表现层状态转换”
  访问一个网站,就代表了客户端和服务器的一个互动过程。在这个过程中,势必涉及到数据和状态的变化。互联网通信协议HTTP协议,是一个无状态协议。这意味着,所有的状态都保存在服务器端。因此,如果客户端想要操作服务器,必须通过某种手段,让服务器端发生"状态转化"(State Transfer)。而这种转化是建立在表现层之上的,所以就是"表现层状态转化"。
  客户端用到的手段,只能是 HTTP 协议。具体来说,主要是HTTP协议的四个表示操作方式的动词:GET、POST、PUT、DELETE。它们分别对应四种基本操作:GET用来获取资源,POST用来新建资源(也可以用于更新资源),PUT用来更新资源,DELETE用来删除资源。
  满足这些约束条件和原则的应用程序或设计就是 RESTful。在行业中,一般用RESTful表示在项目中实现了REST。
  统一的接口是RESTful风格的核心内容。RESTful定义了Web API接口的设计风格,非常适用于前后端分离的应用模式中。RESTful接口约束包含的内容有资源识别、请求动作和响应信息,即通过URL表明要操作的资源,通过请求方法表明要执行的操作,通过返回的状态码表明这次请求的结果。另外,RESTful规定服务端返回的数据格式是XML或JSON,或直接返回状态码。
  这样,服务端只需要关注实现接口就可以了,而且随着接口可读性增强,客户端调用也更加方便。
 
1.4 RESTful 设计主要规范
(1)协议
API与用户的通信协议,使用HTTPs协议或者HTTP协议,统一确定用一种。
(2)域名
应该尽量将API部署在专用域名之下,如 https://xxx.xxx.com;
如果多个项目创建API,把项目名称带上 如 https://项目名.XXX.com
(3)版本
应该将API的版本号放入URL,如下:
http://www.example.com/app/1.0/foo
http://www.example.com/app/1.1/foo
(4)路径
路径又称"终点"(endpoint),表示API的具体网址,每个网址代表一种资源
(resource),具体要求如下:
 资源作为网址,只能有名词,不能有动词,而且所用的名词往往与数据库的表
名对应。
如:以下是不符合 RESTful 规范的URL
/selectGoods
/listOrders
/retreiveClientByOrder?orderId=1
 
以下是符合RESTful规范的URL:
GET请求: /goods -----表示将返回所有商品清单
POST请求: /goods -----表示将商品新增到表中
GET请求: /goods/4 -----将获取id=4的商品信息
PATCH(或)PUT请求: /goods/4 ----表示将更新 id=4的商品
 API 中的名词应该使用复数
如获取产品的API可以这样定义:
获取单个产品:http://127.0.0.1:8080/AppName/goods/1
获取所有产品: http://127.0.0.1:8080/AppName/goods
 
(5)HTTP动词
对于资源的具体操作类型,用HTTP动词表示。常用的HTTP动词有下面四个(括号里
是对应的SQL命令)。
- GET(SELECT):从服务器取出资源(一项或多项)。
- POST(INSERT):在服务器新增一个资源。
- PUT(UPDATE):在服务器更新资源(客户端提供改变后的完整资源)。
- DELETE(DELETE):从服务器删除资源。
具体应用如下:
GET: /goods:列出所有商品清单
POST: /goods:新建一个商品(上传文件)
GET: /goods/Id:获取某个指定商品的信息
PUT: /goods/Id:更新某个指定商品的信息(提供该商品的全部信息)
DELETE: /goods/Id:删除某个商品
GET: /goods/Id/attributes:列出某个指定商品的所有属性信息
DELETE: /goods/Id/attributes:删除某个指定商品的指定属性
(6)过滤信息
如果记录数量很多,服务器不可能都将它们返回给用户,API会提供参数,过滤返
回结果,用于补充规范一些通用字段,常见的参数有:
?limit=20:指定返回记录的数量为20
?offset=8:指定返回记录的开始位置为8
?page=1&per_page=50:指定第1页,以及每页的记录数为50
?sortby=name&order=asc:指定返回结果按照name属性进行升序排序
?attr_id=2:指定筛选条件
(7)状态码
服务器会向用户返回状态码和提示信息,以下是常用的一些状态码,也可以根据实际业务添加对应的状态码:
200 OK - [GET]:服务器成功返回用户请求的数据;
201 CREATED - [POST/PUT/PATCH]:用户新建或修改数据成功;
202 Accepted - [*]:表示一个请求已经进入后台排队(异步任务);
204 NO CONTENT - [DELETE]:用户删除数据成功;
400 INVALID REQUEST - [POST/PUT/PATCH]:用户发出的请求有错误,服务器没有进行新建或修改数据的操作;
401 Unauthorized - [*]:表示用户没有权限(令牌、用户名、密码错误);
403 Forbidden - [*] 表示用户得到授权(与401错误相对),但是访问是被禁止的;
404 NOT FOUND - [*]:用户发出的请求针对的是不存在的记录,服务器没有进行操作;
406 Not Acceptable - [GET]:用户请求的格式不可得;
410 Gone -[GET]:用户请求的资源被永久删除,且不会再得到的;
422 Unprocesable entity - [POST/PUT/PATCH] 当创建一个对象时,发生一个验证错误;
500 INTERNAL SERVER ERROR - [*]:服务器发生错误,用户将无法判断发出的请求是否成功。
(8)返回结果
针对不同操作,服务器向用户返回的结果应该符合以下规范:
GET /collection:返回资源对象的列表
GET /collection/Id:返回单个资源对象
POST /collection:返回新生成的资源对象
PUT /collection/ID:返回完整的资源对象
DELETE /collection/Id:返回一个空文档
常见的返回值格式如下:
code:200,
msg:查询成功
data:[{},{},{}]
 
1.5 基于 RESTful 的 SpringBoot 项目应用
(1)常用注解:
@RestController:相当于@Controller+@ResponseBody两个注解的功能,即表示该类是一个控制器类,同时返回值是JSON格式的;
@GetMapping("/对外访问名" ):表示只接收 get请求;
@PostMapping("/对外访问名" ):只接收post请求,插入新数据
@PutMapping("/对外访问名" ):只接收put请求,更改数据
@DeleteMapping("/对外访问名"/{id}"):只接收delete请求,删除数据
@PathVariable:表示从URL路径上获取指定的参数