解决FeignClient Bean名称重复注册：The bean ‘xxx.FeignClientSpecification‘已定义且覆盖禁用

近期在启动项目时遇到了一个典型的报错：The bean 'contract-management-service.FeignClientSpecification' could not be registered. A bean with that name has already been defined and overriding is disabled.，这个报错直接导致服务启动失败，排查后发现是FeignClient配置的常见疏漏，本文将详细还原问题场景、分析根源，并给出可直接落地的解决方案，帮助快速定位和解决此类问题。

核心内容展开

场景复现（含报错信息、环境配置）

环境配置

• Spring Boot版本：2.6.8
• Spring Cloud版本：2021.0.3
• Spring Cloud OpenFeign版本：3.1.3

问题现象

项目启动时控制台抛出如下异常，服务启动失败：

org.springframework.beans.factory.support.BeanDefinitionOverrideException: The bean 'contract-management-service.FeignClientSpecification' could not be registered. A bean with that name has already been defined and overriding is disabled.

查看项目中的FeignClient接口，发现存在两个及以上使用相同name/value属性的@FeignClient注解，示例如下：

// 第一个FeignClient接口@FeignClient(name="contract-management-service")publicinterfaceContractInfoFeignClient{@GetMapping("/contract/info/{id}")StringgetContractInfo(@PathVariable("id")Longid);}// 第二个FeignClient接口@FeignClient(name="contract-management-service")publicinterfaceContractAuditFeignClient{@PostMapping("/contract/audit")BooleanauditContract(@RequestBodyContractAuditDTOdto);}

问题根源分析

Feign在初始化时，会为每个@FeignClient注解生成对应的FeignClientSpecificationBean，该Bean的名称默认由@FeignClient的name/value属性拼接固定后缀生成（格式为：{name}.FeignClientSpecification）。

Spring容器中Bean的名称是唯一的，当多个@FeignClient使用相同的name/value且未做额外区分时，会生成同名的FeignClientSpecificationBean。而Spring Boot 2.1+版本默认禁用了Bean覆盖（spring.main.allow-bean-definition-overriding=false），因此容器检测到同名Bean时会直接抛出注册异常，导致服务启动失败。

简单来说，核心问题是：相同name/value的@FeignClient未指定contextId，导致生成的FeignClientSpecification Bean名称重复，且Bean覆盖机制禁用。

解决方案

步骤1：指定唯一名称

为每个使用相同name/value的@FeignClient指定唯一的contextId属性，Feign会基于contextId生成唯一的FeignClientSpecificationBean名称，避免重复。

步骤2：修改FeignClient接口配置

为每个重复name的FeignClient补充contextId属性，示例如下：

// 第一个FeignClient接口：指定contextId为contractInfoClient@FeignClient(name="contract-management-service",contextId="contractInfoClient")publicinterfaceContractInfoFeignClient{@GetMapping("/contract/info/{id}")StringgetContractInfo(@PathVariable("id")Longid);}// 第二个FeignClient接口：指定contextId为contractAuditClient@FeignClient(name="contract-management-service",contextId="contractAuditClient")publicinterfaceContractAuditFeignClient{@PostMapping("/contract/audit")BooleanauditContract(@RequestBodyContractAuditDTOdto);}

验证结果

修改完成后，重新启动项目，控制台不再抛出Bean名称重复的异常，服务正常启动。通过访问FeignClient对应的接口，验证远程调用功能正常，无异常。