SpringBoot 统一数据返回与异常处理详解

我们需要一个通用的结果包装类 Result：

package com.hbu.book.model;

import com.hbu.book.enums.ResultCodeEnum;
import lombok.Data;

@Data
public class Result<T> {
    private ResultCodeEnum code; // -1 未登录 200 正常 -2 出错
    private String errMsg;
    private T data;

    public static <T> Result success(T data) {
        Result result = new Result();
        result.setCode(ResultCodeEnum.SUCCESS);
        result.setErrMsg("");
        result.setData(data);
        return result;
    }

    public static <T> Result fail(String errMsg) {
        Result result = new Result();
        result.setCode(ResultCodeEnum.FAIL);
        result.setErrMsg(errMsg);
        result.setData(null);
        return result;
    }

    public static <T> Result fail(String errMsg, T data) {
        Result result = new Result();
        result.setCode(ResultCodeEnum.FAIL);
        result.setErrMsg(errMsg);
        result.setData(data);
        return result;
    }

    public static <T> Result unlogin() {
        Result result = new Result();
        result.setCode(ResultCodeEnum.UNLOGIN);
        result.setErrMsg("用户未登录");
        return result;
    }
}

修改 ResponseAdvice 中的 supports 为 true，并在 beforeBodyWrite 中返回封装后的对象：

package com.hbu.book.responseAdvice;

import com.hbu.book.model.Result;
import org.jspecify.annotations.Nullable;
import org.springframework.core.MethodParameter;
import org.springframework.http.MediaType;
import org.springframework.http.server.ServerHttpRequest;
import org.springframework.http.server.ServerHttpResponse;
import org.springframework.web.servlet.mvc.method.annotation.ResponseBodyAdvice;

public class ResponseAdvice implements ResponseBodyAdvice {
    @Override
    public boolean supports(MethodParameter returnType, Class converterType) {
        return true;
    }

    @Override
    public @Nullable Object beforeBodyWrite(@Nullable Object body,
                                            MethodParameter returnType,
                                            MediaType selectedContentType,
                                            Class selectedConverterType,
                                            ServerHttpRequest request,
                                            ServerHttpResponse response) {
        return Result.success(body);
    }
}

再次访问接口，可以看到所有数据都被包裹在了 Result 结构中：

存在问题

在实际测试中发现，当控制器返回类型为 String 时，偶尔会出现类型转换错误，尽管数据库中数据已正确写入。

package com.hbu.book.controller;

import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RequestMapping("/test")
@RestController
public class TestController {
    @RequestMapping("/t1")
    public String t1() {
        return "t1";
    }

    @RequestMapping("/t2")
    public boolean t2() {
        return true;
    }

    @RequestMapping("/t3")
    public Integer t3() {
        return 200;
    }
}

经排查，核心原因在于 Spring 的消息转换器优先级机制。当方法返回 String 时，Spring 优先使用 StringHttpMessageConverter，但该转换器只处理 String 类型。而我们的 ResponseAdvice 将 String 包装成了 Result 对象，导致转换器尝试将 Result 强制转为 String 时报错。

代码优化

针对上述问题，需要在 beforeBodyWrite 中增加对 String 类型的特殊处理，利用 Jackson 的 ObjectMapper 进行序列化：

package com.hbu.book.config;

import com.hbu.book.model.Result;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.core.MethodParameter;
import org.springframework.http.MediaType;
import org.springframework.http.server.ServerHttpRequest;
import org.springframework.http.server.ServerHttpResponse;
import org.springframework.web.bind.annotation.ControllerAdvice;
import org.springframework.web.servlet.mvc.method.annotation.ResponseBodyAdvice;
import tools.jackson.databind.ObjectMapper;

@ControllerAdvice
public class ResponseAdvice implements ResponseBodyAdvice {
    @Autowired
    private ObjectMapper objectMapper;

    @Override
    public boolean supports(MethodParameter returnType, Class converterType) {
        return true;
    }

    @Override
    public Object beforeBodyWrite(Object body, MethodParameter returnType,
                                  MediaType selectedContentType, Class selectedConverterType,
                                  ServerHttpRequest request, ServerHttpResponse response) {
        if (body instanceof Result) {
            return body;
        }
        if (body instanceof String) {
            try {
                return objectMapper.writeValueAsString(Result.success(body));
            } catch (Exception e) {
                throw new RuntimeException(e);
            }
        }
        return Result.success(body);
    }
}

优点

1. 前端解析便捷：统一的数据结构降低了前端对接成本。
2. 规范制定：后端团队可强制执行标准，避免返回内容五花八门。
3. 维护性高：若需调整状态码或字段名，只需修改一处即可全局生效。

统一异常处理

全局异常处理通常结合 @ControllerAdvice 和 @ExceptionHandler 实现。当发生异常时，框架会自动调用对应的处理方法。

package com.hbu.book.config;

import com.hbu.book.model.Result;
import lombok.extern.slf4j.Slf4j;
import org.springframework.web.bind.annotation.ControllerAdvice;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.ResponseBody;

@ControllerAdvice
@ResponseBody
@Slf4j
public class ExceptionAdvice {
    @ExceptionHandler
    public Object handler(Exception e) {
        log.error("出现异常：", e);
        return Result.fail(e.getMessage());
    }
}

验证效果：

package com.hbu.book.controller;

import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RequestMapping("/test")
@RestController
public class TestController {
    @RequestMapping("/t1")
    public String t1() {
        Integer x = 7 / 0;
        return "t1";
    }

    @RequestMapping("/t2")
    public boolean t2() {
        String a = null;
        a.contains("a");
        return true;
    }

    @RequestMapping("/t3")
    public Integer t3() {
        int[] arr = new int[10];
        System.out.println(arr[100]);
        return 200;
    }
}

针对不同异常，可以定义多个处理器方法，或者指定具体的异常类型：

package com.hbu.book.config;

import com.hbu.book.model.Result;
import lombok.extern.slf4j.Slf4j;
import org.springframework.web.bind.annotation.ControllerAdvice;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.ResponseBody;

@ControllerAdvice
@ResponseBody
@Slf4j
public class ExceptionAdvice {
    @ExceptionHandler
    public Object handler(Exception e) {
        log.error("出现异常：", e);
        return Result.fail(e.getMessage());
    }

    @ExceptionHandler(NullPointerException.class)
    public Object handler1(Exception e) {
        log.error("出现空指针异常：", e);
        return Result.fail("系统内部错误");
    }

    @ExceptionHandler(ArrayIndexOutOfBoundsException.class)
    public Object handler2(Exception e) {
        log.error("出现数组越界异常：", e);
        return Result.fail("参数错误");
    }
}

生产环境中，建议不要将具体的异常堆栈信息直接返回给前端，以免泄露敏感细节。如果没有匹配到具体异常的处理器，Spring 会自动向上查找父类的异常处理方法，确保异常最终能被捕获处理。