集成Swagger2与MapStruct触发ConflictingBeanDefinitionException问题

你在Spring Boot集成Swagger2时遇到的这个Bean冲突问题，核心是同名Bean的注册冲突，咱们一步步拆解清楚：

首先来看你触发的异常核心信息：

org.springframework.context.annotation.ConflictingBeanDefinitionException: Annotation-specified bean name 'licenseMapperImpl' for bean class [springfox.documentation.swagger2.mappers.LicenseMapperImpl] conflicts with existing, non-compatible bean definition of same name and class [data.mapper.LicenseMapperImpl]

冲突的根本原因 #

Swagger2的内部实现依赖了MapStruct，它自己也生成了一个LicenseMapperImpl类（包路径为springfox.documentation.swagger2.mappers），用来转换Swagger规范中的License模型。而你的项目里，MapStruct根据你定义的LicenseMapper接口，同样生成了同名的LicenseMapperImpl类，并且两个类都标注了@Component注解。

Spring默认会以类名首字母小写作为Bean的名称（也就是licenseMapperImpl），当Spring容器初始化时，发现两个不同包下的不同类要注册成同一个名称的Bean，自然会抛出冲突异常——Spring无法区分这两个Bean该加载哪一个。

重命名Mapper接口为何能解决问题？ #

MapStruct生成实现类的命名规则是接口名 + Impl：

• 当你的接口是LicenseMapper时，生成的实现类是LicenseMapperImpl，对应的Bean名称是licenseMapperImpl，和Swagger内部的Bean重名；
• 改成LicenseServiceMapper后，生成的实现类变成LicenseServiceMapperImpl，对应的Bean名称是licenseServiceMapperImpl，和Swagger内部的Bean名称彻底错开，冲突自然就消失了。

其他可选解决方案 #

如果不想重命名接口，还有几个可行的办法：

• 给自定义Mapper指定Bean名称
  在你的LicenseMapper接口上，修改@Mapper注解，指定自定义的Bean名称：

  @Mapper(componentModel = "spring", name = "customLicenseMapper")
  public interface LicenseMapper {
      // 你的映射方法
  }
  

  这样MapStruct生成的实现类会使用指定的name作为Bean名称，避免和Swagger的重名。不过注意，你使用的MapStruct 1.3.0.Final在这个特性上有一些小问题，升级到1.4.0及以上版本会更稳定。

• 调整Swagger的组件扫描范围
  在你的SwaggerConfig里，缩小接口扫描的包范围，只扫描你自己项目的控制器包：

  @Configuration
  @EnableSwagger2
  public class SwaggerConfig {
    @Bean
    public Docket api() {
      return new Docket(DocumentationType.SWAGGER_2)
        .select()
        .apis(RequestHandlerSelectors.basePackage("com.yourproject.controller")) // 替换成你的控制器包路径
        .paths(PathSelectors.any())
        .build();
    }
  }
  

  不过这个方法只是缩小了Swagger文档的扫描范围，不能彻底阻止Swagger内部Bean的注册，只是从业务层面避开冲突。

• 升级MapStruct版本
  把MapStruct升级到1.4.0及以上版本，这个版本改进了生成类的Bean命名逻辑，提供了更灵活的命名控制，能更好地避免这类默认名称冲突。

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