Quarkus响应式应用中集成Keycloak管理客户端的阻塞问题与解决方案

本教程探讨在quarkus响应式应用程序中使用`quarkus-keycloak-admin-client-reactive`扩展时，`serverrequestfilter`中遇到的`blockingnotallowedexception`问题。尽管扩展名暗示响应式，但底层keycloak客户端仍执行阻塞操作。文章将详细解释此问题，并提供一个基于vert.x `executeblocking`的有效解决方案，确保在响应式上下文中安全地执行阻塞调用，从而维护应用的响应性。

理解Quarkus响应式上下文与Keycloak管理客户端

Quarkus以其对响应式编程模型的强大支持而闻名，尤其是在使用quarkus-resteasy-reactive等扩展时。在这种模型下，所有I/O操作都应是非阻塞的，以最大化资源利用率和吞吐量。然而，当我们需要与外部服务（如Keycloak）进行交互时，尤其是在使用其管理API时，可能会遇到挑战。

quarkus-keycloak-admin-client-reactive扩展旨在简化Quarkus应用与Keycloak管理API的集成。它允许开发者通过注入Keycloak客户端实例来执行管理操作。理想情况下，这个客户端在响应式上下文中也应该是非阻塞的。

遇到的问题：BlockingNotAllowedException

在响应式Quarkus应用中，如果尝试在非阻塞线程（如Vert.x事件循环线程）上执行阻塞操作，Quarkus会抛出BlockingNotAllowedException。这通常发生在数据库访问、外部HTTP调用或文件I/O等操作未能以响应式方式实现时。

考虑以下在ServerRequestFilter中尝试使用注入的Keycloak客户端查询用户属性的场景：

import io.quarkus.security.identity.SecurityIdentity;
import io.smallrye.mutiny.Uni;
import jakarta.inject.Inject;
import jakarta.ws.rs.container.ContainerRequestContext;
import jakarta.ws.rs.ext.Provider;
import jakarta.ws.rs.core.Response;
import org.jboss.resteasy.reactive.server.ServerRequestFilter;
import org.keycloak.admin.client.Keycloak;

@Provider
public class KeycloakAttributeFilter {

    @Inject
    Keycloak keycloak; // 注入Keycloak管理客户端

    @ServerRequestFilter
    public Uni<Response> filter(ContainerRequestContext requestContext) {
        // 假设从请求上下文获取到用户名
        String username = "user-from-context"; 

        return Uni.createFrom().item(() -> 
                keycloak.realm("my-realm")
                        .users()
                        .search(username)
                        .stream()
                        .findFirst()
                        .orElseThrow(() -> new RuntimeException("User not found"))
                        .firstAttribute("the-attribute"))
                .map(attr -> {
                    if ("some-value".equals(attr)) {
                        return null; // 继续处理请求
                    }
                    return Response.status(403).build(); // 拒绝请求
                });
    }
}

尽管我们使用了Mutiny的Uni来封装操作，并且扩展名称中带有“reactive”，但在执行keycloak.realm(...).users().search(...)等方法时，仍然会抛出BlockingNotAllowedException。这是因为keycloak-admin-client库本身是基于传统的ResteasyClient构建的，其内部的HTTP调用是阻塞的，而非Quarkus响应式ResteasyReactiveClient。直接在响应式上下文中调用这些阻塞方法会导致线程阻塞，从而触发异常。

尝试使用Uni.runSubscriptionOn(Infrastructure.getDefaultWorkerPool())也无法解决此问题，因为它只是将Uni的订阅操作调度到不同的线程池，但实际的阻塞调用仍然会在这个线程池中执行，这并不是Quarkus响应式模型所期望的。

悟空CRM v 0.5.5

悟空CRM是一种客户关系管理系统软件.它适应Windows、linux等多种操作系统，支持Apache、Nginx、IIs多种服务器软件。悟空CRM致力于为促进中小企业的发展做出更好更实用的软件，采用免费开源的方式，分享技术与经验。 悟空CRM 0.5.5 更新日志：2017-04-21 1.修复了几处安全隐患； 2.解决了任务.日程描述显示问题； 3.自定义字段添加时自动生成字段名

284

查看详情

解决方案：利用Vert.x executeBlocking

解决此问题的核心在于，我们需要将这些阻塞的Keycloak管理客户端调用封装在一个允许阻塞的上下文中执行，同时又不中断整个应用程序的响应式流。Vert.x提供了executeBlocking方法，它正是为此目的而设计的。executeBlocking会将提供的阻塞任务提交给Vert.x的内部工作线程池执行，从而避免阻塞事件循环线程。

