SpringBoot统一返回和统一异常处理

前言

最近在工作中需要新建一个项目，需要处理统一返回和统一异常处理，发现挺不错，特地拿出来分享给大家。

为了有良好的演示效果，我特地重新建了一个项目，把核心代码提炼出来加上了更多注释说明，希望xdm喜欢。

案例

一、项目结构

二、引入依赖

引入pom.xml文件依赖，依赖按照项目所需按需提取。

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <groupId>com.example</groupId>
    <artifactId>responseResultAndException</artifactId>
    <version>0.0.1-SNAPSHOT</version>
    <name>responseResultAndException</name>
    <description>responseResultAndException</description>
    <properties>
        <java.version>1.8</java.version>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
        <project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
        <spring-boot.version>2.6.13</spring-boot.version>
    </properties>
    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>

        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
        </dependency>
        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
            <version>1.18.10</version>
            <scope>compile</scope>
        </dependency>
        <dependency>
            <groupId>io.projectreactor</groupId>
            <artifactId>reactor-core</artifactId>
            <version>3.4.17</version>
            <scope>compile</scope>
        </dependency>
        <dependency>
            <groupId>org.springframework</groupId>
            <artifactId>spring-webflux</artifactId>
            <version>5.3.19</version>
            <scope>compile</scope>
        </dependency>
    </dependencies>
    <dependencyManagement>
        <dependencies>
            <dependency>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-dependencies</artifactId>
                <version>${spring-boot.version}</version>
                <type>pom</type>
                <scope>import</scope>
            </dependency>
        </dependencies>
    </dependencyManagement>

    <build>
        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-compiler-plugin</artifactId>
                <version>3.8.1</version>
                <configuration>
                    <source>1.8</source>
                    <target>1.8</target>
                    <encoding>UTF-8</encoding>
                </configuration>
            </plugin>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
                <version>${spring-boot.version}</version>
                <configuration>
                    <mainClass>com.example.responseresultandexception.ResponseResultAndExceptionApplication</mainClass>
                    <skip>true</skip>
                </configuration>
                <executions>
                    <execution>
                        <id>repackage</id>
                        <goals>
                            <goal>repackage</goal>
                        </goals>
                    </execution>
                </executions>
            </plugin>
        </plugins>
    </build>

</project>

application.yml文件配置，文件按照项目所需按需提取。

server:
  port: 8080

三、统一返回结果

前后端分离时代，如果没有一个统一的数据返回格式，前后端调试时，前端开发人员会骂娘的，同时约定相同的返回接口数据也有助于高效的工作。

通常统一返回的格式包含三部分：

• code：状态码，一般 200 表示正常
• message：状态码对应的描述。
• data：返回的数据。

3.1、统一返回对象

新建一个 SpringBoot 项目定义通用的响应对象。

package com.example.responseresultandexception.utils;

import com.fasterxml.jackson.annotation.JsonInclude;

import java.io.Serializable;
/**
 * @projectName: spring-study
 * @package: com.example.responseresultandexception.utils
 * @className: ResponseResult
 * @author wangwujie
 * @description: TODO
 * @date: 2024-1-25 9:43
 */

@JsonInclude(JsonInclude.Include.NON_NULL)
public class ResponseResult<T> implements Serializable {
    private static final long serialVersionUID = 2233637474601103587L;

    // 接口响应状态码
    private Integer code;

    // 接口响应信息
    private String msg;

    // 接口响应的数据
    private T data;

    public ResponseResult() {
        this.code = AppHttpCodeEnum.SUCCESS.getCode();
        this.msg = AppHttpCodeEnum.SUCCESS.getMsg();
    }

    public ResponseResult(Integer code, T data) {
        this.code = code;
        this.data = data;
    }

    public ResponseResult(Integer code, String msg, T data) {
        this.code = code;
        this.msg = msg;
        this.data = data;
    }

    public ResponseResult(Integer code, String msg) {
        this.code = code;
        this.msg = msg;
    }

    public static ResponseResult errorResult(int code, String msg) {
        ResponseResult result = new ResponseResult();
        return result.error(code, msg);
    }

    public static ResponseResult okResult() {
        ResponseResult result = new ResponseResult();
        return result;
    }

    public static ResponseResult okResult(int code, String msg) {
        ResponseResult result = new ResponseResult();
        return result.ok(code, null, msg);
    }

    public static ResponseResult okResult(Object data) {
        ResponseResult result = setAppHttpCodeEnum(AppHttpCodeEnum.SUCCESS, AppHttpCodeEnum.SUCCESS.getMsg());
        if (data != null) {
            result.setData(data);
        }
        return result;
    }

