自定义Quarkus扩展无法创建标准JAXRS接口的REST客户端

为啥会报这个错？ #

这个错误本质是Quarkus的Rest Client Reactive认不出你的MyContract接口是合法的REST客户端接口，主要跑不了这几个原因：

1. 扩展类加载器隔离搞的鬼 #

Quarkus自定义扩展的类加载器和应用本身的是分开的。你在扩展里直接用RestClientBuilder建客户端时，Rest Client的运行时代码可能读不到扩展接口上的javax.ws.rs注解——毕竟注解类在扩展的类加载器里，而检测注解的逻辑在应用的类加载器里，互相看不到。

2. 扩展没配必要的编译处理器 #

Quarkus的Rest Client Reactive靠编译时注解处理器生成代理类，要是你的自定义扩展没正确配置这个处理器，接口就会被判定为不合法。

3. 直接用RestClientBuilder不符合扩展规范 #

在Quarkus扩展里直接调用RestClientBuilder.newBuilder()不是正确姿势，Quarkus有专门给扩展用的API来创建客户端，能适配它的生命周期和类加载机制。

解决办法 #

办法1：调整扩展的依赖和类加载配置 #

• 在扩展的runtime模块的pom.xml里，把javax.ws.rs-api和quarkus-rest-client-reactive-jackson设为provided，确保依赖能正确传递：

<dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-rest-client-reactive-jackson</artifactId>
    <scope>provided</scope>
</dependency>
<dependency>
    <groupId>javax.ws.rs</groupId>
    <artifactId>javax.ws.rs-api</artifactId>
    <scope>provided</scope>
</dependency>

• 在扩展的deployment模块里，加上quarkus-rest-client-reactive-deployment依赖，让编译时处理器能扫到你的接口：

<dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-rest-client-reactive-deployment</artifactId>
    <version>2.16.4.Final</version>
    <scope>provided</scope>
</dependency>

办法2：用Quarkus扩展专用的方式创建客户端 #

别直接用RestClientBuilder，换成Quarkus提供的扩展API来管理客户端：

1. 在扩展的部署模块里，注册客户端配置，把接口、基础URI这些参数告诉Quarkus：

@BuildStep
void registerRestClient(BuildProducer<RestClientConfigBuildItem> producer) {
    RestClientConfigBuildItem config = new RestClientConfigBuildItem(MyContract.class.getName())
            .withBaseUri("你的默认基础URI")
            .withConnectTimeout(500)
            .withReadTimeout(5000);
    producer.produce(config);
}

2. 在扩展的运行时模块里，要么用依赖注入拿客户端，要么用Quarkus的RestClientBuilder实现：

// 方式1：依赖注入
@Inject
@RestClient
MyContract myContract;

// 方式2：用Quarkus的RestClientBuilder
return Arc.container().instance(RestClientBuilder.class).get()
        .baseUri(URI.create(target))
        .connectTimeout(500, TimeUnit.MILLISECONDS)
        .readTimeout(5000, TimeUnit.MILLISECONDS)
        .build(MyContract.class);

办法3：确保注解能被正确识别 #

• 给MyContract接口加上类级别的@Path，同时确认所有注解都是javax.ws.rs包下的：

import javax.ws.rs.POST;
import javax.ws.rs.Path;
import javax.ws.rs.PathParam;

@Path("/") // 加个类级别的@Path，让注解检测逻辑能抓到
public interface MyContract {

    @POST
    @Path("/v2/apps/{appId}")
    void register(@PathParam("appId") AppNameDTO var1);
}

• 检查AppNameDTO是不是在扩展的运行时模块里，有没有被正确打包，别因为DTO找不到间接导致注解检测失败。

验证步骤 #

1. 重新构建扩展，确保所有依赖和配置都改对了。
2. 在测试应用里引入扩展，启动看看还会不会报错。
3. 要是还不行，开Quarkus的调试日志（在application.properties里加quarkus.log.category."io.quarkus.rest.client.reactive".level=DEBUG），看看注解扫描的详细日志，就能找到具体哪出问题了。

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