GlobalExceptionHandler 自定义异常类 + 处理validation的异常

在 Spring Boot 项目中，​自定义异常通常用于处理特定的业务逻辑错误，并结合全局异常处理器（@ControllerAdvice）统一返回结构化的错误信息。

一.全局异常处理器： 

1. 自定义异常类​

定义一个继承自 RuntimeException 的业务异常类，包含错误码和错误信息：

public class BusinessException extends RuntimeException {
    private final int code; // 自定义错误码
    private final String message; // 错误信息

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

    // 使用枚举定义错误类型（推荐）
    public BusinessException(ErrorCode errorCode) {
        super(errorCode.getMessage());
        this.code = errorCode.getCode();
        this.message = errorCode.getMessage();
    }

    // Getter
    public int getCode() { return code; }
    @Override public String getMessage() { return message; }
}

​配套的枚举：

public enum ErrorCode {
    USER_NOT_FOUND(1001, "用户不存在"),
    INVALID_PARAM(1002, "参数无效"),
    INTERNAL_ERROR(5000, "系统内部错误");

    private final int code;
    private final String message;

    ErrorCode(int code, String message) {
        this.code = code;
        this.message = message;
    }

    // Getter
    public int getCode() { return code; }
    public String getMessage() { return message; }
}

2. 全局异常处理器​

使用 @ControllerAdvice 捕获异常并统一返回 JSON 格式的错误响应：

@Slf4j
@ControllerAdvice  // 标记该类为全局异常处理器，可以拦截所有Controller抛出的异常
@ResponseBody // 或直接使用 @RestControllerAdvice
public class GlobalExceptionHandler {

    /​**​
     * 处理业务异常
     */
    @ExceptionHandler(BusinessException.class) // 处理自定义异常BusinessException
    @ResponseStatus(HttpStatus.BAD_REQUEST) // 指定HTTP响应的状态码 400 错误
    public Result<Void> handleBusinessException(BusinessException e) {
        log.error("业务异常: code={}, message={}", e.getCode(), e.getMessage());
        return Result.fail(e.getCode(), e.getMessage());
    }

    /​**​
     * 处理系统异常（兜底）
     */
    @ExceptionHandler(Exception.class)  // 处理所有未被其他处理器捕获的异常
    @ResponseStatus(HttpStatus.INTERNAL_SERVER_ERROR) // 指定HTTP响应的状态码 500 错误
    public Result<Void> handleException(Exception e) {
        log.error("系统异常: ", e);
        return Result.fail(ErrorCode.INTERNAL_ERROR.getCode(), "系统繁忙，请稍后重试");
    }
}

统一的响应封装类：

@Data
@NoArgsConstructor
@AllArgsConstructor
public class Result<T> {
    private int code;
    private String message;
    private T data;

    // 成功响应
    public static <T> Result<T> success(T data) {
        return new Result<>(200, "成功", data);
    }

    // 失败响应
    public static <T> Result<T> fail(int code, String message) {
        return new Result<>(code, message, null);
    }
}

3. 在业务代码中抛出异常：

@RestController
@RequestMapping("/user")
public class UserController {

    @GetMapping("/{id}")
    public Result<User> getUser(@PathVariable Long id) {
        User user = userService.findById(id);
        if (user == null) {
            throw new BusinessException(ErrorCode.USER_NOT_FOUND); // 抛出业务异常
        }
        return Result.success(user);
    }
}

4.使用方法：

throw new BusinessException(1001, "用户不存在");

throw new BusinessException(ErrorCode.USER_NOT_FOUND);

二.对于JSR303校验的异常处理：

早在JavaEE6规范中就定义了参数校验的规范，它就是JSR-303，它定义了Bean Validation，即对bean属性进行校验。

SpringBoot提供了JSR-303的支持，它就是spring-boot-starter-validation，它的底层使用Hibernate Validator，Hibernate Validator是Bean Validation 的参考实现。

所以，我们准备在Controller层使用spring-boot-starter-validation完成对请求参数的基本合法性进行校验。

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-validation</artifactId>
</dependency>

在javax.validation.constraints包下有很多这样的校验注解，直接使用注解定义校验规则即可。

例子如下：

package com.xuecheng.content.model.dto;


import io.swagger.v3.oas.annotations.media.Schema;
import jakarta.validation.constraints.NotEmpty;
import jakarta.validation.constraints.Size;
import lombok.Data;
import lombok.ToString;