    public static ResponseResult errorResult(AppHttpCodeEnum enums) {
        return setAppHttpCodeEnum(enums, enums.getMsg());
    }

    public static ResponseResult errorResult(AppHttpCodeEnum enums, String msg) {
        return setAppHttpCodeEnum(enums, msg);
    }

    public static ResponseResult setAppHttpCodeEnum(AppHttpCodeEnum enums) {
        return okResult(enums.getCode(), enums.getMsg());
    }

    private static ResponseResult setAppHttpCodeEnum(AppHttpCodeEnum enums, String msg) {
        return okResult(enums.getCode(), msg);
    }

    public ResponseResult<?> error(Integer code, String msg) {
        this.code = code;
        this.msg = msg;
        return this;
    }

    public ResponseResult<?> ok(Integer code, T data) {
        this.code = code;
        this.data = data;
        return this;
    }

    public ResponseResult<?> ok(Integer code, T data, String msg) {
        this.code = code;
        this.data = data;
        this.msg = msg;
        return this;
    }

    public ResponseResult<?> ok(T data) {
        this.data = data;
        return this;
    }

    public Integer getCode() {
        return code;
    }

    public void setCode(Integer code) {
        this.code = code;
    }

    public String getMsg() {
        return msg;
    }

    public void setMsg(String msg) {
        this.msg = msg;
    }

    public T getData() {
        return data;
    }

    public void setData(T data) {
        this.data = data;
    }
}

3.2、系统常量

上面代码中提到了常量 AppHttpCodeEnum，定义自己的应用程序特定状态码，来表示具体的情况。通过定义的状态码就可以知道具体代表什么意思。

package com.example.responseresultandexception.utils;

/**
 * @projectName: spring-study
 * @package: com.example.responseresultandexception.utils
 * @className: AppHttpCodeEnum
 * @author wangwujie
 * @description: TODO
 * @date: 2024-1-25 9:43
 */

public enum AppHttpCodeEnum {
    // 成功
    SUCCESS(200,"成功"),
    // 失败
    ERROR(500,"失败");

    int code;
    String msg;

    AppHttpCodeEnum(int code, String errorMessage){
        this.code = code;
        this.msg = errorMessage;
    }

    public int getCode() {
        return code;
    }

    public String getMsg() {
        return msg;
    }
    }

3.3、控制层新建请求响应，web 层统一响应结果

在controller层下面新建，下面的例子，可以看到在实际项目中接口返回值。

/*
 * Copyright 2013-2018 the original author or authors.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      https://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package com.example.responseresultandexception.demos.web;

import com.example.responseresultandexception.exception.BusinessException;
import com.example.responseresultandexception.utils.AppHttpCodeEnum;
import com.example.responseresultandexception.utils.ResponseResult;
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.ResponseBody;

/***
 * @param null:
 * @return null
 * @author wangwujie
 * @description TODO
 * @date 2024-1-25 10:47
 */
@Controller
public class BasicController {

    // http://127.0.0.1:8080/hello?name=lisi
    @RequestMapping("/hello")
    @ResponseBody
    public ResponseResult hello(@RequestParam(name = "name", defaultValue = "unknown user") String name) {
        return ResponseResult.okResult("Hello " + name);
    }

    // http://127.0.0.1:8080/errorInfo
    @RequestMapping("/errorInfo")
    @ResponseBody
    public String errorInfo() {
        throw new BusinessException(AppHttpCodeEnum.ERROR.getMsg());
    }

}

web请求结果（请求地址：http://127.0.0.1:8080/hello?name=lisi）

四、统一异常处理

程序开发中不可避免的会遇到异常现象，如果不进行处理，遇到异常时，开发人员不能清晰地处理问题，或者使用 try{...}catch{...} 代码块进行处理，但是满屏的 try{...}catch{...} 代码块造成代码过于臃肿。

有没有更好的处理方式呢？全局统一异常处理应运而生。@ControllerAdvice 注解搭配 @ExceptionHandler 进行全局统一异常处理。

4.1、@ControllerAdvice注解

• @ControllerAdvice注解：用于声明一个全局控制器 Advice，相当于把 @ExceptionHandler、@InitBinder 和 @ModelAttribute 注解的方法集中到一个地方。放在特定类上，被认为是全局异常处理器。

4.2、ExceptionHandler 注解

• 用于定义异常处理方法，处理特定类型的异常。放在全局异常处理器类中的具体方法上。 通过这两个注解的配合，可以实现全局的异常处理。当控制器中抛出异常时，SpringBoot 会自动调用匹配的 @ExceptionHandler 方法来处理异常，并返回定义的响应。

