如何配置独立Spring库使@ControllerAdvice异常处理器被自动识别？

我希望创建一个独立的Spring库，通过@ControllerAdvice处理标准API异常，目标是无需额外配置即可在不同模块中轻松使用。以下是我的异常处理器代码：

@ControllerAdvice
public class ApiErrorControllerAdvice extends ResponseEntityExceptionHandler {

    @ExceptionHandler(value = {ApiErrorException.class})
    public ResponseEntity<ErrorResponseTo> handleApiErrorException(ApiErrorException apiError) {
        return new ResponseEntity<>(
                new ErrorResponseTo(apiError.getMessage()),
                apiError.getHttpStatus()
        );
    }
}

请问应如何配置应用，让该异常处理器被Spring自动识别？

实现自动识别的配置方案 #

要让你的ApiErrorControllerAdvice在其他模块引入后被Spring自动识别，核心是利用Spring Boot自动配置机制，无需使用者手动扫描包或导入类，具体步骤如下：

1. 创建自动配置类 #

在你的库中新增一个配置类，负责显式注册异常处理器Bean：

@Configuration
public class ApiErrorAutoConfiguration {

    @Bean
    public ApiErrorControllerAdvice apiErrorControllerAdvice() {
        return new ApiErrorControllerAdvice();
    }
}

注：@ControllerAdvice本身包含@Component语义，也可通过@ComponentScan扫描该类所在包，但用@Bean显式注册更清晰可控，避免包扫描范围冲突。

2. 配置Spring自动加载入口 #

在你的库的src/main/resources/META-INF目录下创建spring.factories文件，添加以下内容：

org.springframework.boot.autoconfigure.EnableAutoConfiguration=\
com.your.package.ApiErrorAutoConfiguration

将com.your.package替换为ApiErrorAutoConfiguration所在的实际包路径。

当其他Spring Boot项目引入你的库时，Spring Boot会自动读取该文件，加载配置类并注册ApiErrorControllerAdvice，使用者无需做任何额外配置。

3. 确保依赖正确 #

在你的库的构建文件中，添加必要的依赖并避免冲突：

• Maven（pom.xml）：

<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
        <scope>provided</scope>
    </dependency>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-autoconfigure</artifactId>
    </dependency>
</dependencies>

• Gradle（build.gradle）：

dependencies {
    implementation 'org.springframework.boot:spring-boot-autoconfigure'
    compileOnly 'org.springframework.boot:spring-boot-starter-web'
}

使用provided/compileOnly避免重复引入Spring Web依赖，防止与使用者项目的依赖版本冲突。

非Spring Boot项目的兼容方案 #

如果使用者是普通Spring项目（非Boot），无法利用自动配置机制，你可以提供一个快捷注解让使用者快速导入：

@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
@Import(ApiErrorControllerAdvice.class)
public @interface EnableApiErrorHandling {
}

使用者只需在自己的配置类上添加@EnableApiErrorHandling即可启用异常处理器。

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