要使用executeBlocking，首先需要注入Vert.x实例：

import io.vertx.mutiny.core.Vertx;
import io.smallrye.mutiny.Uni;
import jakarta.inject.Inject;
import jakarta.ws.rs.container.ContainerRequestContext;
import jakarta.ws.rs.ext.Provider;
import jakarta.ws.rs.core.Response;
import org.jboss.resteasy.reactive.server.ServerRequestFilter;
import org.keycloak.admin.client.Keycloak;

@Provider
public class KeycloakAttributeFilter {

    @Inject
    Keycloak keycloak;
    @Inject
    Vertx vertx; // 注入Vert.x实例

    @ServerRequestFilter
    public Uni<Response> filter(ContainerRequestContext requestContext) {
        String username = "user-from-context"; // 假设从请求上下文获取

        return vertx.getOrCreateContext().executeBlocking(
            Uni.createFrom().emitter(emitter -> {
                try {
                    // 在executeBlocking内部执行阻塞的Keycloak调用
                    var attr = keycloak.realm("my-realm")
                            .users()
                            .search(username)
                            .stream()
                            .findFirst()
                            .orElseThrow(() -> new RuntimeException("User not found"))
                            .firstAttribute("the-attribute");

                    if ("some-value".equals(attr)) {
                        emitter.complete(null); // 成功，继续请求处理
                    } else {
                        emitter.complete(Response.status(403).build()); // 失败，返回403
                    }
                } catch (Exception e) {
                    emitter.fail(e); // 捕获异常并传递
                }
            }));
    }
}

代码解析：

1. @Inject Vertx vertx;: 注入Vert.x的Mutiny版本实例，它提供了executeBlocking方法。
2. vertx.getOrCreateContext().executeBlocking(...): 这是核心。它接收一个Uni作为参数，该Uni的任务将在Vert.x的工作线程池中执行。这意味着其中的代码可以安全地执行阻塞操作，而不会影响主事件循环线程。
3. Uni.createFrom().emitter(emitter -> { ... });: 在executeBlocking内部，我们使用Uni.createFrom().emitter来手动控制Uni的完成或失败。
   • 在emitter的回调中，我们执行了原始的、阻塞的Keycloak客户端调用。
   • 根据Keycloak调用的结果，通过emitter.complete(null)（表示成功，过滤器允许请求继续）或emitter.complete(Response.status(403).build())（表示失败，返回403响应）来完成Uni。
   • try-catch块用于捕获Keycloak调用可能抛出的异常，并通过emitter.fail(e)将异常传递给响应式流。

通过这种方式，我们成功地将阻塞的Keycloak调用隔离到Vert.x的工作线程中，从而避免了BlockingNotAllowedException，并维护了Quarkus应用程序的整体响应性。

注意事项与最佳实践

• 适度使用executeBlocking: executeBlocking是处理阻塞操作的有效手段，但不应滥用。如果存在真正的响应式客户端或库，应优先使用它们。executeBlocking会占用Vert.x的工作线程，过多的阻塞操作会耗尽工作线程池，影响系统吞吐量。
• 错误处理: 在executeBlocking内部，务必进行适当的错误处理。使用try-catch块捕获可能发生的异常，并通过emitter.fail(e)将它们传播到响应式流中，以便后续的onFailure操作能够处理。
• 上下文传递: 如果Keycloak调用依赖于请求上下文中的某些信息（例如安全主体、请求头等），请确保这些信息在executeBlocking的任务内部仍然可用。通常，可以在调用executeBlocking之前从requestContext中提取所需信息，并将其作为局部变量传递到Lambda表达式中。
• 性能考量: 尽管executeBlocking解决了阻塞问题，但阻塞操作本身仍然需要时间。如果Keycloak管理API调用频繁且耗时，可能会成为性能瓶颈。在这种情况下，考虑对Keycloak响应进行缓存，或者重新评估业务流程以减少对管理API的直接、同步依赖。

总结

在Quarkus响应式应用中集成keycloak-admin-client时，由于其底层是阻塞的，直接调用会导致BlockingNotAllowedException。通过巧妙地利用Vert.x的executeBlocking方法，我们可以将这些阻塞操作安全地转移到专门的工作线程池中执行，从而维护应用程序的响应式特性。这种模式是处理现有阻塞库在响应式环境中集成的有效策略，但开发者应始终关注其对性能和资源利用的影响，并优先选择原生响应式解决方案。

以上就是Quarkus响应式应用中集成Keycloak管理客户端的阻塞问题与解决方案的详细内容，更多请关注php中文网其它相关文章！