Spring Boot 3.x中RestTemplate传Null Header报NPE如何解决？

问题原因 #

Spring Boot 3.x集成的OkHttp客户端（4.x+版本）对请求头参数做了严格的非空校验，okhttp3.Request$Builder.addHeader方法的value参数被标记为非null。当RestTemplate拦截器中调用HttpHeaders.add()传入null值时，这个null会直接传递给底层OkHttp的方法，触发NullPointerException。

修复方案 #

方案1：仅在值非null时添加请求头（推荐）

修改拦截器代码，对请求头的值做非null判断，只有当值存在时才添加对应的请求头，避免传入null：

public class RestTemplateConfig {

    @Bean
    @LoadBalanced
    public RestTemplate restTemplate(RestTemplateBuilder builder) {
        return builder.additionalInterceptors(createCustomHeadersInterceptor()).build();
    }

    public ClientHttpRequestInterceptor createCustomHeadersInterceptor() {
        return (request, body, execution) -> {
            UserContext userContext = ContextHolder.getCurrentContext().getUserContext();
            HttpHeaders headers = request.getHeaders();
            headers.setContentType(MediaType.APPLICATION_JSON);
            
            // 仅当GUID不为null时添加请求头
            String guid = userContext.getGuid();
            if (guid != null) {
                headers.add(HeaderKeys.GUID, guid);
            }
            
            // 对Username同样做非null校验，避免潜在问题
            String username = userContext.getUsername();
            if (username != null) {
                headers.add(HeaderKeys.USERNAME, username);
            }

            return execution.execute(request, body);
        };
    }
}

方案2：将Null转换为空字符串（需确认下游服务兼容）

如果业务逻辑要求必须传递该请求头（即使值为空），可以把null转换为空字符串""，但要确保下游服务能接受空值的请求头：

headers.add(HeaderKeys.GUID, userContext.getGuid() != null ? userContext.getGuid() : "");
headers.add(HeaderKeys.USERNAME, userContext.getUsername() != null ? userContext.getUsername() : "");

方案3：切换RestTemplate的底层客户端（不推荐）

如果不想修改代码逻辑，可以将RestTemplate的底层客户端切换为对null请求头更宽松的实现，比如Apache HttpClient或JDK原生的HttpURLConnection。但这种方式会引入额外依赖或改变默认行为，仅在特殊场景下使用。

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