企业官网建设流程全解析

• 数据库
• 后端
• 缓存

Lettuce 是一个可扩展、线程安全的 Java Redis 客户端，同时支持同步（synchronous）、异步（asynchronous）与响应式（reactive）三种执行模型，底层基于 Netty 构建，并原生支持 Sentinel、Cluster、Pipelining、自动重连及 Redis 数据模型等高级特性。阅读本文后，你将能够完成 Lettuce 的依赖引入、连接创建与基础命令调用，掌握同步/异步/响应式三种 API 的核心用法与差异，并了解 Pub/Sub、RedisURI 连接配置以及如何从源码构建测试该项目。

项目概览：一个连接，三种执行模型

Lettuce 的核心设计理念是"可扩展且线程安全"。官方文档与 RedisClient 类源码 均明确指出：多个线程可以共享同一条连接，前提是这些线程避免阻塞型操作（如BLPOP）和事务型操作（如MULTI/EXEC）。

从 pom.xml 可以看到，本项目当前版本为7.9.0-SNAPSHOT，底层依赖 Netty4.2.17.Final与 Reactor3.8.7，这也是其能够同时提供阻塞式调用和响应式流（Reactive Streams）支持的基础。

Lettuce 支持的核心能力包括：

• 同步、异步、响应式三种 API：同一连接上通过sync()、async()、reactive()三个访问器切换执行模型，互不冲突；
• 高可用方案：Redis Sentinel、Redis Cluster；
• 连接安全与形态：SSL / TLS、Unix Domain Socket；
• 流式 API（Streaming API）：以回调方式逐条消费大数据量结果；
• 编解码器（Codecs）：自定义 key/value 的 UTF-8、二进制、JSON 等序列化表示；
• 动态命令接口（Command Interfaces）：以类型安全的方式声明式调用 Redis 命令；
• 原生传输（Native Transports）：Epoll、Kqueue 等；
• Redis 模块支持：RediSearch、RedisJSON、Redis Vector Sets、Bloom Filter、TDigest、TopK、Cuckoo Filter 等；
• 兼容性：兼容 Java 8+（以隐式自动模块方式提供，无 module descriptor）。

引入依赖：Maven 坐标与快照仓库

Lettuce 的正式版本发布在 Maven Central 仓库。以 Maven 为例，在pom.xml中添加如下依赖：

<dependency> <groupId>io.lettuce</groupId> <artifactId>lettuce-core</artifactId> <version>x.y.z</version> </dependency>

其中x.y.z替换为实际使用的发布版本号（例如当前源码对应的主线版本为7.9.0-SNAPSHOT）。

如果你希望使用下一个大版本的每日构建快照，可以使用 Sonatype 快照仓库并声明BUILD-SNAPSHOT版本：

<dependency> <groupId>io.lettuce</groupId> <artifactId>lettuce-core</artifactId> <version>x.y.z.BUILD-SNAPSHOT</version> </dependency> <repositories> <repository> <id>sonatype-snapshots</id> <name>Sonatype Snapshot Repository</name> <url>https://oss.sonatype.org/content/repositories/snapshots/</url> <snapshots> <enabled>true</enabled> </snapshots> </repository> </repositories>

注意：快照版本不稳定，仅建议在尝鲜新特性或参与上游开发时使用；生产环境请锁定 Maven Central 上的正式发布版本。

基础用法：同步 API 与连接生命周期

Lettuce 的最基本用法只需要三步：创建客户端、建立连接、获取命令 API 并执行命令。官方 README 给出了最精简的示例：

RedisClient client = RedisClient.create("redis://localhost"); StatefulRedisConnection<String, String> connection = client.connect(); RedisStringCommands sync = connection.sync(); String value = sync.get("key");

更完整的写法（含泛型与资源释放）可以参照仓库中的官方示例 ConnectToRedis.java：

// Syntax: redis://[password@]host[:port][/databaseNumber] // Syntax: redis://[username:password@]host[:port][/databaseNumber] RedisClient redisClient = RedisClient.create("redis://password@localhost:6379/0"); StatefulRedisConnection<String, String> connection = redisClient.connect(); // 通过 sync() 获取同步命令 API RedisStringCommands<String, String> sync = connection.sync(); String value = sync.get("key"); connection.close(); redisClient.shutdown();

命令命名约定

Lettuce 中每个 Redis 命令都由一个或多个方法实现，方法名与 Redis 命令的小写名称完全一致。对于带多个修饰符、会改变结果类型的复杂命令，其修饰符以驼峰形式拼接到命令名中，例如：

• zrangebyscore：按分数区间返回成员；
• zrangebyscoreWithScores：同样命令但附带分数返回。

也就是说，方法名本身既是命令名，也是结果形态的"说明书"。

连接是昂贵的资源

RedisClient 的类注释 特别提醒：RedisClient是一种昂贵资源，它持有 Netty 的EventLoopGroup（内部使用多个线程）。因此：

