声明式HTTP接口生成代理时抛出IllegalStateException异常

可能原因及修复方案 #

1. 检查ClientInterface定义合法性 #

确保你的ClientInterface满足以下要求：

• 接口必须是public修饰
• @GetExchange注解的路径无语法错误，路径模板变量需与方法参数一一对应
• 方法返回类型为Spring支持的类型（如Mono<T>、Flux<T>，或直接返回响应体类型，具体取决于Spring版本）

示例正确接口定义：

public interface ClientInterface {
    @GetExchange("/api/target-endpoint")
    Mono<YourResponseType> getResource();
}

2. 显式指定类加载器构建代理 #

代理生成时的类加载上下文异常可能导致该问题，可在构建HttpServiceProxyFactory时显式指定类加载器：

@Configuration
public class ClientConfig {
    @Bean
    ClientInterface someClient() {
        WebClient webClient = WebClient.builder()
                .baseUrl("https://your-actual-base-url")
                .defaultHeader("Authorization", "Bearer token")
                .build();

        return HttpServiceProxyFactory
                .builderFor(WebClientAdapter.create(webClient))
                .classLoader(ClientInterface.class.getClassLoader()) // 指定接口类加载器
                .build()
                .createClient(ClientInterface.class);
    }
}

3. 排查Spring版本依赖冲突 #

若使用Spring Boot 3.x及以上版本，确保spring-boot-starter-webflux依赖版本统一，无跨版本依赖冲突。可执行Maven/Gradle的依赖清理命令，重新构建项目：

• Maven：mvn clean install
• Gradle：gradle clean build

4. 避免初始化阶段触发代理toString() #

异常触发时机通常是IDE调试工具、Bean预览功能在Bean初始化时调用了代理的toString()方法。可尝试：

• 关闭IDE的Bean自动预览功能
• 调试时避免直接查看代理对象的toString()输出，优先验证代理能否正常发起HTTP请求

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