Spring中如何强制服务接口仅存在1个实例（默认实现除外）

核心实现步骤 #

1. 统一自定义实现的Bean注册规则 #

所有自定义IStorageService实现类的@Bean方法，直接按业务逻辑加@ConditionalOnExpression注解即可，不需要额外加@Primary或其他条件注解，示例：

// OSS自定义实现
@Bean
@ConditionalOnExpression("'${storage.type}'.equals('oss')")
public IStorageService ossStorageService() {
    return new OssStorageService();
}

// S3自定义实现
@Bean
@ConditionalOnExpression("'${storage.type}'.equals('s3')")
public IStorageService s3StorageService() {
    return new S3StorageService();
}

2. 配置默认实现的注册条件 #

给DefaultStorageService的@Bean方法添加@ConditionalOnMissingBean注解，保证容器中不存在任何IStorageService类型的Bean时，才会创建默认实例：

@Bean
@ConditionalOnMissingBean(IStorageService.class)
public IStorageService defaultStorageService() {
    return new DefaultStorageService();
}

注意：如果默认实现定义在Spring Boot自动配置类中，需要给配置类添加@AutoConfigureOrder(Ordered.LOWEST_PRECEDENCE)注解，保证用户自定义的Bean优先被容器处理，避免默认Bean提前注册导致的逻辑异常。

3. 添加启动时多实例校验逻辑 #

实现容器刷新完成的事件监听器，在Spring容器加载完所有Bean后立刻校验IStorageService类型的实例数量，超过1个直接抛出异常终止启动：

@Component
public class StorageServiceValidator implements ApplicationListener<ContextRefreshedEvent> {
    @Override
    public void onApplicationEvent(ContextRefreshedEvent event) {
        // 只处理根容器，避免父子容器重复校验
        if (event.getApplicationContext().getParent() != null) {
            return;
        }
        Map<String, IStorageService> serviceBeans = event.getApplicationContext()
                .getBeansOfType(IStorageService.class);
        int instanceCount = serviceBeans.size();
        if (instanceCount > 1) {
            throw new IllegalStateException(
                String.format("存储服务配置错误：检测到%d个IStorageService实现实例，仅允许配置1个自定义存储服务，请检查storage.type相关配置", instanceCount)
            );
        }
        if (instanceCount == 0) {
            throw new IllegalStateException("存储服务配置错误：未找到任何IStorageService实现实例");
        }
    }
}

规则匹配逻辑 #

• 无自定义配置：所有自定义实现的条件表达式均不满足，无自定义Bean注册，@ConditionalOnMissingBean条件生效，自动创建DefaultStorageService实例，校验时实例数为1，正常启动。
• 配置1个自定义实现：对应自定义Bean注册成功，@ConditionalOnMissingBean条件不满足，默认实例不创建，校验时实例数为1，正常启动，使用自定义实现。
• 配置≥2个自定义实现：多个自定义Bean同时注册，默认实例不创建，校验时实例数≥2，直接抛出异常终止启动。

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