Spring Boot微服务中按OpenAPI要求实现自定义错误返回的问题

我正在使用Java Spring Boot开发汽车共享平台，通过OpenAPI文件定义接口路径与数据模型，需求如下：

• 按ID查询用户不存在时，返回自定义错误信息；
• 查询成功时返回ApiUser类型数据，且不能修改方法的返回类型。

当前Controller的getUserById方法出现类型不兼容错误，错误提示：

Incompatible types. Found: 'org.springframework.http.ResponseEntity<java.lang.String>', required: 'org.springframework.http.ResponseEntity<com.example.userservice.api.model.ApiUser>'

已自定义UserException异常类，Service层会在用户不存在时抛出该异常，但Controller无法正确返回错误信息。相关代码见下文。

getUserById方法的返回类型是ResponseEntity<ApiUser>，但catch块中尝试返回字符串类型的body，导致类型不匹配。必须保证返回的ResponseEntity的body类型始终符合方法定义，同时满足异常场景下返回自定义错误信息的需求。

方案：使用全局异常处理器（推荐） #

通过全局异常处理器统一捕获UserException，返回符合OpenAPI定义的ApiError结构，既满足方法返回类型要求，又能输出自定义错误信息。

1. 创建全局异常处理器类

package com.example.userservice.web;

import com.example.userservice.api.model.ApiError;
import com.example.userservice.domain.user.UserException;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.ControllerAdvice;
import org.springframework.web.bind.annotation.ExceptionHandler;

@ControllerAdvice
public class GlobalExceptionHandler {

    @ExceptionHandler(UserException.class)
    public ResponseEntity<ApiError> handleUserException(UserException ex) {
        ApiError errorResponse = new ApiError();
        errorResponse.setCode("2300");
        errorResponse.setMessage(ex.getMessage());
        // 用户不存在符合REST规范的404状态码，可根据需求调整
        return new ResponseEntity<>(errorResponse, HttpStatus.NOT_FOUND);
    }
}

2. 修改Controller的getUserById方法

移除try-catch块，让异常直接被全局处理器捕获，方法仅处理成功场景：

@Override
public ResponseEntity<ApiUser> getUserById(Long userID) {
    User user = userService.getUserById(userID);
    return ResponseEntity.ok(toDto(user));
}

package com.example.userservice.web;

import com.example.userservice.api.model.ApiCar;
import com.example.userservice.api.model.ApiUsers;
import com.example.userservice.domain.car.Car;
import com.example.userservice.domain.user.User;
import com.example.userservice.domain.user.UserService;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.http.ResponseEntity;
import org.springframework.stereotype.Component;
import com.example.userservice.api.UserApiDelegate;
import com.example.userservice.api.model.ApiUser;

import java.util.List;

@Component
public class UserController implements UserApiDelegate {

    private final UserService userService;

    @Autowired
    public UserController(UserService userService) {
        this.userService = userService;
    }

    @Override
    public ResponseEntity<String> createUser(ApiUser data) {
        try {
            userService.createUser(data);
            return ResponseEntity.ok("Successfully created user");
        } catch (UserException e) {
            return ResponseEntity
                    .status(HttpStatus.BAD_REQUEST)
                    .body("Error creating user: " + e.getMessage());
        }
    }

    @Override
    public ResponseEntity<ApiUser> getUserById(Long userID) {
        User user = userService.getUserById(userID);
        return ResponseEntity.ok(toDto(user));
    }

    @Override
    public ResponseEntity<ApiUsers> getUsers() {
        ApiUsers apiUsers = new ApiUsers();
        List<User> users = userService.getUsers();

        for (User user : users) {
            apiUsers.add(toDto(user));
        }

        return ResponseEntity.ok(apiUsers);
    }

    private ApiUser toDto(User user) {
        ApiUser apiUser = new ApiUser();
        apiUser.setName(user.getName());
        apiUser.setUserID(user.getUserID());
        apiUser.setEmail(user.getEmail());
        if (user.getCar() != null) {
            apiUser.setCar(toApiCarDto(user.getCar()));
        }
        return apiUser;
    }

    public static ApiCar toApiCarDto(Car car) {
        ApiCar apiCar = new ApiCar();
        apiCar.setCarID(car.getCarID());
        apiCar.setBrand(car.getBrand());
        apiCar.setModel(car.getModel());
        apiCar.setPricePerHour(car.getPricePerHour());
        apiCar.setLocation(car.getLocation());
        return apiCar;
    }
}

内容的提问来源于stack exchange，提问作者kuno vercammen