接口文档 与 全局异常处理冲突问题

 Knife4j（基于 Swagger）与@RestControllerAdvice（全局异常处理器）在版本兼容性或扫描逻辑上存在冲突，具体原因和解决方法如下：

一、冲突原因

Knife4j 在生成接口文档时，会通过反射扫描项目中的@ControllerAdvice（或@RestControllerAdvice）类。如果你的项目中 Spring Boot 版本（尤其是 3.x 及以上）与 Knife4j 版本不兼容，就会触发ControllerAdviceBean构造方法不匹配、扫描逻辑冲突等问题，导致接口文档无法正常加载。

二、解决方案（无需删除全局异常处理）

推荐通过 “隐藏异常处理器类” 来规避扫描冲突，既保留全局异常处理功能，又能正常显示接口文档：

  1. 添加依赖：确保引入 Swagger 的@Hidden注解依赖（如果是 Knife4j+Spring Boot 3.x，通常已包含）：
1
2
3
4
5
<dependency>
    <groupId>io.swagger.core.v3</groupId>
    <artifactId>swagger-annotations</artifactId>
    <version>2.2.15</version>
</dependency>
  1. 在全局异常处理器类上添加@Hidden注解：
1
2
3
4
5
6
7
8
import io.swagger.v3.oas.annotations.Hidden;
import org.springframework.web.bind.annotation.RestControllerAdvice;

@Hidden // 告诉Knife4j不要扫描这个类，避免冲突
@RestControllerAdvice
public class GlobalExceptionHandler {
    // 原有异常处理方法保持不变...
}

三、原理说明

@Hidden注解是 Swagger/Knife4j 的原生注解，作用是让文档生成工具跳过对该类的扫描。这样既不会影响全局异常处理的正常运行（异常仍会被 Spring 捕获并处理），又能避免 Knife4j 因扫描冲突导致接口文档无法显示的问题。

通过这种方式，你可以同时保留全局异常处理的规范性和Knife4j 接口文档的可用性，无需删除或注释异常处理器代码。