Spring中ResponseEntity错误消息处理：不同返回类型的最佳实践

核心问题说明 #

你当前的代码存在类型不匹配的编译问题：方法返回类型是Mono<ResponseEntity<UserAccessData>>，但错误分支返回的ResponseEntity<String>无法适配这个泛型类型。同时，混用实体类和纯文本响应会导致前端解析逻辑混乱，这是需要优先解决的问题。

最优方案：统一响应格式（推荐） #

不要混用不同格式的响应，建议定义一个通用的响应包装类，同时覆盖成功和错误场景，让前后端有统一的交互标准。

1. 定义通用响应DTO #

public class ApiResponse<T> {
    private int code;
    private String message;
    private T data;

    // 构造方法、getter/setter省略
    // 成功响应快捷方法
    public static <T> ApiResponse<T> success(T data) {
        ApiResponse<T> response = new ApiResponse<>();
        response.setCode(HttpStatus.OK.value());
        response.setMessage("success");
        response.setData(data);
        return response;
    }

    // 错误响应快捷方法
    public static <T> ApiResponse<T> error(int code, String message) {
        ApiResponse<T> response = new ApiResponse<>();
        response.setCode(code);
        response.setMessage(message);
        response.setData(null);
        return response;
    }
}

2. 修改接口实现 #

将方法返回类型统一为Mono<ResponseEntity<ApiResponse<UserAccessData>>>，用包装类处理两种场景：

@PostMapping("/login")
public Mono<ResponseEntity<ApiResponse<UserAccessData>>> authorizeUser(@RequestBody @Valid LoginData loginData) {
    return userPort.login(loginData)
            .map(userAccessData -> ResponseEntity.ok(ApiResponse.success(userAccessData)))
            .onErrorResume(ex -> {
                String errorMsg = "User authorization failed: " + ex.getMessage();
                return Mono.just(ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR)
                        .body(ApiResponse.error(HttpStatus.INTERNAL_SERVER_ERROR.value(), errorMsg)));
            });
}

这种方式下，无论成功还是错误，返回的都是结构一致的JSON响应，前端只需通过code字段判断状态，data字段取业务数据，message字段取错误信息即可。

替代方案：全局异常处理 #

如果不想修改每个接口的业务逻辑，可以利用Spring的全局异常处理机制，统一捕获并转换异常为JSON格式响应。

全局异常处理器示例 #

@ControllerAdvice
public class GlobalExceptionHandler {

    @ExceptionHandler(Exception.class)
    public Mono<ResponseEntity<Map<String, Object>>> handleGenericException(Exception ex) {
        Map<String, Object> errorResponse = new HashMap<>();
        errorResponse.put("code", HttpStatus.INTERNAL_SERVER_ERROR.value());
        errorResponse.put("message", "User authorization failed: " + ex.getMessage());
        return Mono.just(ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR).body(errorResponse));
    }
}

此时接口可以简化为只处理成功场景，异常会被全局处理器自动捕获并格式化：

@PostMapping("/login")
public Mono<ResponseEntity<UserAccessData>> authorizeUser(@RequestBody @Valid LoginData loginData) {
    return userPort.login(loginData)
            .map(ResponseEntity::ok);
}

不推荐的方案：统一返回ResponseEntity #

如果强行把所有响应转成JSON字符串并返回Mono<ResponseEntity<String>>，虽然能解决类型问题，但会失去Spring自动序列化的便利性——你需要手动处理对象转JSON（比如依赖Jackson），增加代码复杂度；同时前端还要额外处理字符串转JSON，完全是冗余操作，不建议这么做。

内容的提问来源于stack exchange，提问作者Konrad Groń