大型Spring Boot应用中错误消息与代码的管理方案

DevOps 小满

2026-6-20

问题

在拥有超100种与HTTP状态码匹配的错误消息的大型Spring Boot应用中，如何基于Java系统地为所有API配置对应错误码的错误消息？

除了在每个API方法中逐个处理异常，是否存在如@ControllerAdvice这类通用异常处理方案？使用@ControllerAdvice有哪些弊端，尤其是在异常处理器的执行顺序方面？

@GetMapping("/user/{id}")
public ResponseEntity<UserResponse> getUserById(@PathVariable String id) {
    List<UserInfo> userInfoByIdList = null;
    try {
        userInfoByIdList = userService.getUserById(id);
        if (userInfoByIdList.isEmpty()) {
            throw new NoUserFoundException("没有找到ID为: " + id + "的用户");
        }
        if (userInfoByIdList.get(0).isDeleted()) {
            throw new UserDeletedException("ID为: " + id + "的用户已被删除");
        }
        if (!userService.isUserEligible(userInfoByIdList.get(0))) {
            throw new UserNotEligibleForAccessingUserException("ID为: " + id + "的用户无访问权限");
        }
    } catch (NoUserFoundException e) {
        log.error("获取用户时触发NoUserFoundException，用户ID {}: {}", id, e.getMessage(), e);
        return new ResponseEntity<>(new UserResponse(HttpStatus.NOT_FOUND.value(), e.getMessage()), 
                                    HttpStatus.NOT_FOUND);
    } catch (UserDeletedException e) {
        log.error("获取用户时触发UserDeletedException，用户ID {}: {}", id, e.getMessage(), e);
        return new ResponseEntity<>(new UserResponse(HttpStatus.GONE.value(), e.getMessage()), 
                                    HttpStatus.GONE);
    } catch (UserNotEligibleForAccessingUserException e) {
        log.error("获取用户时触发UserNotEligibleForAccessingUserException，用户ID {}: {}", id, e.getMessage(), e);
        return new ResponseEntity<>(new UserResponse(HttpStatus.FORBIDDEN.value(), e.getMessage()), 
                                    HttpStatus.FORBIDDEN);
    } catch (ServiceException e) {
        log.error("获取用户时触发ServiceException，用户ID {}: {}", id, e.getMessage(), e);
        return new ResponseEntity<>(new UserResponse(HttpStatus.INTERNAL_SERVER_ERROR.value(), e.getMessage()), 
                                    HttpStatus.INTERNAL_SERVER_ERROR);
    } catch (Exception e) {
        log.error("获取用户时触发未知错误，用户ID {}: {}", id, e.getMessage(), e);
        return new ResponseEntity<>(new UserResponse(HttpStatus.INTERNAL_SERVER_ERROR.value(), e.getMessage()), 
                                    HttpStatus.INTERNAL_SERVER_ERROR);
    }

    return new ResponseEntity<>(new UserResponse(HttpStatus.OK.value(), userInfoByIdList), HttpStatus.OK);
}

回答

一、系统配置HTTP错误码与消息的方案

1. 自定义异常体系+统一处理器+消息配置文件

先搭建分层异常体系：定义业务异常基类，所有具体业务异常继承它，内置HTTP状态码、错误码字段；再用配置文件集中管理100+条错误消息，避免硬编码。

示例代码：

// 业务异常基类
public class BaseBusinessException extends RuntimeException {
    private final HttpStatus httpStatus;
    private final String errorCode;
    private final Object[] args; // 消息参数，用于动态填充

    public BaseBusinessException(String message, HttpStatus httpStatus, String errorCode, Object... args) {
        super(message);
        this.httpStatus = httpStatus;
        this.errorCode = errorCode;
        this.args = args;
    }

    // getter方法省略
}

// 具体业务异常
public class NoUserFoundException extends BaseBusinessException {
    public NoUserFoundException(String userId) {
        super("用户不存在", HttpStatus.NOT_FOUND, "USER_NOT_FOUND", userId);
    }
}

创建error-messages.properties配置文件：

USER_NOT_FOUND=用户ID:{0}不存在
USER_DELETED=用户ID:{0}已被删除
USER_NOT_ELIGIBLE=用户ID:{0}无访问权限
# 其他100+条错误消息

最后通过@ControllerAdvice结合MessageSource读取配置，统一处理异常：

@ControllerAdvice
public class GlobalExceptionHandler {
    @Autowired
    private MessageSource messageSource;

    @ExceptionHandler(BaseBusinessException.class)
    public ResponseEntity<UserResponse> handleBusinessException(BaseBusinessException e, Locale locale) {
        // 从配置文件读取格式化后的消息
        String errorMsg = messageSource.getMessage(e.getErrorCode(), e.getArgs(), e.getMessage(), locale);
        log.error("业务异常: {}", errorMsg, e);
        return new ResponseEntity<>(new UserResponse(e.getHttpStatus().value(), errorMsg), e.getHttpStatus());
    }

    // 处理系统级异常
    @ExceptionHandler(Exception.class)
    public ResponseEntity<UserResponse> handleGlobalException(Exception e) {
        log.error("系统异常", e);
        return new ResponseEntity<>(new UserResponse(HttpStatus.INTERNAL_SERVER_ERROR.value(), "系统繁忙，请稍后再试"), 
                                    HttpStatus.INTERNAL_SERVER_ERROR);
    }
}