• 尽量复用同一个RedisClient实例；
• 或者在多个 client 实例之间共享一个ClientResources实例；
• 连接（StatefulRedisConnection）是线程安全的，可被多线程共享，详见 StatefulRedisConnection 接口。

自动重连机制

StatefulRedisConnection内部有一个ConnectionWatchdog监控每条连接，在close()被调用之前会自动重连；所有尚未完成的命令在重连成功后会（重新）发送。这正是 Lettuce 在故障场景下保持高可用的底层保障。

异步 API：RedisFuture 与 LettuceFutures

异步 API 通过connection.async()获得，每个命令立即返回一个RedisFuture<T>（继承自 JDK 的CompletionStage），可以组合、编排，而不会阻塞调用线程：

StatefulRedisConnection<String, String> connection = client.connect(); RedisStringAsyncCommands<String, String> async = connection.async(); RedisFuture<String> set = async.set("key", "value"); RedisFuture<String> get = async.get("key"); // 等待多个 future 全部完成 LettuceFutures.awaitAll(set, get) == true set.get() == "OK" get.get() == "value"

LettuceFutures 工具类

LettuceFutures是异步编程的配套工具，源码位于 LettuceFutures.java，提供两个关键方法：

• awaitAll(Duration timeout, Future<?>... futures)/awaitAll(long timeout, TimeUnit unit, Future<?>... futures)：等待所有 future 在超时前完成；若全部按时完成返回true，否则返回false。超时时不会取消命令。
• awaitOrCancel(RedisFuture<T> cmd, long timeout, TimeUnit unit)：等待单个命令完成，超时则取消命令。

仓库测试代码中也实际使用了该工具，例如 RediSearchIntegrationTests.java 中的批量等待：

assertThat(LettuceFutures.awaitAll(Duration.ofSeconds(60), futures.toArray(new RedisFuture[0]))).isTrue();

与Future.get()直接阻塞不同，异步 API 的价值在于：可以在等待 I/O 的同时做其他工作，或将多个命令的结果通过thenApply、thenCombine等CompletionStage操作组合起来。详细的异步编程指南见 异步 API 文档。

响应式 API：Mono 与 Flux

响应式 API 通过connection.reactive()获得，基于 Reactor 的Mono<T>（单个结果）与Flux<T>（流式多个结果）：

StatefulRedisConnection<String, String> connection = client.connect(); RedisStringReactiveCommands<String, String> reactive = connection.reactive(); Mono<String> set = reactive.set("key", "value"); Mono<String> get = reactive.get("key"); set.subscribe(); get.block() == "value"

响应式模型的核心特征是背压（backpressure）与订阅即执行：Mono<String> set的创建并不立即发送命令，只有subscribe()后命令才会真正执行。在真实应用中，更推荐使用map、flatMap、zip等操作符组合多个命令，并将最终结果交给上层订阅者消费。

需要留意的是，从 StatefulRedisConnection 的源码注释可知，reactive()访问器自 7.8 起已被标记为@Deprecated，计划在未来大版本中由commands(CommandsFactory)配合RedisReactiveCommands#factory()取代；在 Lettuce 7.x 中它仍可正常使用。响应式编程的完整讲解见 响应式 API 文档。

Pub/Sub 发布订阅

Lettuce 通过独立的 Pub/Sub 连接提供发布订阅能力。与普通连接不同，Pub/Sub 连接需要先注册监听器（Listener），再订阅频道，消息到达时由监听器回调：

