企业官网建设流程全解析

Redisson 四种 API 模型全解：同步、异步、Reactive 与 RxJava3 实战指南

【免费下载链接】redissonRedisson: Valkey & Redis Java Client and Real-Time Data Platform. Sync/Async/RxJava/Reactive API. Over 50 Valkey and Redis based Java objects and services: Set, Multimap, SortedSet, Map, List, Queue, Deque, Semaphore, Lock, AtomicLong, Map Reduce, Bloom filter, Spring, Tomcat, Scheduler, JCache API, Hibernate, RPC, local cache..项目地址: https://gitcode.com/GitHub_Trending/re/redisson

Redisson 为同一套分布式对象与 Redis/Valkey 数据服务提供了四种并存的编程模型：同步（Synchronous）、异步（Asynchronous）、Reactive（基于 Project Reactor）与 RxJava3。本文以 docs/api-models.md 为核心骨架，结合仓库源码讲解四种模型的入口接口、返回值类型、回调与订阅写法及线程安全注意事项，帮助你在命令式、CompletableFuture 风格与响应式流三种技术栈之间自由切换，而无须重写业务逻辑。

一、四种 API 模型总览

Redisson 的分布式对象（AtomicLong、Map、Lock、Queue、Set 等 50 余种数据结构与服务）几乎都以四种形态暴露给开发者：

四种模型共享同一套分布式语义与底层连接管理：同步与异步入口都是 RedissonClient，Reactive 与 RxJava 则分别通过RedissonClient.reactive()与RedissonClient.rxJava()两个工厂方法获得。

二、同步与异步 API

2.1 Redisson 实例是线程安全的

Redisson 实例被设计为完全线程安全，同一个RedissonClient可以被多个线程并发共享，用于获取任意数量的分布式对象。因此你只需在应用启动时创建一次客户端，所有业务线程共用即可，无需按线程创建实例，也无需额外的同步措施。

2.2 同步接口继承异步接口

同步与异步 API 都通过 RedissonClient 接口访问。Redisson 的大部分对象同时实现了同步接口，而该同步接口本身继承自对应的异步接口，因此每个同步方法都天然带有一个xxxAsync()的异步孪生方法。

以RAtomicLong为例，其接口声明见 RAtomicLong.java：

