Spring Boot 3 OpenFeign客户端@Headers注解失效原因咨询

问题背景 #

使用Java 17 + Spring Boot 3.0.2创建Feign客户端，通过原生Feign的@Headers注解添加请求头后，请求返回401未授权状态码，请求头未被正确携带。代码示例如下：

@FeignClient(
        name = "test-client",
        url = "https://example-api-development.dev.company.ai"
)
public interface TestClient {
    @Headers({
            "Content-Type: application/json",
            "Accept: application/json",
            "Authorization: My-Auth-Key",
            "X-TenantID: test"
    })
    @PostMapping("/")
    String sendFiles();
}

已知可行替代方案：

• 通过@RequestHeader传递Map<String, String>类型的请求头参数；
• 创建FeignConfig类，使用RequestInterceptor添加请求头。

原因解析 #

核心原因是Spring Cloud Feign默认契约不支持原生Feign的@Headers注解：

• Spring Cloud Feign默认采用SpringMvcContract，该契约基于Spring MVC注解（如@PostMapping、@RequestHeader）解析请求，不会处理原生Feign的@Headers注解；
• 原生Feign的@Headers属于feign-core模块，仅在使用Feign原生契约（feign.Contract.Default）时才会被解析，但切换到原生契约后，Spring MVC注解（如@PostMapping）将失效，因为原生契约只识别Feign自带的注解（如@RequestLine）。

可选验证方案 #

若一定要使用@Headers注解，需配置Feign使用原生契约，同时替换Spring MVC注解为Feign原生注解：

@Configuration
public class FeignConfig {
    @Bean
    public Contract feignContract() {
        return new feign.Contract.Default();
    }
}

修改后的Feign客户端接口：

@FeignClient(
        name = "test-client",
        url = "https://example-api-development.dev.company.ai"
)
public interface TestClient {
    @Headers({
            "Content-Type: application/json",
            "Accept: application/json",
            "Authorization: My-Auth-Key",
            "X-TenantID: test"
    })
    @RequestLine("POST /")
    String sendFiles();
}

不过这种方式会失去Spring MVC注解的便利性，因此更推荐使用你提到的两种替代方案。

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