/**
 * @description 添加课程dto
 * @author Mr.M
 * @date 2022/9/7 17:40
 * @version 1.0
 */
@Data
@ToString
@Schema(name = "AddCourseDto", description = "新增课程基本信息")
public class AddCourseDto {

    @NotEmpty(message = "课程名称不能为空")
    @Schema(description = "课程名称", required = true)
    private String name;

    @NotEmpty(message = "适用人群不能为空")
    @Size(message = "适用人群内容过少",min = 10)
    @Schema(description = "适用人群", required = true)
    private String users;

    @NotEmpty(message = "课程分类不能为空")
    @Schema(description = "大分类", required = true)
    private String mt;

    @NotEmpty(message = "课程分类不能为空")
    @Schema(description = "小分类", required = true)
    private String st;

    @NotEmpty(message = "课程等级不能为空")
    @Schema(description = "课程等级", required = true)
    private String grade;

    @Schema(description = "教学模式（普通，录播，直播等）", required = true)
    private String teachmode;

    @Schema(description = "课程介绍")
    private String description;

    @Schema(description = "课程图片", required = true)
    private String pic;

    @NotEmpty(message = "收费规则不能为空")
    @Schema(description = "收费规则，对应数据字典", required = true)
    private String charge;
}

 上边用到了@NotEmpty和@Size两个注解，@NotEmpty表示属性不能为空，@Size表示限制属性内容的长短。

定义好校验规则还需要开启校验，在controller方法中添加@Validated注解，如下：

@Operation("新增课程基础信息")
@PostMapping("/course")
public CourseBaseInfoDto createCourseBase(@RequestBody @Validated AddCourseDto addCourseDto){
    //机构id，由于认证系统没有上线暂时硬编码
    Long companyId = 1L;
    return courseBaseInfoService.createCourseBase(companyId,addCourseDto);
}

如果校验出错Spring会抛出MethodArgumentNotValidException异常，我们需要在统一异常处理器中捕获异常，解析出异常信息。

@ResponseBody
@ExceptionHandler(MethodArgumentNotValidException.class)
@ResponseStatus(HttpStatus.INTERNAL_SERVER_ERROR)
public RestErrorResponse methodArgumentNotValidException(MethodArgumentNotValidException e) {
    // 拿到校验框架
    BindingResult bindingResult = e.getBindingResult();
    List<String> msgList = new ArrayList<>();
    // 将错误信息放在msgList
    bindingResult.getFieldErrors().stream().forEach(item->msgList.add(item.getDefaultMessage()));
    // 将msgList的错误拼接
    String msg = StringUtils.join(msgList, ",");
    log.error("【系统异常】{}",msg);
    return new RestErrorResponse(msg);
}

有时候在同一个属性上设置一个校验规则不能满足要求，比如：订单编号由系统生成，在添加订单时要求订单编号为空，在更新订单时要求订单编写不能为空。

此时就用到了分组校验，同一个属性定义多个校验规则属于不同的分组，比如：添加订单定义@NULL 规则属于 insert 分组，更新订单定义@NotEmpty规则属于 update 分组，insert 和update 是分组的名称，是可以修改的。

下边举例说明，我们用class类型来表示不同的分组，所以我们定义不同的接口类型（空接口）表示不同的分组，由于校验分组是公用的，所以定义在 base工程中。如下：

package com.xuecheng.base.execption;
 /**
 * @description 校验分组
 * @version 1.0
 */
public class ValidationGroups {

 public interface Inster{};
 public interface Update{};
 public interface Delete{};

}

下边在定义校验规则时指定分组：

@NotEmpty(groups = {ValidationGroups.Inster.class},message = "添加课程名称不能为空")
@NotEmpty(groups = {ValidationGroups.Update.class},message = "修改课程名称不能为空")
// @NotEmpty(message = "课程名称不能为空")
@ApiModelProperty(value = "课程名称", required = true)
private String name;

在Controller方法中启动校验规则指定要使用的分组名：

@Operation("新增课程基础信息")
@PostMapping("/course")
public CourseBaseInfoDto createCourseBase(@RequestBody @Validated({ValidationGroups.Inster.class}) AddCourseDto addCourseDto){
    //机构id，由于认证系统没有上线暂时硬编码
    Long companyId = 1L;
  return courseBaseInfoService.createCourseBase(companyId,addCourseDto);
}

再次测试，由于这里指定了Insert分组，所以抛出 异常信息：添加课程名称不能为空。

如果修改分组为ValidationGroups.Update.class，异常信息为：修改课程名称不能为空。