RESTful风格以及统一响应结果

Posted 2023-04-06 yfs1024

常用的两个开发规范: RESTful风格 和 统一响应结果

1, REST风格

在前后端分离的开发模式中，前后端开发人员都需要根据提前定义好的接口文档，来进行前后端功能的开发。后端开发人员必须严格遵守提供的接口文档进行后端功能开发（保障开发的功能可以和前端对接）

而在前后端进行交互的时候，我们需要基于当前主流的REST风格的API接口进行交互。

什么是REST风格呢?

• REST（Representational State Transfer），表述性状态转换，它是一种软件架构风格。

传统URL风格如下：

http://localhost:8080/user/getById?id=1     GET：查询id为1的用户
http://localhost:8080/user/saveUser         POST：新增用户
http://localhost:8080/user/updateUser       POST：修改用户
http://localhost:8080/user/deleteUser?id=1  GET：删除id为1的用户

我们看到，原始的传统URL呢，定义比较复杂，而且将资源的访问行为对外暴露出来了。

基于REST风格URL如下：

http://localhost:8080/users/1  GET：查询id为1的用户
http://localhost:8080/users    POST：新增用户
http://localhost:8080/users    PUT：修改用户
http://localhost:8080/users/1  DELETE：删除id为1的用户

其中总结起来，就一句话：通过URL定位要操作的资源，通过HTTP动词(请求方式)来描述具体的操作。

在REST风格的URL中，通过四种请求方式，来操作数据的增删改查。 可以理解为这几种请求只接受对应的请求方式

• GET ： 查询
• POST ：新增
• PUT ：修改
• DELETE ：删除

我们看到如果是基于REST风格，定义URL，URL将会更加简洁、更加规范、更加优雅。

注意事项：

• REST是风格，是约定方式，约定不是规定，可以打破
• 描述模块的功能通常使用复数，也就是加s的格式来描述，表示此类资源，而非单个资源。如：users、emps、books…

2, 统一响应结果

对于之前我们响应的结果可以是String,可以是无返回值,可以是ModelAndview可以是自定义对象.

这种方式虽然可以通过不同的场景返回不同的类型,但是对于前端开发来说不是很友好, 更需要依赖接口文档来判断返回值类型. 也因为有这样的弊端,后来就统一了返回结果,都为自定的对象Result返回,这样对于前端来说十分的方便.

返回实体类对象如下:

import lombok.AllArgsConstructor;
import lombok.Data;
import lombok.NoArgsConstructor;

@Data
@NoArgsConstructor
@AllArgsConstructor
public class Result 
    private Integer code;//响应码，1 代表成功; 0 代表失败
    private String msg;  //响应信息 描述字符串
    private Object data; //返回的数据

    //增删改 成功响应
    public static Result success()
        return new Result(1,"success",null);
    
    //查询 成功响应
    public static Result success(Object data)
        return new Result(1,"success",data);
    
    //失败响应
    public static Result error(String msg)
        return new Result(0,msg,null);
    

使用上面的两个规范我们在开发的时候就可以这样来处理web层, 如下:

修改

    /**
     * 用于修改部门数据
     *
     * @return 
     */
    @PutMapping(("/depts"))
    public Result updateDeptById(@RequestBody Dept dept) 
        Integer integer = deptService.updateDeptById(dept);
        if (integer > 0) 
            return Result.success();
        
        return Result.error("更新失败");
    

查询:

    /**
     * 查询所有的部门信息
     *
     * @return
     */
    @GetMapping("/depts")
    public Result queryAllDept() 
        return Result.success(deptService.selectAllDept());
    

删除:

    @DeleteMapping("/depts/id")
    public Result deleteDeptById(@PathVariable Integer id) 
        Integer integer = deptService.deleteDeptById(id);
        if (integer > 0) 
            return Result.success();
        
        return Result.error("删除失败");
    

添加:

    @PostMapping("/depts")
    public Result insertDpet(@RequestBody Dept dept) 
        Integer integer = deptService.insertDept(dept);
        if (integer > 0) 
            return Result.success();
        
        return Result.error("添加失败");
    

当请求路径中有同样的参数的时候可以提到类上使用原始的@RequestMapping注解

@RestController
@Slf4j
@RequestMapping("/depts")
public class DeptController  
	...

简化后的方法请求路径注解如下:

添加->    @GetMapping
删除->    @DeleteMapping("/id")
新增->    @PostMapping
修改->    @PutMapping

---

附加一些知识，当统一了响应后，如果程序中出现了异常那么该怎么解决。因为一般不处理那么返回的就是系统中默认的信息如下：

	"timestamp":"2023-04-02T14:52:24.536+00:00",
	"status":500,
	"error":"Internal Server Error",
	"path":"/depts"

这显然不是我们想要的Result结果，所以我们就需要对全局的异常一同的来做一个处理。方法如下：

第一步：定义一个用于处理异常的处理类
第二步：在类上添加@RestControllerAdvice注解
第三步：定义处理异常的方法
第四步：在方法上通过@ExceptionHandler注解指定处理的异常
示例如下：

@RestControllerAdvice
@Slf4j
public class GlobalException 

    @ExceptionHandler(DataAccessException.class)
    public Result sqlException(DataAccessException e)
        log.info(e.getMessage());
//        说明这个时候系统中存在sql异常
        return Result.error("数据异常");
    

    @ExceptionHandler(Exception.class)
    public Result othersException()
        return Result.error("服务器异常,请联系管理员");
    

这样就做到了程序中即使有异常，也做到了统一响应结果的目的，前端就可以通过返回值来进行对应的处理。

spring boot 2 全局统一返回RESTful风格数据统一异常处理

全局统一返回RESTful风格数据，主要是实现ResponseBodyAdvice接口的方法，对返回值在输出之前进行修改。
使用注解@RestControllerAdvice拦截异常并统一处理。

开发环境：
IntelliJ IDEA 2019.2.2
jdk1.8
Spring Boot 2.2.2

1、创建一个SpringBoot项目，pom.xml引用的依赖包如下

        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>

        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
            <optional>true</optional>
        </dependency>

        <dependency>
            <groupId>com.alibaba</groupId>
            <artifactId>fastjson</artifactId>
            <version>1.2.62</version>
        </dependency>

2、定义一个返回类

package com.example.response.entity;

import lombok.Data;
import lombok.NoArgsConstructor;
import lombok.ToString;

import java.io.Serializable;

@Data
@NoArgsConstructor
@ToString
public class ResponseData<T> implements Serializable {
    /**
     * 状态码：0-成功，1-失败
     * */
    private int code;

    /**
     * 错误消息，如果成功可为空或SUCCESS
     * */
    private String msg;

    /**
     * 返回结果数据
     * */
    private T data;

    public static ResponseData success() {
        return success(null);
    }

    public static ResponseData success(Object data) {
        ResponseData result = new ResponseData();
        result.setCode(0);
        result.setMsg("SUCCESS");
        result.setData(data);
        return result;
    }

    public static ResponseData fail(String msg) {
        return fail(msg,null);
    }

    public static ResponseData fail(String msg, Object data) {
        ResponseData result = new ResponseData();
        result.setCode(1);
        result.setMsg(msg);
        result.setData(data);
        return result;
    }
}

3、统一拦截接口返回数据

新建一个类GlobalResponseHandler，用注解@RestControllerAdvice，并且实现ResponseBodyAdvice接口的方法，其中方法supports可以判断哪些需要拦截，方法beforeBodyWrite可以对返回值在输出之前进行修改，从而实现返回统一的接口数据。

package com.example.response.config;

import com.alibaba.fastjson.JSON;
import com.example.response.entity.ResponseData;
import org.springframework.core.MethodParameter;
import org.springframework.http.MediaType;
import org.springframework.http.converter.HttpMessageConverter;
import org.springframework.http.server.ServerHttpRequest;
import org.springframework.http.server.ServerHttpResponse;
import org.springframework.web.bind.annotation.RestControllerAdvice;
import org.springframework.web.servlet.mvc.method.annotation.ResponseBodyAdvice;

/**
 * 实现ResponseBodyAdvice接口，可以对返回值在输出之前进行修改
 */
@RestControllerAdvice
public class GlobalResponseHandler implements ResponseBodyAdvice<Object> {

    //判断支持的类型
    @Override
    public boolean supports(MethodParameter methodParameter, Class<? extends HttpMessageConverter<?>> aClass) {
        // 检查注解是否存在，存在则忽略拦截
        if (methodParameter.getDeclaringClass().isAnnotationPresent(IgnorReponseAdvice.class)) {
            return false;
        }
        if (methodParameter.getMethod().isAnnotationPresent(IgnorReponseAdvice.class)) {
            return false;
        }
        return true;
    }

