整合 Redis

从连接示例到业务会话

内置配置只提供连接，不会自动将应用的内存会话迁移到 Redis。业务接入时可建立共享的会话 Service：以 JWT 的 jti 作为键的一部分，用户 ID 作为值，通过 Redis.setStr(key, seconds, value) 写入与令牌一致的有效期；鉴权时校验 JWT 后再读取会话，退出时调用 Redis.del(key)。

多个应用实例需要使用相同的签名密钥、Redis 逻辑库和业务键前缀。开发、测试、生产则应隔离键空间。Redis 不可用时返回服务不可用，不应自动回退到互不共享的进程内会话。应用重启不会清空 Redis 会话；Redis 自身的数据持久化仍需单独配置。

测试应覆盖跨服务实例读取、退出撤销、有效期、Redis 故障，以及后端进程重启后使用原 token。测试键使用独立随机前缀，结束后仅清理该前缀下的数据。

tio-boot-admin 提供 TioAdminRedisDbConfiguration，负责读取 Redis 连接参数、启动 java-db 的 Redis 插件，并在应用关闭时停止插件。业务代码复用已有连接池即可。

1. 添加客户端依赖

在应用的 pom.xml 中显式声明 Jedis；如果工程已经声明，不要重复添加：

<dependency>
  <groupId>redis.clients</groupId>
  <artifactId>jedis</artifactId>
  <version>4.3.1</version>
</dependency>

上游以 provided 声明的客户端依赖不会自动进入应用运行时，连接配置也不会自动补齐客户端 JAR。使用与框架依赖兼容的客户端。

2. 配置 Redis 连接

在当前环境配置文件，例如 app-dev.properties 中添加：

redis.host=127.0.0.1
redis.port=6379
redis.database=0
redis.cacheName=main
redis.timeout=2000

如果 Redis 要求密码，通过本地秘密配置提供：

redis.password=replace-with-your-password

未设置密码的 Redis 无需配置 redis.password。不要在示例、源码或提交记录中填写真实密码。

配置项含义与默认行为
redis.host主机地址；未配置时跳过 Redis 初始化
redis.port端口，建议显式填写 6379；内置配置没有提供端口默认值
redis.password可选的认证密码
redis.databaseRedis 逻辑库编号，默认 0
redis.cacheNamejava-db 缓存实例名称，默认 main；不是 Redis 键前缀
redis.timeout传给 Jedis 连接池的超时，单位毫秒；内置默认值为 60，示例显式设置为 2000

这里使用普通单节点连接。内置配置没有读取 ACL 用户名、TLS、Sentinel 或 Cluster 参数；这些场景需要按客户端能力单独扩展配置。

不使用 Redis 时，移除有效配置中的 redis.host 即可。不要用空字符串或自行添加 redis.enabled=false 代替：内置配置按 host 是否为 null 决定是否初始化。

3. 调用内置配置

在应用原有的启动配置中保留一次：

import nexus.io.tio.boot.admin.config.TioAdminRedisDbConfiguration;

// 放在已有 config() 方法中
new TioAdminRedisDbConfiguration().config();

上述片段中的 import 放在文件顶部，调用放在配置方法内。如果 入门指南 的标准配置中已经包含该调用，无需再次添加。不要再手工创建同名 RedisPlugin，否则可能发生重复缓存注册。

初始化完成后，Redis.use() 返回默认实例，Redis.use("main") 按名称获取实例。第一个注册的缓存默认成为主缓存；有多个实例时应明确默认缓存选择。静态字符串 API 使用默认实例。

内置配置会尝试建立连接，并注册应用关闭钩子。连接尝试中的异常会被捕获，因此不能仅凭应用启动成功就判定 Redis 可用，应执行一次实际读写验证。

4. 写入、读取和删除字符串

import nexus.io.redis.Redis;