RedisPubSubCommands<String, String> connection = client.connectPubSub().sync(); connection.getStatefulConnection().addListener(new RedisPubSubListener<String, String>() { // 实现 message / subscribed / unsubscribed 等回调 }); connection.subscribe("channel");

监听器回调接口

RedisPubSubListener 定义了以下核心回调：

• message(K channel, V message)：收到普通频道消息；
• message(K pattern, K channel, V message)：收到模式（pattern）匹配的消息；
• subscribed(K channel, long count)/psubscribed(K pattern, long count)：订阅成功（count 为当前订阅总数）；
• unsubscribed(K channel, long count)/punsubscribed(K pattern, long count)：退订成功；
• ssubscribed/sunsubscribed：自 6.4 起新增的 Shard Channel 订阅/退订回调（默认委托给subscribed/unsubscribed）。

订阅命令

RedisPubSubCommands 接口 提供的订阅命令与 Redis 一一对应：

连接配置：RedisURI 的创建与语法

无论是 Standalone、Sentinel 还是 Cluster，连接细节的统一载体都是RedisURI（源码见 RedisURI.java），它可以在其中携带数据库编号、客户端名、密码和超时等配置。RedisURI有三种创建方式：

// 1. 使用 URI 字符串 RedisURI.create("redis://localhost/"); // 2. 使用 Builder RedisURI.Builder.redis("localhost", 6379).withPassword("password").withDatabase(1).build(); // 3. 直接构造实例 RedisURI uri = new RedisURI("localhost", 6379, Duration.ofSeconds(60)); // 或 RedisURI uri = new RedisURI(); uri.setHost("localhost");

URI 语法

RedisURI支持 Standalone、SSL、Unix Domain Socket、Sentinel 等多种连接形态，其 URI 语法由源码注释明确定义：

Redis Standalone

redis://[[username:]password@]host[:port][/database] [?[timeout=timeout[d|h|m|s|ms|us|ns]][&database=database] [&clientName=clientName][&libraryName=libraryName][&libraryVersion=libraryVersion] [&verifyPeer=NONE|CA|FULL]]

Redis Standalone（SSL）：使用rediss://前缀，语法同上。

Redis Standalone（Unix Domain Socket）

redis-socket://[[username:]password@]path [?[timeout=...][&database=database][&clientName=clientName]...]

Redis Sentinel

redis-sentinel://[[username:]password@]host1[:port1][,host2[:port2]][,hostN[:portN]][/database] [?[timeout=...][&sentinelMasterId=sentinelMasterId][&database=database]...]

支持的 Scheme 一览

源码中同时保留了redis+ssl、redis+tls等别名 Scheme 常量。

超时单位

URI 中的timeout参数支持多种时间单位后缀：d（天）、h（小时）、m（分钟）、s（秒）、ms（毫秒）、us（微秒）、ns（纳秒）。

使用要点

• database 优先级：查询参数（?后）中的database优先级高于路径中的/database；
• Sentinel 认证：URI 中的密码只作用于数据节点；Sentinel 节点的认证需要对每个哨兵节点单独配置；
• 用户名：Redis 6 起才支持用户名；
• 库名与库版本：在 Redis 7.2+ 上会自动设置libraryName/libraryVersion，默认取 LettuceVersion 中的版本信息。

高级能力速览

Redis Cluster 与 Sentinel

• 集群场景使用RedisClusterClient（源码），同样提供同步/异步/响应式 API。集群客户端按命令首个 key 计算槽位并路由到对应节点，维护集群分区视图。仓库官方示例 ConnectToRedisCluster.java 展示了基本连接方式。需要说明的是，集群连接上不建议使用MULTI/EXEC/DISCARD等无 key 的事务命令——它们无法被分配到特定节点。
• Sentinel / 主从高可用场景参见 ha-sharding.md。

流式 API（Streaming API）

对于结果集巨大的命令（如SCAN、HGETALL的大批量数据），Lettuce 提供StreamingChannel回调接口，使数据以流的方式逐条输出，避免一次性在内存中堆积。详见 streaming-api.md。

Codecs 编解码器

通过client.connect(RedisCodec)可传入自定义编解码器，控制 key/value 在 UTF-8、二进制、JSON 等表示形式之间的转换。内置StringCodec、ByteArrayCodec、CompressionCodec、CipherCodec等，见 codec 包。Codecs 的接入方式详见 integration-extension.md。

动态命令接口（Command Interfaces）

除 190+ 条内置命令外，Lettuce 还允许你通过声明接口来自定义类型安全的命令调用，减少样板代码。核心是Commands标记接口，例如：

public interface KeyCommands extends Commands { String get(String key); String set(String key, String value); String set(String key, byte[] value); }

接口中方法名即命令名、参数即命令参数、返回类型即结果形态。完整的声明式调用机制见 redis-command-interfaces.md。

原生传输与 Redis 模块

• Epoll / Kqueue 原生传输可在 Linux/macOS 上获得更好的性能，见 native-transports.md；
• 模块支持：RediSearch（redis-search.md）、RedisJSON（redis-json.md）、Vector Sets（vector-sets.md）等，相应命令构建器位于 search、json、vector 包下。

从源码构建与测试

Lettuce 使用 Apache Maven 构建。其测试需要多个运行中的 Redis 实例，实例的启停通过仓库根目录的 Makefile 统一编排（底层基于 Docker Compose，测试环境定义见src/test/resources/docker-env/）。

当前源码默认测试目标是 Redis8.10，同时支持8.12、8.8、8.6、8.4、8.2、8.0、7.4、7.2等版本（见 Makefile）。构建流程如下：

git clone https://gitcode.com/gh_mirrors/le/lettuce-core cd lettuce-core make start # 启动测试用 Redis 环境 make test # 运行构建与测试（等价于 mvn -DskipITs=false clean compile verify）

常用命令：

• make test：运行完整构建与测试；
• make start：手动启动 Redis 测试环境；
• make stop：手动停止 Redis 测试环境；
• make clean：清理构建产物。

如果你已经有本地 Redis，也可以直接使用 Maven 运行单元测试（集成测试默认通过skipITs跳过，见 pom.xml）。

结语

Lettuce 以"一个线程安全连接承载三种执行模型"为核心设计，覆盖了从单机、主从、哨兵到集群的完整 Redis 部署形态，并提供 Codec、流式 API、动态命令接口、模块命令等丰富的扩展机制。本文所述的入门路径——引入依赖、创建连接、选择sync()/async()/reactive()、按命令命名约定调用——即可支撑大部分日常开发场景。深入阅读可继续参考仓库中的 connecting-redis.md、async-api.md、reactive-api.md 与 faq.md 等文档。

• 数据库
• 后端
• 缓存