Spring WebFlux响应式HttpServiceProxy类型转换失败问题求助

问题根源 #

你遇到的核心问题是：Spring声明式HTTP客户端（HttpServiceProxyFactory）的类型转换体系独立于WebFlux全局FormatterRegistry。你在WebfluxConfig中注册的转换器仅会被WebFlux的请求处理链路使用，并不会被HttpServiceProxyFactory复用，后者有自己独立的转换服务配置。错误提示中的@org.springframework.web.bind.annotation.PathVariable标识，说明Spring在为声明式客户端的参数转换寻找带注解限定的适配转换器。

解决方案 #

1. 将转换器定义为可复用的Spring Bean #

先把CUID转换器注册为Spring Bean，方便后续在多个场景注入使用：

import io.github.thibaultmeyer.cuid.CUID
import org.springframework.core.convert.converter.Converter
import org.springframework.data.convert.ReadingConverter
import org.springframework.data.convert.WritingConverter
import org.springframework.stereotype.Component

@ReadingConverter
@Component
class CUIDReadingConverter : Converter<String, CUID> {
    override fun convert(source: String): CUID? = CUID.fromString(source)
}

@WritingConverter
@Component
class CUIDWritingConverter : Converter<CUID, String> {
    override fun convert(source: CUID): String? = source.toString()
}

2. 为声明式客户端创建专属ConversionService #

构建包含CUID转换器的自定义转换服务，供HttpServiceProxyFactory使用：

import org.springframework.context.annotation.Bean
import org.springframework.context.annotation.Configuration
import org.springframework.core.convert.support.DefaultConversionService

@Configuration
class HttpClientConversionConfig {

    @Bean
    fun httpClientConversionService(
        cuidReadingConverter: CUIDReadingConverter,
        cuidWritingConverter: CUIDWritingConverter
    ): DefaultConversionService {
        val conversionService = DefaultConversionService()
        conversionService.addConverter(cuidReadingConverter)
        conversionService.addConverter(cuidWritingConverter)
        return conversionService
    }
}

3. 修改客户端代理构建逻辑 #

在创建HttpServiceProxyFactory时，注入自定义的转换服务：

import org.springframework.core.convert.support.DefaultConversionService
import org.springframework.web.reactive.function.client.ExchangeFilterFunction
import org.springframework.web.reactive.function.client.WebClient
import org.springframework.web.reactive.function.client.support.WebClientAdapter
import org.springframework.web.service.invoker.HttpServiceProxyFactory

object ServiceClientFactory {

    private fun contentServiceAdapter(
        builder: WebClient.Builder,
        vararg filters: ExchangeFilterFunction,
    ): WebClientAdapter {
        val webClient = builder.baseUrl("http://content-service").filters { filters.toList() }.build()
        return WebClientAdapter.create(webClient)
    }

    fun <T> createContentServiceClient(
        builder: WebClient.Builder,
        serviceType: Class<T>,
        conversionService: DefaultConversionService,
        vararg filters: ExchangeFilterFunction,
    ): T {
        val adapter = contentServiceAdapter(builder, *filters)
        return HttpServiceProxyFactory.builderFor(adapter)
            .conversionService(conversionService) // 关键：绑定自定义转换服务
            .build()
            .createClient<T>(serviceType)
    }
}

4. 更新SubscriptionService Bean注册 #

在Bean定义中注入自定义的转换服务：

import org.springframework.context.annotation.Bean
import org.springframework.core.convert.support.DefaultConversionService
import org.springframework.web.reactive.function.client.WebClient
import org.springframework.cloud.client.loadbalancer.reactive.ReactorLoadBalancerExchangeFilterFunction

@Bean
fun subscriptionService(
    builder: WebClient.Builder,
    lbFunction: ReactorLoadBalancerExchangeFilterFunction,
    httpClientConversionService: DefaultConversionService
): SubscriptionService =
    ServiceClientFactory.createContentServiceClient(
        builder,
        SubscriptionService::class.java,
        httpClientConversionService,
        lbFunction
    )

补充说明 #

• 若不需要WebFlux全局转换器支持，可移除WebfluxConfig中的addFormatters逻辑，避免冗余配置
• 声明式HTTP客户端的转换服务会自动识别注解限定的参数转换，只要转换器实现正确，即可处理@PathVariable、@RequestParam等注解标记的参数

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