RESTful风格

RESTful风格

1、REST概念

REST(英文: Representational State Transfer,简称REST, 意思:表述性状态转换,描述了一个架构样式的网络系统,比如web应用)。

它是一种软件架构风格、 设计风格,而不是标准,只是提供了一组设计原则和约柬条件,它主要用于客户端和服务端交互类的软件。基于这个风格设计的软件可以更简介,更有层次,更易于实现缓存等机制。

它本身并没有什么使用性,其核心价值在于如何设计出符合REST风格的网络接口。

2、RESTful概念

REST指的是一组架构约束条件和原则。 满足这些约束条件和原则的应用程序或设计就是RESTful,

  • RESTful的特性:
    • 资源(Resources):互联网所有的事物都可以被抽象为资源。它可以是一段文本、一张图片、一首歌曲、一种服务,总之就是一个具体的存在。可以用一个URI (統一资源定位符)指向它,每种资源对应一个特性的URI。 要获取这个资源,访问它的URI就可以,因此URI即为每一个资源的独一 无二 的识别符。
    • 表现层(Representation):把资源具体星现出来的形式,叫做它的表现层(Representation)。 比如,文本可以用txt格式表现,也可以用HTML格式、XML格式、JSON格式表现,甚至可以采用二进制格式。
    • 状态转换(State Transfer):每发出一个请求,就代表了客户端和服务器的一次交互过程。HTTP协议,是一个无状态协议,即所有的状态都保存在服务器端。因此,如果客户端想要操作服务器,必须通过某种手段,让服务器端发生"状态转换"(State Transfer)。而这种转换是建立在表现层之上的,所以就是"表现层状态转换"。

具体来说就是HTTP协议里面,四个表示操作方式的动词: GETPOSTPUTDELETE他们分别对应四种基本操作: GET用来获取资源,POST用来新建资源,PUT用来更新资源,DELETE用来删除资源。

原来的操作资源的方式:

localhost:8080/getExpress.do?id=1
localhost:8080/saveExpress.do?
localhost:8080/updateExpress.do?
localhost:8080/deleteExpress.do?id=1

原来用的方式当然没有问题,但是如果有更简洁的方式就更好了,此时就是RESTful风格。

使用RESTful操作资源:

GET /expresses#查询所有的快递信息列表
GET /express/1006#查询一个快递信息
POST /express#新建一个快递信息
PUT/express/1006#更新一个快递信息(全部更新)
PATCH /express/1006#更新一个快递信息(部分更新)
DELETE /express/1006#删除一个快递信息

3、API设计/URL设计

动词+宾语

RESTful的核心思想就是:客户端的用户发出的数据操作指令都是"动词+宾语"的结构。比如,GET/expresses这个命令,GET是动词,/expresses是宾语。

于是,在编写controller的方法的时候,就可以使用springmvc提供的@RequestMapping注解的method属性来指定它可以 用于处理什么类型的请求。

动词通常就是五种HTTP方法,对应CRUD 操作。
GET:读取(Read)
POST:新建(Create)
PUT:更新(Update) 
PATCH:更新(Update),通常是部分更新
DELETE:删除(Delete)

PS: 1、根据HTTP规范,动词一律大写。
	2、一些代理只支持POST和GET方法,为了使用这些有限方法支持RESTful API, 需要一种办法覆盖http原来的方法。 使用订制的HTTP头X-HTTP-Method-Override来覆盖POST方法。

宾语必须是名词

宾语就是API的URL,是HTTP动词作用的对象。它应该是名词,不能是动词。

比如,/expresses 这个URL就是正确的。

以下这些URL都是不推荐的,因为带上了动词,不是推荐写法。
/getAllExpresses
/getExpress
/createExpress
/deleteAllExpress

ps:不要混淆名词单数和复数,为了保持简单,只对所有资源使用复数。

避免多级URL

如果资源中有多级分类,也不建议写出多级的URL。例如要获取球队中某个队员,有人可能这么写:

​ GET /team/1001/player/1005

这种写法的语义不够明确,所以推荐使用查询字符串做后缀,改写为

​ GET /team/1001? player=1005.

再例如查询所有的还未职出的快递,你该如何编写呢?
GET /expresses/statu 不推荐
GET /expresses?statumfalse 推荐

4、HTTP状态码

客户端的用户发起的每一次请求, 服务器都必须给出响应。响应包括HTTP状态码数据两部分。

