背景

在微服务架构中，我们经常利用 HTTP 请求头来控制系统行为，比如实现灰度发布和流量控制。在 PIG 微服务框架中，我们通过重写 Spring Cloud LoadBalancer，根据请求 header 中的 version 字段动态匹配微服务实例，从而实现精准的流量路由控制。

然而，在 Spring Boot 3.4 版本升级后，用户们陆续反馈了一个棘手问题：当客户端请求中包含 version 请求头，同时 Controller 接口的 DTO 对象中也有同名的 version 字段（比如使用 MyBatis-Plus 乐观锁插件的场景），请求头中的 version 值会被自动绑定到 DTO 对象中，污染了乐观锁插件的判断条件，最终导致业务异常。

原因

Spring 6.2 的新特性与潜在风险

Spring Framework 6.2（被 Spring Boot 3.4 所依赖）引入了一项新功能：将 HTTP 请求头自动绑定到 Controller 方法的参数上。这项功能由ExtendedServletRequestDataBinder类实现，旨在增强数据绑定能力，但同时也带来了意想不到的兼容性问题。

在之前的 Spring 版本中，HTTP 头部不会自动绑定到模型属性，开发者需要显式使用@RequestHeader注解才能获取头部值。然而，Spring 6.2 改变了这一行为，任何 HTTP 头部现在都可能被自动绑定到同名的模型属性上。

PIG AI新版来袭：一站式Java AI解决方案，六大能力全面升级！

RFC9218 标准的影响

这一问题在使用符合 RFC9218 标准的 HTTP 头部时尤为明显。RFC9218 定义了Priority头部用于 HTTP 请求优先级管理，当系统中存在名为priority的表单字段时，来自头部的非预期值格式可能导致绑定异常或验证错误。

同样，在灰度发布场景中，我们常用的version头部也会与 DTO 对象中的 version 字段发生冲突，特别是当该字段被用作乐观锁控制时，这种冲突会直接导致业务逻辑错误。

官方响应

相关问题已在 GitHub 上被多次提出，如 #33961和 #34039，但 Spring 官方目前并未提供内置的解决方案，相关功能请求被标记为 "not planned"，这意味着框架层面短期内不会有内置的配置选项来禁用这种行为。

方案

既然官方暂时没有提供开关，我们需要自行解决这个问题。经过研究，我们发现了一个简洁有效的解决方案：自定义全局的ControllerAdvice来拦截和控制 HTTP 头部的绑定行为。

@ControllerAdvice
public class HeaderBindingConfiguration {

    /**
     * 初始化绑定器
     * <a href="https://github.com/spring-projects/spring-framework/issues/34039">
     * 处理 spring 6.2 严格遵循 RFC 导致 的请求头和请求参数冲突问题
     * </a>
     *
     * @param binder 绑定规则
     */
    @InitBinder
    public void initBinder(ExtendedServletRequestDataBinder binder) {
        binder.addHeaderPredicate(header -> false);
    }
}

这段代码通过@ControllerAdvice全局拦截所有 Controller 方法的数据绑定过程，并在@InitBinder方法中向ExtendedServletRequestDataBinder添加一个始终返回false的头部断言，从而完全禁用 HTTP 头部到模型属性的自动绑定。

除此之外，还有几种可选的应对策略：

1. 1. 避免字段名冲突：在设计 DTO 对象时，避免使用与常见 HTTP 头部同名的字段名，例如将priority改为taskPriority。
2. 2. 显式处理头部值：在控制器层显式获取和处理需要的头部值，而不依赖自动绑定。
3. 3. 自定义转换器：实现更复杂的Converter来控制特定头部的绑定行为。

总结

Spring Boot 3.4（通过 Spring Framework 6.2）引入的 HTTP 头部自动绑定功能，虽然提升了数据绑定能力，但也带来了潜在的兼容性问题，特别是在灰度发布和使用乐观锁等场景中。

通过本文提供的全局绑定拦截方案，我们可以完全禁用头部绑定功能，确保系统在升级后仍能保持预期行为。对于依赖微服务架构和灰度发布的企业来说，这一修复至关重要，可以避免业务逻辑错误和不必要的生产事故。