String key = "example:redis:message";
String status = Redis.setStr(key, 60, "Hello Redis");
String value = Redis.getStr(key);
long deleted = Redis.del(key);
方法结果
Redis.setStr(key, value)写入原生字符串，不设置过期时间，成功返回 OK
Redis.setStr(key, seconds, value)写入并原子设置过期时间，单位为秒，成功返回 OK
Redis.getStr(key)读取字符串；键不存在或过期返回 null
Redis.del(key)删除对应键；实际删除返回 1，不存在返回 0，重复删除返回 0

redis.timeout 的毫秒单位与 setStr 有效期的秒单位不同。字符串 API 使用相同的原生键编码，可与 Redis 命令行工具互操作。

5. Handler 中的最小演示

单纯演示 API 时可以直接在 Handler 调用，不必额外建立 Service。下面使用固定的示例键，避免对任意业务键执行操作：

package com.example.admin.handler;

import com.jfinal.kit.Kv;
import nexus.io.model.body.RespBodyVo;
import nexus.io.redis.Redis;
import nexus.io.tio.boot.http.TioRequestContext;
import nexus.io.tio.http.common.HttpRequest;
import nexus.io.tio.http.common.HttpResponse;

public class RedisDemoHandler {
  private static final String KEY = "example:redis:demo";

  public HttpResponse set(HttpRequest request) {
    String status = Redis.setStr(KEY, 60, "Hello Redis");
    Kv result = Kv.create().set("status", status);
    return TioRequestContext.getResponse().respond(RespBodyVo.ok(result));
  }

  public HttpResponse get(HttpRequest request) {
    String value = Redis.getStr(KEY);
    Kv result = Kv.create().set("value", value).set("exists", value != null);
    return TioRequestContext.getResponse().respond(RespBodyVo.ok(result));
  }

  public HttpResponse delete(HttpRequest request) {
    long deleted = Redis.del(KEY);
    Kv result = Kv.create().set("deleted", deleted);
    return TioRequestContext.getResponse().respond(RespBodyVo.ok(result));
  }
}

在已有 Handler 路由配置方法中注册；所需 import 分别为 HttpMethod、HttpRequestRouter、TioBootServer 和示例 Handler：

HttpRequestRouter router = TioBootServer.me().getRequestRouter();
RedisDemoHandler handler = new RedisDemoHandler();
router.add(HttpMethod.POST, "/api/redis-demo/set", handler::set);
router.add(HttpMethod.GET, "/api/redis-demo/get", handler::get);
router.add(HttpMethod.POST, "/api/redis-demo/delete", handler::delete);

类型全名为 nexus.io.tio.http.common.HttpMethod、nexus.io.tio.http.server.router.HttpRequestRouter、nexus.io.tio.boot.server.TioBootServer、com.example.admin.handler.RedisDemoHandler。Handler 直接创建，交给路由器持有，不放入 Aop。

保留后台拦截器保护，不将这些写接口加入匿名放行列表。已有自定义鉴权时，应按项目规则给这些路由配置访问策略。真实业务涉及参数、用户归属等规则时，仍需对应的校验和业务分层。

6. 通过 HTTP 验证

以下假定应用端口为 8100，没有设置额外 context-path；设置了前缀时，在路径前补上该前缀。使用后台登录取得的 token 放入请求头：

POST /api/redis-demo/set HTTP/1.1
Host: 127.0.0.1:8100
Authorization: Bearer <token>

依次请求：

  1. POST /api/redis-demo/set：返回 status=OK。
  2. GET /api/redis-demo/get：返回 value=Hello Redis、exists=true。
  3. POST /api/redis-demo/delete：返回 deleted=1。
  4. 再次读取：返回 exists=false。
  5. 再次删除：返回 deleted=0。

也可以写入后等待有效期结束，再确认 exists=false。数值是否序列化为字符串、null 字段是否输出，取决于应用的 JSON 配置。

出现连接超时或认证错误时，检查服务地址、端口、密码、逻辑库及实际生效的环境配置；出现客户端类缺失时，检查运行时 Jedis 依赖。更多底层用法见 Redis 使用示例。