public interface RAtomicLong extends RExpirable, RAtomicLongAsync { long get(); long incrementAndGet(); boolean compareAndSet(long expect, long update); // ... }

而 RAtomicLongAsync.java 定义了与同步方法一一对应的异步版本，返回值统一包装为RFuture：

public interface RAtomicLongAsync extends RExpirableAsync { RFuture<Long> getAsync(); RFuture<Long> incrementAndGetAsync(); RFuture<Boolean> compareAndSetAsync(long expect, long update); // ... }

从源码结构可以看到，同步与异步方法的差异仅在于：同步方法直接返回结果并阻塞当前线程，异步方法返回RFuture且不阻塞。文档中的对照示例：

// RAtomicLong extends RAtomicLongAsync RAtomicLong obj = client.getAtomicLong("myLong"); obj.compareAndSet(1, 401); RAtomicLongAsync objAsync = client.getAtomicLong("myLong"); RFuture<Boolean> future = objAsync.compareAndSetAsync(1, 401);

2.3 RFuture 是 CompletionStage 的扩展

异步方法返回的 RFuture 接口同时继承了java.util.concurrent.Future<V>与java.util.concurrent.CompletionStage<V>：

public interface RFuture<V> extends java.util.concurrent.Future<V>, CompletionStage<V> {

因此它既可以用Future的方式阻塞get()，也可以使用CompletionStage提供的一整套声明式回调方法。文档给出的两种典型回调写法：

future.whenComplete((res, exception) -> { // handle both result and exception }); // or future.thenAccept(res -> { // handle result }).exceptionally(exception -> { // handle exception });

其中whenComplete同时接收结果与异常，适合统一的收尾逻辑；thenAccept只处理成功结果，配合exceptionally单独分流异常处理，风格更贴近CompletableFuture。

2.4 重要：不要在 RFuture 监听器中调用阻塞方法

文档中特别给出了如下警告：

Avoid using blocking methods in RFuture listeners. Listeners are executed by netty threads, and delays in them may cause errors in Redis or Valkey request/response processing.

原因在于监听器回调运行在 Netty 事件循环线程上。如果在回调中直接执行阻塞方法（如future.get()、Thread.sleep()、同步 JDBC 查询等），会阻塞 Netty 线程，进而拖慢乃至中断 Redis/Valkey 的请求与响应处理——这是 Redisson 高性能路径上的一个典型陷阱。

正确的做法是使用xxxAsync变体，把回调调度到独立的Executor上执行：

future.whenCompleteAsync((res, exception) -> { // handle both result and exception }, executor); // or future.thenAcceptAsync(res -> { // handle result }, executor).exceptionallyAsync(exception -> { // handle exception }, executor);

带Async后缀的方法（whenCompleteAsync、thenAcceptAsync、exceptionallyAsync）接受一个Executor参数，将阻塞逻辑从 Netty 线程池移出，既保持回调链式风格，又不影响请求处理吞吐。

三、Reactive API（基于 Project Reactor）

3.1 入口与获取方式

Reactive API 通过 RedissonReactiveClient 接口访问，其实现基于 Project Reactor。在 Redisson.java 中，它由同步客户端工厂方法生成：

@Override public RedissonReactiveClient reactive() { return new RedissonReactive(connectionManager, evictionScheduler, writeBehindService); }

即先创建同步RedissonClient，再调用redissonClient.reactive()得到 RedissonReactive 实例，该实例复用同一套连接管理器（connectionManager）、驱逐调度器与写后置服务。

3.2 使用示例

文档给出的 Reactive 用法示例：

RedissonReactiveClient client = redissonClient.reactive(); RAtomicLongReactive atomicLong = client.getAtomicLong("myLong"); Mono<Boolean> cs = atomicLong.compareAndSet(10, 91); Mono<Long> get = atomicLong.get(); get.doOnSuccess(res -> { // ... }).subscribe();

Reactive 模型的关键特征：

• 所有方法返回Mono<T>（单值）或Flux<T>（多值）等 Reactor 类型；
• 方法调用本身不触发执行，必须通过.subscribe()等操作符真正订阅后才会向 Redis/Valkey 发送命令；
• 支持doOnSuccess、map、flatMap、zip、retry等完整的 Reactor 操作符，便于在响应式链路中编排多个分布式操作。

对应对象的接口为 RAtomicLongReactive（继承RExpirableReactive），其原子操作均返回Mono类型。

四、RxJava API（基于 RxJava3）

4.1 入口与获取方式

RxJava API 通过RedissonRxClient接口访问，实现基于 RxJava3。同样在 Redisson.java 中提供工厂方法：

@Override public RedissonRxClient rxJava() { return new RedissonRx(connectionManager, evictionScheduler, writeBehindService); }

生成的 RedissonRx 与 Reactive 实现共享相同的底层组件，只是对外暴露 RxJava3 类型。

4.2 使用示例

文档给出的 RxJava 用法示例：

RedissonRxClient client = redissonClient.rxJava(); RAtomicLongRx atomicLong = client.getAtomicLong("myLong"); Single<Boolean> cs = atomicLong.compareAndSet(10, 91); Single<Long> get = atomicLong.get(); get.doOnSuccess(res -> { // ... }).subscribe();

RxJava 模型的关键特征：

• 单值操作返回Single<T>，可能无值的操作返回Maybe<T>，多值流返回Flowable<T>/Observable<T>；
• 与 Reactor 类似，需要.subscribe()后命令才会真正执行；
• 支持doOnSuccess、map、flatMap、zipWith、retryWhen等 RxJava3 操作符。

对应对象的接口为 RAtomicLongRx（继承RExpirableRx）。

五、四种模型的选型建议

无论选择哪一种，底层都复用同一套连接管理与分布式对象实现，四种模型之间的分布式语义（原子性、过期时间、锁行为等）完全一致，可根据团队技术栈随时切换而无需担心行为差异。需要注意的共性是：回调与订阅线程上的阻塞必须谨慎处理——异步模型的监听器运行在 Netty 线程上，应避免在其中执行阻塞操作；Reactive 与 RxJava 模型则要留意订阅生命周期管理与背压。

六、相关文档导航

• 开始使用 Redisson（客户端创建与配置）
• 配置详解（连接、编解码、线程池等）
• 数据序列化与编解码器
• 分布式锁与同步器
• 流水线（Pipelining）批处理

以上文档覆盖客户端的启动配置、底层连接模型与各类分布式对象的详细用法，与本文的四种 API 模型配合使用，即可构建完整的 Redisson 应用。

【免费下载链接】redissonRedisson: Valkey & Redis Java Client and Real-Time Data Platform. Sync/Async/RxJava/Reactive API. Over 50 Valkey and Redis based Java objects and services: Set, Multimap, SortedSet, Map, List, Queue, Deque, Semaphore, Lock, AtomicLong, Map Reduce, Bloom filter, Spring, Tomcat, Scheduler, JCache API, Hibernate, RPC, local cache..项目地址: https://gitcode.com/GitHub_Trending/re/redisson