2.1 概述
Quarkus 是一个基于 Java 的框架，主要用于构建 Jakarta EE 和 MicroProfile 应用，尤其擅长开发 REST 服务。为简化 REST 服务访问，Quarkus 提供了 REST 客户端，允许通过类型安全的代理对象调用 REST 服务。
⚠️ 当 REST 资源受保护时，必须进行身份认证。在 REST/HTTP 中通常通过发送包含凭据的 HTTP 头实现。但 REST 客户端 API 本身并未提供直接设置安全信息或 HTTP 头的方法。
本教程将介绍如何通过 Quarkus（MicroProfile）REST 客户端访问受保护的 REST 服务。Quarkus 为基本认证提供了简单解决方案：@ClientBasicAuth 注解。
2.2 搭建受保护的服务
首先用 Quarkus 搭建一个受保护的服务。
考虑以下 REST 服务接口：
@Path("/hello")
@RequestScoped
public interface MyService {
@GET
@Produces(TEXT_PLAIN)
String hello();
}
实现 MyService：
public class MyServiceImpl implements MyService {
@Override
@RolesAllowed("admin")
public String hello() {
return "Hello from Quarkus REST";
}
}
❌ 注意：@RolesAllowed 注解必须放在实现类而非接口上——该注解不会从接口继承。不过这也有合理性：角色名称可视为内部细节，不应暴露。
启用安全后，Quarkus 默认激活基本认证机制，但需提供 身份存储（Quarkus 中称 IdentityProvider）。通过在 classpath 添加依赖实现，例如在 pom.xml 中加入：
<dependency>
<groupId>io.quarkus</groupId>
<artifactId>quarkus-elytron-security-properties-file</artifactId>
</dependency>
✅ 该依赖会激活安全机制（通过其传递依赖 io.quarkus:quarkus-elytron-security），并在 classpath 中提供身份存储。通过 application.properties 添加用户配置：
quarkus.http.auth.basic=true
quarkus.security.users.embedded.enabled=true
quarkus.security.users.embedded.plain-text=true
quarkus.security.users.embedded.users.john=secret1
quarkus.security.users.embedded.roles.john=admin,user
2.3 RestClientBuilder 与 @ClientBasicAuth
现在看如何通过 RestClientBuilder 调用受保护服务。
以下是无凭据的类型安全调用：
MyService myService = RestClientBuilder.newBuilder()
.baseUri(URI.create("http://localhost:8081"))
.build(MyService.class);
myService.hello();
这段代码会创建 REST 服务代理，调用方式如同本地方法。
提供凭据的常规方案有两种：
- 用
@ClientHeaderParam注解原始接口 - 继承接口并在子接口添加注解
两种方式都需通过注解指定的回调方法手动生成正确头信息。对于基本认证，更推荐使用 @ClientBasicAuth 注解。
使用 @ClientBasicAuth 提供用户名/密码时，需为特定用户创建专用接口类型。用户名和密码是静态的，每个类型对应固定用户——适合使用静态定义的系统账户访问远程服务的场景。
创建专用接口：
@ClientBasicAuth(username = "john", password = "secret1")
public interface MyServiceJohnRightCredentials extends MyService {
}
调用时改用带凭据的接口类型：
MyService myService = RestClientBuilder.newBuilder()
.baseUri(URI.create("http://localhost:8081"))
.build(MyServiceJohnRightCredentials.class);
myService.hello();
✅ 上述代码中，Quarkus RestClientBuilder 会自动生成基本认证所需的 HTTP 头。实际项目中，可通过 ${john.password} 等表达式引用配置属性。
2.4 总结
本文介绍了：
- 如何搭建受基本认证保护的 REST 服务
- 如何使用
@ClientBasicAuth注解访问这类服务
关键点：
✅ @ClientBasicAuth 无需修改原始 REST 接口
❌ 但仅支持静态预定义用户，不适用于动态凭据场景
所有代码示例可在 GitHub 获取。