HTTP状态码就是一个三位数,分成五个类别。这五大类总包含了100多种状态码(不需要全都记住,不用紧张哈,覆盖了绝大部分可能遇到的情况。每一种状态码都有标准的(或者约定的)解释,客户端只需查看状态码,就可以判断出发生了什么情况,所以服务器应该返回尽可能精确的状态码。

五类状态码分别如下:
	1xx:相关信息
	2xx:操作成功
	3xx:重定向
	4xx:客户端错误
	5xx:服务器错误
	
	PS:API 不需要1xx状态码,所以这里可以忽略这个类别

状态码2xx

200状态码表示操作成功,但是不同的方法可以返回更精确的状态码

GRT:200 OK 表示一切正常
POST:201 Created 表示新的资源已经成功创建
PUT:200 OK
PATCH:200 OK
DELETE:204 No Content 表示资源已经成功删除

状态码3xx

API用不到301状态码(永久重定向)和302状态码(暂时重定向,307 也是这个含义),因为它们可以由应用级别返回,浏览器会直接跳转,API级别可以不考虑这两种情况。

API用到的3xx状态码,主要是303 See other,表示参考另一个URL。它与302和307的含义一样,也是暂时重定向",区别在于302和307用于GET请求,

而303用于POST、PUT 和DELETE请求。收到303以后,浏览器不会自动跳转,而会让用户自己决定下一步怎么办。

我们只需要关注一下304状态码就可以了
304 : Not Modified 客户端使用缓存数据

状态码4xx

4xx状态码表示客户端错误。

400 Bad Request:服务器不理解客户端的请求,未做任何处理。
401 Unauthorized: 用户未提供身份验证凭据,或者没有通过身份验证。
403 Forbidden:用户通过了身份验证,但是不具有访问资源所需的权限。
404 Not Found: 所请求的资源不存在,或不可用。
405 Method Not Allowed: 用户已经通过身份验证,但是所用的HTtp 方法不在他的权限之内。
410 Gone:所请求的资源已从这个地址转移,不再可用。
415 Unsupported Media Type: 客户端要求的返回格式不支持。比如,API只能返回JSON 格式,但是客户端要求返回XL格式。
422 Unprocessable Entity : 客户端上传的附件无法处理,导致请求失败。
429 Too Many Requests:客户端的请求次数超过限额。

状态码5xx

5xx状态码表示服务端错误。一般来说,API不会向用户透露服务器的详细信息,所以只要两个状态码就够了。

500 Internal Server Error: 客户端请求有效,服务器处理时发生了意外。
503 Service Unavailable:服务器无法处理请求,一般用于网站护状态。

5、服务器响应

服务器返回的信息一般不推荐纯文本,而是建议大家选择JSON对象,因为这样才能返回标准的结构化数据。

所以,服务器回应的HTTP头的Content-Type属性要设为application/json.客户端请求时,也要明确告诉服务器,可以接受JSON格式,即请求的HTTP头的ACCEPT属性也要设成applicat ion/json.

当发生错误的时候,除了返回状态码之外,也要返回错误信息。所以我们可以自己封装要返回的信息。

6、案例

RESTful风格的查询

前端页面

html 复制代码
<html>
<head>
    <title>RESTful</title>
    <script src="/js/jquery2.1.4.js"></script>
</head>
<body>
    <form id="myForm" action="" method="post">
        球队ID:<input type="text" name="teamID" id="teamID"><br/>
        球队名称:<input type="text" name="tName" id="teamName"><br/>
        球队位置:<input type="text" name="tLocation" id="teamLocation"><br/>
        <button type="button" id="btnGetAll">查询所有GET</button>
        <button type="button" id="btnGetOne">查询单个GET</button>
        <button type="button" id="btnPost">添加POST</button>
        <button type="button" id="btnPut">更新PUT</button>
        <button type="button" id="btnDel">删除DELETE</button>
    </form>
<p id="showResult"></p>
</body>
</html>
<script>
    //页面加载完毕之后给按钮绑定事件
    $(function (){
        //1、给查询所有GET按钮绑定事件
        $("#btnGetAll").click(function (){
            $.ajax({
                type: "GET",
                url: "/restful/teams",
                data: "",
                success: function(list){
                    alert( "Data Saved: " + list );
                    var str = "";
                    for(var i=0;i<list.length;i++){
                        var obj=list[i];
                        str+="球队ID:"+obj.teamID+",球队名称:"+obj.tName+",球队位置:"+obj.tLocation+"<br/>";
                    }
                    $("#showResult").html(str);
                }
            });
        });

        //2、给查询单个GET绑定事件
        $("#btnGetOne").click(function (){
            $.ajax({
                type: "GET",
                url: "/restful/team/"+$("#teamID").val(),//RESTful风格的API定义(传参格式)
                data: "",
                success: function(obj){
                    if(obj == ""){
                        $("#showResult").html("此数据不存在");
                        return;
                    }
                    alert( "Data Saved: " + obj );
                    var str ="球队ID:"+obj.teamID+",球队名称:"+obj.tName+",球队位置:"+obj.tLocation+"<br/>";
                    $("#showResult").html(str);
                }
            });
        });

        //3、给添加POST绑定事件
        $("#btnPost").click(function (){
            alert($("#myForm").serialize());//输出测试
            $.ajax({
                type: "POST",
                url: "/restful/team/",
                data: $("#myForm").serialize(),//表单的所有数据以?&形式追加在URL后:team?teamID=1001&teamName=队伍&teamLocation=队伍地址
                success: function(msg){
                    if(msg == "201"){
                        $("#showResult").html("添加成功");
                        return;
                    }
                }
            });
        });

        //4、给更新PUt绑定事件
        $("#btnPut").click(function (){
            $.ajax({
                type: "POST",
                url: "/restful/updateTeam/",
                data: $("#myForm").serialize()+"&_method=PUT",//表单的所有数据以?&形式追加在URL后:team?teamID=1001&teamName=队伍&teamLocation=队伍地址
                success: function(msg){
                    if(msg == "200"){
                        $("#showResult").html("更新成功");
                        return;
                    }else if(msg == ""){
                        $("#showResult").html("没找到对应的数据");
                    }
                }
            });
        });

        //5、给删除DELETE绑定事件
        $("#btnDel").click(function (){
            $.ajax({
                type: "POST",
                url: "/restful/deleteTeam/",
                data: $("#myForm").serialize()+"&_method=DELETE",//表单的所有数据以?&形式追加在URL后:team?teamID=1001&teamName=队伍&teamLocation=队伍地址
                success: function(msg){
                    if(msg == "204"){
                        $("#showResult").html("删除成功");
                        return;
                    }else if(msg == ""){
                        $("#showResult").html("没找到对应的数据");
                    }
                }
            });
        });
    });
</script>
java 复制代码
/**
 * RESTful风格控制器Controller
 */
@Controller
@RequestMapping("/restful")
public class RestfulController {
    private static List<Team> teamList;//代替数据库存储数据
    static {    //静态代码块,类加载时存入数据用于查询测试
        teamList = new ArrayList<>(3);
        for(int i=1;i<=3;i++){
            Team team = new Team();
            team.setTeamID(1000+i);
            team.settName("队名"+i);
            team.settLocation("队伍地址"+i);
            teamList.add(team);
        }
    }

    /**
     * 查询所有的球队
     * @return
     */
    @RequestMapping(value = "/teams",method = RequestMethod.GET)
    @ResponseBody
    public List<Team> getAll(){
        System.out.println("查询所有数据------GETAll发起请求");
        return teamList;
    }
    /**
     * 查询单个球队
     * @return
     */
    @RequestMapping(value = "/team/{teamID}",method = RequestMethod.GET)
    @ResponseBody
    public Team getOne(@PathVariable("teamID") String teamID){
        System.out.println("查询单个数据------GETOne发起请求");
        for(Team team:teamList){
            if(Integer.valueOf(teamID) == team.getTeamID()){
                return team;
            }
        }
        return null;
    }
    /**
     * 添加球队信息
     * @return
     */
    @RequestMapping(value = "/team",method = RequestMethod.POST)
    @ResponseBody
    public String addPost(Team team){
        System.out.println(team);
        System.out.println("添加数据------addPost发起请求");
        teamList.add(team);
        return "201";
    }
    @RequestMapping(value = "/updateTeam",method = RequestMethod.PUT)
    @ResponseBody
    public String updatePut(Team team){
        System.out.println("更新信息-----updatePUT发起请求");
        for(Team t:teamList){
            if(t.getTeamID()==team.getTeamID()){
                t.settName(team.gettName());
                t.settLocation(team.gettLocation());
                return "200";
            }
        }
        return null;
    }
    @RequestMapping(value = "/deleteTeam",method = RequestMethod.DELETE)
    @ResponseBody
    public String deleteDelete(Team team){
        System.out.println(team);
        System.out.println("删除信息-----DELETE发起请求");
        for(Team t:teamList){
            if(t.getTeamID()==team.getTeamID()){
                teamList.remove(t);
                return "204";
            }
        }
        return null;
    }
    @RequestMapping("/hello")
    public String hello(){
        return "restful";
    }
}

RESTful风格的更新和删除遇到的问题

原因

实际上,ajax中如果不用data传递参数,只使用url传递参数,是没有问题的。
在Ajax中,采用RESTful风格的PUT和DELETE请求传递参数无效,传递到后台的参数值为null的问题

原因:
	Tomcat封装请求参数的过程:
		1.将请求体中的数据,封装成一个map
		2.request.getParameter("id")会从这个map中取值
		3.SpringMvc封装POJO对象的时候,会把POJO中每个属性的值进行request.getParamter();
	AJAX发送PUT或者DELETE请求时,请求体中的数据通过request.getParamter()拿不到。
	Tomcat一检测到是PUT或者DELETE就不会封装请求体中的数据为map, 只有POST形式的请求才封装请求为map.

解决方法

前端页面中发送ajax请求的时候在url中加"&_method=PUT"或者"&_method=DELETE"

如图:

然后web.xml中配置过滤器

配置的时候多个过滤器需要注意顺序

xml 复制代码
<!--使用Rest风格的URI将页面普通的post请求转为指定的delete或者put请求
	原理:在Aajx中发送post请求后,带method参数,将其修改为PUT,或者DELETE请求-->
	<filter>
        <filter-name>httpMethodFilter</filter-name>
        <filter-class>
            org.springframework.web.filter.HiddenHttpMethodFilter
        </filter-class>
    </filter>
    <filter-mapping>
        <filter-name>httpMethodFilter </filter-name>
        <url-pattern>/*</url-pattern>
    </filter-mapping>

自行封装响应结果

实际开发时,通常自行约定封装响应结果

如:自定义一个类,专门用于封装响应结果数据,controller中的返回类型永远是这个类的实体,前端要获取数据也只需要从这个实体内部取数据就可以了。

如下:

java 复制代码
public class ResultVO<T> {
    private int status;//状态码
    private String msg;//响应信息
    private List<T> list;//返回的数据可能是集合
    private T obj;//返回的结果也有可能是对象。

    public ResultVO(int status, String msg, T obj) {
        this.status = status;
        this.msg = msg;
        this.obj = obj;
    }

    public ResultVO(int status, String msg, List<T> list) {
        this.status = status;
        this.msg = msg;
        this.list = list;
    }

    public ResultVO(int status, String msg) {
        this.status = status;
        this.msg = msg;
    }

    public ResultVO() {//默认构造方法,根据实际情况自行决定
        status = 200;
        msg = "";
        list = null;
        obj = null;
    }
}

如上,之前代码中的所有的返回值都可以封装为ResultVO类型,前端根据具体情况从返回的对象中获取数据即可。

相关推荐
颜淡慕潇1 小时前
【K8S问题系列 |1 】Kubernetes 中 NodePort 类型的 Service 无法访问【已解决】
后端·云原生·容器·kubernetes·问题解决
尘浮生2 小时前
Java项目实战II基于Spring Boot的光影视频平台(开发文档+数据库+源码)
java·开发语言·数据库·spring boot·后端·maven·intellij-idea
尚学教辅学习资料2 小时前
基于SpringBoot的医药管理系统+LW示例参考
java·spring boot·后端·java毕业设计·医药管理
monkey_meng3 小时前
【Rust中的迭代器】
开发语言·后端·rust
余衫马3 小时前
Rust-Trait 特征编程
开发语言·后端·rust
monkey_meng3 小时前
【Rust中多线程同步机制】
开发语言·redis·后端·rust
paopaokaka_luck7 小时前
【360】基于springboot的志愿服务管理系统
java·spring boot·后端·spring·毕业设计
码农小旋风9 小时前
详解K8S--声明式API
后端
Peter_chq9 小时前
【操作系统】基于环形队列的生产消费模型
linux·c语言·开发语言·c++·后端
Yaml49 小时前
Spring Boot 与 Vue 共筑二手书籍交易卓越平台
java·spring boot·后端·mysql·spring·vue·二手书籍