    @Override
    public Object beforeBodyWrite(Object o, MethodParameter methodParameter, MediaType mediaType, Class<? extends HttpMessageConverter<?>> aClass, ServerHttpRequest serverHttpRequest, ServerHttpResponse serverHttpResponse) {
        // 判断为null构建ResponseData对象进行返回
        if (o == null) {
            return ResponseData.success();
        }
        // 判断是ResponseData子类或其本身就返回Object o本身，因为有可能是接口返回时创建了ResponseData,这里避免再次封装
        if (o instanceof ResponseData) {
            return (ResponseData<Object>) o;
        }
        // String特殊处理，否则会抛异常
        if (o instanceof String) {
            return JSON.toJSON(ResponseData.success(o)).toString();
        }
        return ResponseData.success(o);
    }
}

新建自定义注解IgnorReponseAdvice

package com.example.response.config;

import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

@Target({ElementType.TYPE, ElementType.METHOD})
@Retention(RetentionPolicy.RUNTIME)
public @interface IgnorReponseAdvice {
}

4、统一异常处理

package com.example.response.exception;
import com.example.response.entity.ResponseData;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.RestControllerAdvice;

@RestControllerAdvice
public class GlobalExceptionHandler {
    @ExceptionHandler(Exception.class)
    public ResponseData exceptionHandler(Exception e) {
        e.printStackTrace();
        return ResponseData.fail("服务器异常：" + e.getMessage());
    }
}

5、新建一个测试用的实体类

package com.example.response.entity;

import lombok.Data;

@Data
public class User {
    private Long userId;
    private String userName;
    public User(Long userId, String userName){
        this.userId = userId;
        this.userName = userName;
    }
}

6、新建一个测试用的控制器类

package com.example.response.controller;

import com.example.response.config.IgnorReponseAdvice;
import com.example.response.entity.ResponseData;
import com.example.response.entity.User;
import org.springframework.web.bind.annotation.*;

import java.util.ArrayList;
import java.util.List;

@RestController
public class DemoController {
    @GetMapping("user")
    public User user() {
        User u = new User(100L, "u1");
        return u;
    }

    @GetMapping("userList")
    public List<User> userList(){
        List<User> list = new ArrayList<User>();
        list.add(new User(100L, "u1"));
        list.add(new User(200L, "u2"));
        return list;
    }

    @GetMapping("test1")
    public String test1(){
        return "test1";
    }

    @GetMapping("test2")
    public ResponseData test2(){
        return ResponseData.success("test2");
    }

    @IgnorReponseAdvice
    @GetMapping("test3")
    public String test3() {
        return "test3";
    }

    @GetMapping("test4")
    public String test4() {
        Integer x = 1 / 0;
        return x.toString();
    }

    @GetMapping("test5")
    public String test5() throws Exception {
        throw new Exception("自定义异常信息");
    }
}

7、用Postman测试

(1)请求http://localhost:8080/user，返回

{
    "code": 0,
    "msg": "SUCCESS",
    "data": {
        "userId": 100,
        "userName": "u1"
    }
}

(2)请求http://localhost:8080/userList，返回

{
    "code": 0,
    "msg": "SUCCESS",
    "data": [
        {
            "userId": 100,
            "userName": "u1"
        },
        {
            "userId": 200,
            "userName": "u2"
        }
    ]
}

(3)请求http://localhost:8080/tes1，返回

{"msg":"SUCCESS","code":0,"data":"test1"}

(4)请求http://localhost:8080/test2，返回

{
    "code": 0,
    "msg": "SUCCESS",
    "data": "test2"
}

(5)请求http://localhost:8080/test3，返回

test3

(6)请求http://localhost:8080/test4，返回

{
    "code": 1,
    "msg": "服务器异常：/ by zero",
    "data": null
}

(7)请求http://localhost:8080/test5，返回

{
    "code": 1,
    "msg": "服务器异常：自定义异常信息",
    "data": null
}

  

参考文章：
https://blog.csdn.net/lrt890424/article/details/83624761
https://www.cnblogs.com/Purgeyao/p/11599810.html