1. 为什么需要客户端从协议到 Jedis 的定位Redis 服务端本身只认一种东西RESP 协议REdis Serialization Protocol。它是一套基于 TCP 的文本协议客户端把命令按特定格式发过去服务端按格式回。你可以用telnet或者nc直接连上去手敲命令比如发一个*3\r\n$3\r\nSET\r\n$3\r\nkey\r\n$5\r\nvalue\r\n服务端就回你一个OK。手敲一次两次还行真要在业务代码里用没人会去拼这种字符串。所以就有了客户端库。客户端库干的事说白了就三件把命令封装成方法调用、管理连接、把返回值转成编程语言里的对象。Java 生态里Jedis 是最早一批、也是最直白的一个。它的设计哲学是薄封装——你调jedis.set(k,v)它底层就是发一条 SET 命令几乎不做额外抽象。这种直白带来的好处是学习成本极低、行为可预测代价是连接管理、线程安全这些事得你自己操心。这篇内容适合谁看如果你刚开始接触 Redis想搞清楚Java 代码到底怎么跟 Redis 说话或者你已经在用 Spring Data Redis 但想弄明白底层到底发生了什么那 Jedis 是最好的切入点。它足够简单简单到你能一眼看穿整个调用链路。我会从依赖引入、连接建立、基本命令、连接池、到常见坑一步步拆开讲每个环节都告诉你为什么这么做。需要先明确一个前提Jedis 实例不是线程安全的。这一点跟很多人的直觉相反——很多人以为客户端对象可以随便共享。实际上一个Jedis对象内部持有一个 socket 连接多个线程同时往同一个 socket 上写数据响应就会串包。所以生产环境里几乎不会直接用裸Jedis而是用JedisPool。这个认知是后面所有内容的基础先记住。2. 环境准备与依赖引入的取舍2.1 版本选择为什么建议用 4.x 而不是 3.xJedis 的版本迭代里3.x 到 4.x 是个分水岭。3.x 时代连接池依赖的是 Apache Commons Pool 2而 4.x 换成了自己维护的一套池化实现同时把很多过时 API 清理掉了。如果你在搜索引擎里翻到老教程看到JedisPoolConfig里配置testOnBorrow、maxActive这些参数那是 3.x 的写法4.x 里maxActive改成了maxTotaltestOnBorrow的语义也有调整。我的建议是新项目直接上 4.x 的最新稳定版。原因有两个。第一4.x 对 Redis 6/7 的新特性支持更完整比如 ACL 用户认证、RESP3 协议。第二3.x 已经进入维护模式遇到问题社区响应会慢。当然如果你维护的是老系统锁死在 3.x 上那也没必要强行升级因为 4.x 的 API 有不兼容变更升级成本得评估。Maven 依赖大概长这样dependency groupIdredis.clients/groupId artifactIdjedis/artifactId version4.4.6/version /dependency如果你用 Gradleimplementation redis.clients:jedis:4.4.6注意Jedis 4.x 需要 JDK 8 及以上。如果你还在 JDK 7 上跑只能用 3.x。另外4.x 内部用了java.util.function的一些接口JDK 8 是硬门槛。2.2 要不要引 commons-pool2这是个高频疑问。答案是Jedis 4.x 已经把它作为传递依赖带进来了你不需要手动声明。但如果你在依赖树里看到版本冲突比如项目里别的库引了老版本 commons-pool2那就得用dependencyManagement或者exclusions把它统一到 Jedis 要求的版本。我踩过一次坑某项目里有个老连接池组件锁了 commons-pool2 2.4结果 Jedis 4.x 跑起来报NoSuchMethodError排查了半天才发现是版本打架。用mvn dependency:tree一看就清楚了。3. 从裸连接到连接池一次完整的实操3.1 最朴素的连接方式及其问题先看最原始的写法理解它然后抛弃它import redis.clients.jedis.Jedis; public class RawConnectionDemo { public static void main(String[] args) { // 建立连接默认连 localhost:6379 Jedis jedis new Jedis(127.0.0.1, 6379); // 如果有密码 jedis.auth(yourpassword); // 发命令 jedis.set(name, jedis-demo); String value jedis.get(name); System.out.println(value); // 关闭连接 jedis.close(); } }这段代码能跑但问题一大堆。第一每次操作都新建 TCP 连接TCP 三次握手 Redis 认证的开销全摊在业务请求上QPS 高的时候连接建立本身就成了瓶颈。第二如果中间抛异常jedis.close()执行不到连接就泄漏了。第三多线程环境下这个jedis对象根本不能共享。我实测过单机 Redis用裸连接做 1 万次 SET耗时大概是用连接池的 3 到 5 倍。这个差距在压测里非常明显。所以裸连接只适合写个 demo 验证连通性生产代码里出现裸new Jedis()基本就是事故隐患。3.2 连接池的正确打开方式连接池的核心思想是复用预先建好一批连接放在池子里用的时候借用完还。这样连接建立的开销只在初始化时付一次。import redis.clients.jedis.JedisPool; import redis.clients.jedis.JedisPoolConfig; import redis.clients.jedis.Jedis; public class PoolDemo { public static void main(String[] args) { JedisPoolConfig config new JedisPoolConfig(); // 池中最大连接数 config.setMaxTotal(50); // 最大空闲连接数 config.setMaxIdle(20); // 最小空闲连接数 config.setMinIdle(5); // 借连接时是否做有效性检测 config.setTestOnBorrow(true); // 归还连接时是否做有效性检测 config.setTestOnReturn(false); // 空闲连接逐出扫描周期 config.setTimeBetweenEvictionRunsMillis(30000); // 连接最小空闲时间超过则可能被逐出 config.setMinEvictableIdleTimeMillis(60000); JedisPool pool new JedisPool(config, 127.0.0.1, 6379, 2000, yourpassword); // try-with-resources 保证归还 try (Jedis jedis pool.getResource()) { jedis.set(pool-key, pool-value); System.out.println(jedis.get(pool-key)); } // 应用关闭时销毁池 pool.close(); } }这里有几个参数值得掰开说。maxTotal设多少合适不是越大越好。每个连接在服务端都占一个文件描述符和一块内存设太大反而拖垮 Redis。经验值是单机 RedismaxTotal 控制在 50 到 200 之间具体看你的 QPS 和单次命令耗时。粗略估算公式是maxTotal ≈ 峰值QPS × 平均命令耗时(秒)。比如峰值 5000 QPS平均命令 2ms那5000 × 0.002 10考虑到突发流量留 3 到 5 倍余量设 50 就够。testOnBorrow要不要开开了每次借连接都发一个 PING多一次往返。如果网络稳定、Redis 不常重启可以关掉靠timeBetweenEvictionRunsMillis后台扫描来剔除坏连接。但如果你的 Redis 有过自动重启、或者网络抖动频繁建议开着宁可多一次 PING 也别拿到死连接。实操心得maxIdle不要设得比maxTotal还大否则没意义。一般maxIdle设成maxTotal的一半到三分之二minIdle设成maxIdle的四分之一左右。这样既能应对突发又不会让池子长期空占资源。3.3 用 try-with-resources 还是 finallyJedis实现了Closeable接口所以能用在 try-with-resources 里。但要注意这里的close()不是真的关闭连接而是归还给池子。这是 Jedis 的一个设计——Jedis对象内部有个标志位如果它是从池里借出来的close()就归还如果是裸new的close()才真关。我见过有人写这样的代码Jedis jedis pool.getResource(); jedis.set(k, v); // 忘了 close跑一段时间后报Could not get a resource from the pool因为连接全被借光了没还。所以只要是从池里拿的必须保证归还。try-with-resources 是最省心的写法编译器帮你生成 finally 块。如果非要用 finally记得判空Jedis jedis null; try { jedis pool.getResource(); jedis.set(k, v); } finally { if (jedis ! null) { jedis.close(); } }4. 核心命令实操与返回值处理4.1 字符串、哈希、列表的典型用法Jedis 的 API 命名基本跟 Redis 命令一一对应学起来很快。下面挑几个最常用的类型演示try (Jedis jedis pool.getResource()) { // 字符串 jedis.set(user:1:name, Alice); jedis.expire(user:1:name, 3600); // 设置过期单位秒 String name jedis.get(user:1:name); // 哈希适合存对象 jedis.hset(user:1, name, Alice); jedis.hset(user:1, age, 30); MapString, String user jedis.hgetAll(user:1); // 列表适合做队列 jedis.lpush(task:queue, task1, task2); String task jedis.rpop(task:queue); // 集合 jedis.sadd(tags, java, redis); SetString tags jedis.smembers(tags); // 有序集合带分数 jedis.zadd(rank, 100, player1); jedis.zadd(rank, 200, player2); ListString top jedis.zrevrange(rank, 0, 9); // 取前10名 }这里有个细节hgetAll返回的是MapString, String如果哈希特别大比如几万个字段这个 Map 会一次性全加载到内存可能撑爆 JVM。大哈希建议用hscan分批取。同理smembers、lrange这些返回集合的命令数据量大时都要小心。4.2 返回值类型与空值处理Jedis 的返回值设计有个特点很多命令返回String但可能为null。比如get一个不存在的 key返回null而不是空字符串。这个区别很重要因为null和在业务上含义完全不同。String value jedis.get(not-exist-key); if (value null) { // key 不存在 } else if (value.isEmpty()) { // key 存在但值是空字符串 }数值类命令返回Long比如del返回删除的 key 数量incr返回自增后的值。incr有个坑如果 key 的值不是数字会抛JedisDataException。所以用incr做计数器前得确保这个 key 要么不存在要么存的是数字字符串。try { long count jedis.incr(page:view); } catch (JedisDataException e) { // key 存了非数字值 jedis.set(page:view, 1); }4.3 批量操作Pipeline 与 mget单条命令一条往返网络 RTT 是主要开销。如果要在循环里发 1000 条命令用 Pipeline 能把 1000 次往返压成 1 次。try (Jedis jedis pool.getResource()) { Pipeline pipeline jedis.pipelined(); for (int i 0; i 1000; i) { pipeline.set(key: i, value: i); } // 执行并拿到所有响应 ListObject results pipeline.syncAndReturnAll(); }Pipeline 的原理是客户端把命令攒在本地缓冲区一次性发出去服务端按顺序处理完一次性回。注意 Pipeline不保证原子性中间某条命令失败后面的照样执行。如果要原子性得用事务multi/exec或者 Lua 脚本。mget是另一种批量方式但它只针对getListString values jedis.mget(key1, key2, key3);mget是服务端原生命令比 Pipeline 更轻量但只能用于字符串的批量读。写操作批量只能用 Pipeline。避坑Pipeline 里不要塞太多命令。我试过一次性塞 10 万条结果客户端内存暴涨因为所有响应都缓存在本地。建议每批控制在 1000 到 5000 条分批 sync。5. 常见问题排查与避坑清单5.1 连接泄漏最常见的生产事故症状是跑一段时间后报JedisException: Could not get a resource from the pool。根因几乎都是借了没还。排查方法在JedisPoolConfig里开setTestOnBorrow没用得看代码里有没有漏close。我一般会写个工具方法强制规范public T T execute(FunctionJedis, T action) { try (Jedis jedis pool.getResource()) { return action.apply(jedis); } }所有 Redis 操作都走这个方法从源头杜绝泄漏。这个模式后来被 Spring 的RedisTemplate学去了本质一样。5.2 超时设置别用默认值new JedisPool(config, host, port)不传超时的话用的是默认值。默认连接超时和读取超时都比较短网络稍微抖一下就可能超时。建议显式设置JedisPool pool new JedisPool(config, host, port, 2000, // 连接超时 2 秒 password, 3000); // socket 读取超时 3 秒连接超时设短点1 到 2 秒因为连不上就该快速失败。读取超时设长点3 到 5 秒因为有些命令比如大 key 的hgetAll本身耗时就长。这两个值要根据你的业务命令耗时分布来调没有万能值。5.3 常见问题速查表问题现象可能原因排查方向解决方式Could not get a resource连接泄漏检查 close 调用用 try-with-resourcesJedisConnectionException网络不通/Redis 挂了ping 服务端检查网络和 Redis 状态JedisDataException命令用错类型看具体报错信息确认 key 的数据类型响应串包/数据错乱多线程共享 Jedis检查是否单例裸用改用连接池内存暴涨Pipeline 批量过大看批次数分批 sync连接数打满maxTotal 过大看 Redis 的 client list调小 maxTotal5.4 几个容易忽略的细节密码认证的位置。auth可以在构造Jedis后单独调也可以在JedisPool构造时传。推荐后者因为池在创建连接时就认证好了借出来的连接直接可用。如果单独调auth每次借出来都得再认证一次多一次往返。数据库选择。Redis 默认有 16 个库0 到 15select可以切换。但集群模式下不支持 select只有 0 号库。所以如果你的代码里用了jedis.select(1)将来迁集群会出问题。建议从一开始就用 0 号库靠 key 前缀区分业务。序列化。Jedis 存的是字节数组你传String它按 UTF-8 编码。如果存对象得自己序列化。很多人用 JDK 序列化但那个体积大、跨语言不兼容。推荐 JSON 或者 Protobuf。这一点 Jedis 不管得你自己在业务层处理。6. 从 Jedis 到生产级使用的进阶思路裸用 Jedis 加连接池能撑起大部分中小规模场景。但如果你要的是开箱即用、自动重连、支持集群、声明式缓存那 Jedis 的薄封装反而成了负担。这时候通常会往上走一层用 Spring Data Redis 或者 Redisson。Spring Data Redis 底层可以选 Jedis 或 Lettuce 作为驱动。它帮你做了连接管理、序列化、异常转换还提供了RedisTemplate这种模板类。如果你项目已经是 Spring 体系直接用RedisTemplate比手写 Jedis 代码省事得多。但理解 Jedis 仍然有价值——因为RedisTemplate底层调的就是 Jedis 的那些方法出问题时你得能往下钻。Redisson 走的是另一条路它把 Redis 的分布式能力封装成了 Java 对象比如RLock、RMap、RQueue。适合需要分布式锁、分布式集合的场景。但它的抽象更重学习成本也更高。我的建议是先把 Jedis 用熟理解连接、命令、池化这三件事。这三件事是通用的换成任何客户端都跑不掉。等你对一次 Redis 调用到底发生了什么有了肌肉记忆再往上选框架就是水到渠成的事。最后分享一个我自己的习惯本地开发时我会在JedisPoolConfig里把maxTotal设成 1然后跑一遍所有业务代码。如果哪里泄漏了连接第二次调用就会卡死问题立刻暴露。这个极限压测法比看代码找泄漏高效得多。等确认没有泄漏再改回正常值。这个技巧帮我提前发现过好几次隐藏的连接泄漏尤其是在那些用了异步回调、异常分支复杂的代码里。