步骤如下：

1. 新建一个统一异常处理类
2. 类上标注 @RestControllerAdvice 注解
3. 在方法上标注 @ExceptionHandler 注解，并且指定需要捕获的异常，可以同时捕获多个。

新建 exception 包，在包下新建 GlobalExceptionHandler 类。代码如下：

package com.example.responseresultandexception.exception;

/**
 * @projectName: spring-study
 * @package: com.example.responseresultandexception.exception
 * @className: GlobalExceptionHandler
 * @author wangwujie: wangwujie
 * @description: TODO
 * @date: 2024-1-25 9:49
 */

import com.example.responseresultandexception.utils.AppHttpCodeEnum;
import com.example.responseresultandexception.utils.ResponseResult;
import lombok.extern.slf4j.Slf4j;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.RestControllerAdvice;

/***
 * @param null: 
 * @return null
 * @author wangwujie 
 * @description 全局异常处理器
 * @date 2024-1-25 11:13
 */
@RestControllerAdvice
@Slf4j
public class GlobalExceptionHandler {

    // 全局异常
    @ExceptionHandler(Exception.class)
    public ResponseResult exceptionHandler(Exception e){
        //打印异常信息
        log.error("出现了异常exceptionHandler-{}",e);
        //从异常对象中获取提示信息封装返回
        return ResponseResult.errorResult(AppHttpCodeEnum.SUCCESS.getCode(),e.getMessage());
    }

    // 自定义异常
    @ExceptionHandler(BusinessException.class)
    public ResponseResult BusinessException(BusinessException e){
        //打印异常信息
        log.error("出现了异常BusinessException-{}",e);
        //从异常对象中获取提示信息封装返回
        return ResponseResult.errorResult(e.getCode(),e.getMsg());
    }

}

在exception包下新建自定义异常处理类 BusinessException

package com.example.responseresultandexception.exception;

import com.example.responseresultandexception.utils.AppHttpCodeEnum;
import lombok.Data;

/**
 * @projectName: spring-study
 * @package: com.example.responseresultandexception.exception
 * @className: BbsBusinessException
 * @author wangwujie
 * @description: TODO
 * @date: 2024-1-25 9:53
 */
@Data
public class BusinessException extends RuntimeException{

    private int code;

    private String msg;

    public BusinessException(){
        super();
    }
    public BusinessException(String msg){
        super(msg);
        this.code = AppHttpCodeEnum.ERROR.getCode();
        this.msg = msg;
    }

    public BusinessException(int code, String msg){
        super(msg);
        this.code = code;
        this.msg = msg;
    }

}

4.3、统一异常处理使用

在业务开发中，可以在 service 层处理业务时，可以手动抛出异常，由全局异常处理器处理进行统一处理，演示方便，我直接在controller层进行异常抛出，在1.3中的BasicController.java增加errorInfo()方法。

/*
 * Copyright 2013-2018 the original author or authors.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      https://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package com.example.responseresultandexception.demos.web;

import com.example.responseresultandexception.exception.BusinessException;
import com.example.responseresultandexception.utils.AppHttpCodeEnum;
import com.example.responseresultandexception.utils.ResponseResult;
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.ResponseBody;

/***
 * @param null:
 * @return null
 * @author wangwujie
 * @description TODO
 * @date 2024-1-25 10:47
 */
@Controller
public class BasicController {

    // http://127.0.0.1:8080/hello?name=lisi
    @RequestMapping("/hello")
    @ResponseBody
    public ResponseResult hello(@RequestParam(name = "name", defaultValue = "unknown user") String name) {
        return ResponseResult.okResult("Hello " + name);
    }

    // http://127.0.0.1:8080/errorInfo
    @RequestMapping("/errorInfo")
    @ResponseBody
    public String errorInfo() {
        throw new BusinessException(AppHttpCodeEnum.ERROR.getMsg());
    }

}

当我们请求接口时，假如用户名称或者密码错误，接口就会响应(请求地址:http://127.0.0.1:8080/errorInfo)：

实际开发中还有许多的异常需要捕获，比如 Token 失效、过期等异常， 如果整合了其他的框架，还要注意这些框架抛出的异常，比如Spring Security 等框架。

五、总结

在 SpringBoot 项目中，统一返回和统一异常处理是非常常用的一环，它们能提高应用的可读性和可维护性，统一返回有助于保持代码一致性和规范性，在前后端联调时更加方便，统一异常处理，减少了代码冗余，对异常处理更加易于管理。