2. 枚举类集中管理错误元数据

用枚举类统一维护错误码、HTTP状态码、消息键，避免分散管理：

public enum ErrorCodeEnum {
    USER_NOT_FOUND("USER_NOT_FOUND", HttpStatus.NOT_FOUND),
    USER_DELETED("USER_DELETED", HttpStatus.GONE),
    USER_NOT_ELIGIBLE("USER_NOT_ELIGIBLE", HttpStatus.FORBIDDEN),
    // 其他100+个枚举项
    ;

    private final String code;
    private final HttpStatus status;

    ErrorCodeEnum(String code, HttpStatus status) {
        this.code = code;
        this.status = status;
    }

    // getter方法省略
}

抛出异常时直接传入枚举项，处理器中通过枚举获取状态码和消息键，进一步降低耦合。

二、通用异常处理方案：@ControllerAdvice

@ControllerAdvice是Spring官方提供的全局异常处理方案，完全可以替代你代码中每个API的重复try-catch逻辑。它会拦截所有控制器抛出的异常，统一处理后返回标准化响应，让业务代码更专注于核心逻辑。

使用它重构后，你的getUserById方法可以简化成：

@GetMapping("/user/{id}")
public ResponseEntity<UserResponse> getUserById(@PathVariable String id) {
    List<UserInfo> userInfoByIdList = userService.getUserById(id);
    if (userInfoByIdList.isEmpty()) {
        throw new NoUserFoundException(id);
    }
    UserInfo userInfo = userInfoByIdList.get(0);
    if (userInfo.isDeleted()) {
        throw new UserDeletedException(id);
    }
    if (!userService.isUserEligible(userInfo)) {
        throw new UserNotEligibleForAccessingUserException(id);
    }
    return new ResponseEntity<>(new UserResponse(HttpStatus.OK.value(), userInfoByIdList), HttpStatus.OK);
}

三、@ControllerAdvice的弊端及解决办法

1. 执行顺序问题

默认情况下，多个@ControllerAdvice的执行顺序是不确定的（取决于Spring Bean的加载顺序），如果多个处理器能处理同一种异常，可能出现预期外的执行结果。

解决办法：

用@Order注解指定优先级，值越小优先级越高：

@ControllerAdvice
@Order(1) // 优先执行
public class BusinessExceptionHandler {
    @ExceptionHandler(BaseBusinessException.class)
    public ResponseEntity<UserResponse> handleBusinessException(BaseBusinessException e, Locale locale) {
        // 处理逻辑
    }
}

@ControllerAdvice
@Order(2) // 后执行
public class GlobalExceptionHandler {
    @ExceptionHandler(Exception.class)
    public ResponseEntity<UserResponse> handleGlobalException(Exception e) {
        // 处理逻辑
    }
}

单个@ControllerAdvice中，按异常从具体到通用的顺序编写@ExceptionHandler方法（Spring会优先匹配最具体的异常类型）。

2. 过度集中导致维护困难

如果所有异常处理逻辑都放在一个@ControllerAdvice类中，当异常类型超过100种时，这个类会变得异常庞大，难以维护。

解决办法：

按业务模块拆分多个@ControllerAdvice，比如UserExceptionHandler、OrderExceptionHandler，每个负责处理对应模块的异常。
用@RestControllerAdvice（专门处理REST接口）和@ControllerAdvice（处理页面控制器）分开配置。

3. 范围控制不当问题

默认@ControllerAdvice会作用于所有控制器，如果需要针对特定包/控制器做特殊处理，配置不当会导致异常处理范围不符合预期。

解决办法：
通过注解参数指定作用范围：

// 只作用于com.example.user包下的控制器
@ControllerAdvice(basePackages = "com.example.user")
public class UserModuleExceptionHandler {
}

// 只作用于指定控制器
@ControllerAdvice(assignableTypes = UserController.class)
public class UserControllerExceptionHandler {
}

4. 异常链处理复杂

当异常被多层包装（比如ServiceException包裹了NoUserFoundException），@ExceptionHandler默认只会捕获最外层异常，需要手动解析异常链才能处理原始异常，增加代码复杂度。

解决办法：
在处理器中递归解析异常链，找到最底层的业务异常：

private BaseBusinessException extractBaseException(Throwable throwable) {
    if (throwable instanceof BaseBusinessException) {
        return (BaseBusinessException) throwable;
    }
    if (throwable.getCause() != null) {
        return extractBaseException(throwable.getCause());
    }
    return null;
}

内容的提问来源于stack exchange，提问作者Kevin Luko

大型Spring Boot应用中错误消息与代码的管理方案

一、系统配置HTTP错误码与消息的方案 #

1. 自定义异常体系+统一处理器+消息配置文件 #

2. 枚举类集中管理错误元数据 #

二、通用异常处理方案：@ControllerAdvice #

三、@ControllerAdvice的弊端及解决办法 #

1. 执行顺序问题 #

2. 过度集中导致维护困难 #

3. 范围控制不当问题 #

4. 异常链处理复杂 #