Galosys.Foundation.Redis 26.5.20.1

Galosys.Foundation.Redis

成熟度: 🟢 稳定 — v2 三层架构（Connection → Template → Operations），分布式锁、幂等性、缓存管理、Pub/Sub、健康检查、重试装饰器全面就绪

简介

Galosys.Foundation.Redis 提供 Redis 抽象层，对标 Spring Data Redis 三层架构：Connection（底层连接）、Template（模板操作）、Operations（数据结构视图）。支持序列化策略、Pipeline、消息队列、分布式锁、幂等性控制、缓存管理等能力。

架构概览

┌──────────────────────────────────────────────────────┐
│                  应用层                                │
│  IDistributedLock / IDistributedIdempotence           │
│  RedisCacheManager / IMessageListener                 │
├──────────────────────────────────────────────────────┤
│                   RedisTemplate                       │
│  OpsForValue / OpsForHash / OpsForList / OpsForSet    │
│  OpsForZSet / OpsForGeo / OpsForStream                │
│  KeySerializer / ValueSerializer / HashKeySerializer  │
│  ConvertAndSendAsync (Pub/Sub)                        │
├──────────────────────────────────────────────────────┤
│            IRedisConnection (Resilient)               │
│  Key / String / Hash / List / Set / SortedSet         │
│  Geo / Stream / Script / Publish — 全部 byte[] 级别   │
├──────────────────────────────────────────────────────┤
│         实现层（FreeRedis / StackExchange.Redis）       │
│         重试装饰器 (ResilientRedisConnection)           │
├──────────────────────────────────────────────────────┤
│         基础设施                                       │
│  RedisHealthCheck / RedisConnectionLogger             │
│  RedisConnectionOptions / RedisRetryOptions           │
└──────────────────────────────────────────────────────┘

特性

• 三层架构 — Connection → Template → Operations，职责清晰
• 7 大 Operations 视图 — Value、Hash、List、Set、SortedSet、Geo、Stream
• 可插拔序列化 — 内置 Json、String、Null 三种序列化器
• Pipeline 批量执行 — ExecuteInPipelineAsync 高效批处理
• IRedisCallback — 通过 ExecuteAsync 直接操作底层连接
• 分布式锁 — IDistributedLock 统一锁接口，支持看门狗续期、await using 自动释放
• 幂等性控制 — IDistributedIdempotence 统一幂等性接口，标记/缓存/清理
• CacheManager — Builder 模式构建缓存管理器，对标 Spring CacheManager
• Pub/Sub — IMessageListener + IRedisMessageListenerContainer 消息发布订阅
• 重试装饰器 — ResilientRedisConnection 指数退避 + 随机抖动
• 健康检查 — PING 延迟检测，自动注册 [HealthCheck("redis")]
• 连接日志 — 连接断开/恢复/错误事件记录
• 向后兼容 — 旧 IRedisCli / RLock / RIdempotence 标记 [Obsolete] 但仍可使用

安装

dotnet add package Galosys.Foundation.Redis

本包为抽象层，需配合实现层包使用（FreeRedis 或 StackExchange.Redis）。

快速开始

1. 注册服务

// 使用 FreeRedis 实现（推荐）
services.AddRedisClient();

// 或使用 StackExchange.Redis 实现
services.AddStackExchangeRedis(Configuration);

// 注册缓存管理器（可选）
services.AddRedisCacheManager(config =>
{
    config.EntryTtl = TimeSpan.FromHours(1);   // 默认过期时间
    config.KeyPrefix = "app:";                   // Key 前缀
});

2. 注入 RedisTemplate

public class OrderService
{
    private readonly RedisTemplate _redis;

    public OrderService(RedisTemplate redis)
    {
        _redis = redis;
    }
}

3. Value 操作

// 设置值（默认 JSON 序列化）
var valueOps = _redis.OpsForValue();
await valueOps.SetAsync("order:001", new Order { OrderNo = "001", Amount = 100 });

// 获取值
var order = await valueOps.GetAsync<Order>("order:001");

// 设置带过期时间
await valueOps.SetAsync("order:001", order, TimeSpan.FromMinutes(30));

// 自增
await valueOps.IncrementAsync("counter:order");

4. Hash 操作

var hashOps = _redis.OpsForHash();

// 设置 Hash field
await hashOps.PutAsync("user:001", "name", "张三");
await hashOps.PutAsync("user:001", "profile", new UserProfile { Age = 25 });

// 获取单个 field
var name = await hashOps.GetAsync<string>("user:001", "name");

// 获取全部 field-value
var all = await hashOps.GetAllAsync<UserProfile>("user:001");

// 判断 field 是否存在
var exists = await hashOps.ContainsKeyAsync("user:001", "name");

5. List 操作

var listOps = _redis.OpsForList();

// 推入
await listOps.RightPushAsync("task:queue", new TaskItem { Id = 1 });

// 弹出
var task = await listOps.LeftPopAsync<TaskItem>("task:queue");

// 获取范围
var items = await listOps.RangeAsync<TaskItem>("task:queue", 0, -1);

6. Set 操作

var setOps = _redis.OpsForSet();

await setOps.AddAsync("tags:product:001", "电子产品", "手机", "5G");
var members = await setOps.MembersAsync<string>("tags:product:001");
var count = await setOps.SizeAsync("tags:product:001");

7. SortedSet 操作

var zsetOps = _redis.OpsForZSet();

await zsetOps.AddAsync("leaderboard", "player:001", 9500);
var top10 = await zsetOps.ReverseRangeAsync<string>("leaderboard", 0, 9);
var rank = await zsetOps.RankAsync("leaderboard", "player:001");

8. Geo 操作

var geoOps = _redis.OpsForGeo();

await geoOps.AddAsync("locations", 116.397, 39.908, "北京天安门");
var nearby = await geoOps.RadiusAsync("locations", 116.397, 39.908, 10, GeoUnit.Kilometers);
var dist = await geoOps.DistanceAsync("locations", "北京天安门", "北京西站", GeoUnit.Kilometers);

9. Stream 操作

var streamOps = _redis.OpsForStream();

var msgId = await streamOps.AddAsync("orders", new Dictionary<string, string>
{
    ["orderNo"] = "ORDER001",
    ["amount"] = "100.00"
});

await streamOps.CreateConsumerGroupAsync("orders", "order-group");
var messages = await streamOps.ReadGroupAsync("orders", "order-group", "consumer-1", count: 10);
await streamOps.AcknowledgeAsync("orders", "order-group", msgId);

---

分布式锁 (IDistributedLock)

命名空间：Microsoft.Extensions.Locking.Distributed

统一锁接口，支持 await using 自动释放、看门狗自动续期。InMemoryDistributedLock 提供内存实现（用于单元测试）。

接口说明

类型	说明
IDistributedLock	分布式锁接口，IDisposable
IDistributedLockHandle	锁句柄，IAsyncDisposable + IsAcquired + ReleaseAsync()
InMemoryDistributedLock	内存实现（测试用）

核心方法

Task<IDistributedLockHandle> TryAcquireAsync(
    string resourceKey,            // 锁的资源标识
    TimeSpan expiry,               // 锁的过期时间
    TimeSpan? waitTimeout = null,  // 等待超时，null 表示不等待
    TimeSpan? renewalInterval = null, // 看门狗续期间隔，null 表示不续期
    CancellationToken cancellationToken = default);

使用示例

// 注入 IDistributedLock
public class PaymentService(IDistributedLock @lock)
{
    public async Task PayAsync(string orderNo)
    {
        // await using 自动释放，即使发生异常也能确保释放
        await using var handle = await @lock.TryAcquireAsync(
            $"lock:pay:{orderNo}",
            expiry: TimeSpan.FromSeconds(30),       // 锁 30 秒后自动过期
            waitTimeout: TimeSpan.FromSeconds(5),    // 最多等待 5 秒
            renewalInterval: TimeSpan.FromSeconds(10)); // 每 10 秒看门狗续期

        if (handle.IsAcquired)
        {
            // 业务逻辑，锁会自动续期和释放
            await ProcessPaymentAsync(orderNo);
        }
        else
        {
            throw new BusinessException("获取锁失败，请稍后重试");
        }
    }
}

迁移指南

旧版 RLock 已标记 [Obsolete("请使用 IDistributedLock 统一锁接口")]：

// ❌ 旧写法（已过时）
var token = await rLock.TryLockAsync("key", 5000, 30000);
try { /* ... */ }
finally { await rLock.UnlockAsync("key", token); }

// ✅ 新写法
await using var handle = await distributedLock.TryAcquireAsync("key", TimeSpan.FromSeconds(30));
if (handle.IsAcquired) { /* ... */ }

---

幂等性 (IDistributedIdempotence)

命名空间：Microsoft.Extensions.Idempotence

分布式幂等性控制接口，防止重复提交，支持结果缓存。

接口方法

方法	说明
TryMarkProcessingAsync(requestId, expiry)	原子标记请求为"处理中"，返回 false 表示重复请求
MarkSuccessAsync(requestId, resultJson, expiry)	标记请求成功，缓存结果 JSON
GetCachedResultAsync(requestId)	获取已缓存的成功结果
ClearStateAsync(requestId)	清理状态（业务失败时调用）

使用示例

public class OrderService(IDistributedIdempotence idempotence)
{
    public async Task<OrderResult> CreateOrderAsync(string requestId, Order order)
    {
        // 尝试标记为处理中（幂等性检查）
        if (!await idempotence.TryMarkProcessingAsync(requestId, TimeSpan.FromMinutes(10)))
        {
            // 重复请求 → 返回已缓存的结果
            var cached = await idempotence.GetCachedResultAsync(requestId);
            if (cached != null) return JsonSerializer.Deserialize<OrderResult>(cached);
            throw new BusinessException("请求正在处理中，请稍后");
        }

        try
        {
            var result = await DoCreateOrderAsync(order);
            // 成功后缓存结果
            await idempotence.MarkSuccessAsync(requestId, JsonSerializer.Serialize(result), TimeSpan.FromHours(24));
            return result;
        }
        catch
        {
            // 失败后清理状态，允许重试
            await idempotence.ClearStateAsync(requestId);
            throw;
        }
    }
}

迁移指南

旧版 RIdempotence 已标记 [Obsolete("请使用 IDistributedIdempotence 统一幂等性接口")]：

// ❌ 旧写法（已过时）
var isNew = await rIdempotence.IdempotenceMarkAsync("msgKey", 600);
await rIdempotence.IdempotenceRemoveAsync("msgKey");

// ✅ 新写法
if (await idempotence.TryMarkProcessingAsync("requestId", TimeSpan.FromMinutes(10)))
{
    // ... 业务逻辑
    await idempotence.MarkSuccessAsync("requestId", resultJson, expiry);
}

---

CacheManager

命名空间：Galosys.Foundation.Redis

对标 Spring CacheManager 的缓存管理器，支持 Builder 模式构建、命名缓存、Key 前缀、TTL 配置。

核心类型

类型	说明
RedisCacheManager	缓存管理器，管理多个命名 ICache
ICache	缓存抽象接口：GetAsync / PutAsync / EvictAsync / ClearAsync
RedisCacheConfiguration	缓存配置：TTL、前缀、null 缓存策略、序列化器
CacheStatistics	缓存统计：命中次数、未命中次数、条目数量

RedisCacheConfiguration 配置项

属性	类型	默认值	说明
EntryTtl	TimeSpan?	null	默认条目过期时间，null 表示永不过期
DisableCachingNullValues	bool	false	是否禁用缓存 null 值（默认缓存 null 防穿透）
KeyPrefix	string	null	Key 前缀
ValueSerializer	IRedisSerializer	null	值序列化器，null 使用 RedisTemplate 默认

DI 注册

// 方式一：使用默认配置
services.AddRedisCacheManager();

// 方式二：使用 Action 配置
services.AddRedisCacheManager(config =>
{
    config.EntryTtl = TimeSpan.FromHours(1);   // 默认过期 1 小时
    config.KeyPrefix = "app:";                   // Key 前缀
    config.DisableCachingNullValues = true;      // 禁止缓存 null
});

手动构建

// 使用 Builder 模式手动构建
var manager = RedisCacheManager.CreateBuilder(redisTemplate)
    .EntryTtl(TimeSpan.FromHours(1))           // 默认过期时间
    .KeyPrefix("app:")                          // Key 前缀
    .DisableCachingNullValues()                 // 禁止缓存 null
    .ValueSerializer(new JsonRedisSerializer()) // 自定义序列化器
    .Configure(c => c.EntryTtl = TimeSpan.FromMinutes(30)) // 追加配置
    .Build();

// 获取命名缓存
var cache = manager.GetCache("orders");

// 操作缓存
await cache.PutAsync("order:001", orderData);                          // 写入
var data = await cache.GetAsync<OrderData>("order:001");               // 读取
await cache.EvictAsync("order:001");                                   // 逐出
await cache.ClearAsync();                                              // 清空

---

Pub/Sub 消息发布订阅

命名空间：Galosys.Foundation.Redis

基于 Redis Pub/Sub 的消息发布订阅机制，支持频道精确匹配和模式匹配。

核心类型

类型	说明
IMessageListener	消息监听器接口，OnMessageAsync(RedisMessage)
IRedisMessageListenerContainer	消息监听容器（IHostedService），管理订阅生命周期
RedisMessage	消息体：Channel（频道） + Body（消息字节）
ChannelTopic	频道主题，精确匹配频道名
PatternTopic	模式主题，支持 glob 风格模式匹配（如 order.*）

发布消息

// 通过 RedisTemplate 发布（自动序列化）
await redisTemplate.ConvertAndSendAsync("order.events", new OrderEvent { OrderNo = "001" });

订阅消息

// 实现 IMessageListener
public class OrderEventListener : IMessageListener
{
    public async Task OnMessageAsync(RedisMessage message)
    {
        var body = Encoding.UTF8.GetString(message.Body);
        Console.WriteLine($"频道: {message.Channel}, 消息: {body}");
    }
}

// 注册监听器到容器
container.AddMessageListener(new OrderEventListener(), "order.events");

// 移除监听器
container.RemoveMessageListener(listener);

---

连接配置 (RedisConnectionOptions)

命名空间：Microsoft.Extensions.Options，配置节：Redis:Connection

配置项

属性	类型	默认值	说明
ConnectionString	string	null	连接字符串（主机:端口）
ServiceName	string	null	Sentinel 服务名称
Password	string	null	密码
ConnectTimeout	int	5000	连接超时（毫秒）
SyncTimeout	int	5000	同步操作超时（毫秒）
AsyncTimeout	int	10000	异步操作超时（毫秒）
AbortOnConnectFail	bool	false	连接失败时是否中止
ConnectRetry	int	3	连接重试次数
KeepAlive	int	60	保持活跃间隔（秒）
Retry	RedisRetryOptions	见下表	重试策略配置

RedisRetryOptions 重试策略

属性	类型	默认值	说明
MaxRetries	int	3	最大重试次数
InitialDelayMs	int	200	初始延迟（毫秒）
MaxDelayMs	int	3000	最大延迟（毫秒）
EnableJitter	bool	true	是否启用随机抖动

appsettings.json 配置示例

{
  "Redis": {
    "Connection": {
      "ConnectionString": "localhost:6379",
      "ServiceName": "mymaster",
      "Password": "your-password",
      "ConnectTimeout": 5000,
      "AbortOnConnectFail": false,
      "ConnectRetry": 3,
      "KeepAlive": 60,
      "Retry": {
        "MaxRetries": 3,
        "InitialDelayMs": 200,
        "MaxDelayMs": 3000,
        "EnableJitter": true
      }
    }
  }
}

向后兼容：若未配置 Redis:Connection，将回退读取 ConnectionStrings:Redis。

---

重试装饰器 (ResilientRedisConnection)

命名空间：Galosys.Foundation.Redis

装饰器模式包装 IRedisConnection，对所有命令提供自动重试能力。

特性

• 指数退避 — 延迟按 2 的幂次递增：InitialDelayMs × 2^(attempt-1)，不超过 MaxDelayMs
• 随机抖动 — 启用后追加 Random(0, delay/2) 的随机延迟，防止重试风暴
• 可重试异常 — TimeoutException 及名称包含 "Connection" 或 "Timeout" 的异常
• 自动注册 — 在 DI 中自动包装到 ResilientRedisConnection
• 全方法覆盖 — Key、String、Hash、List、Set、SortedSet、Geo、Stream、Script、Pipeline、Pub/Sub 全部 50+ 个方法

工作原理

请求 → ResilientRedisConnection.ExecuteWithRetryAsync()
          ├── 成功 → 返回结果
          └── 可重试异常 → 计算延迟 → 等待 → 重试（最多 MaxRetries 次）

---

健康检查 (RedisHealthCheck)

命名空间：Galosys.Foundation.Redis

基于 PING 的健康检查，通过 set → get → delete 往返检测连接状态。

健康状态判定

延迟	状态	说明
< 100ms	Healthy	Redis 正常
>= 100ms	Degraded	Redis 响应缓慢
异常	Unhealthy	Redis 连接失败

自动注册

通过 [HealthCheck("redis")] 特性自动注册，Tags 包含 "redis" 和 "database"。

配置

// 在 appsettings.json 中启用健康检查端点
services.AddHealthChecks();
// RedisHealthCheck 由 [HealthCheck] 特性自动发现注册

// 映射端点
app.MapHealthChecks("/health");

---

连接日志 (RedisConnectionLogger)

命名空间：Galosys.Foundation.Redis

集中记录 Redis 连接生命周期事件，各实现层（FreeRedis / StackExchange.Redis）附加各自的事件。

日志事件

方法	级别	说明
LogConnectionFailed(endpoint, ex)	Error	连接断开
LogConnectionRestored(endpoint)	Information	连接恢复
LogError(message)	Warning	一般错误
LogClientCreated(clientType)	Information	客户端创建

---

高级用法

自定义序列化器

_redis.KeySerializer = new StringRedisSerializer();      // Key 默认 UTF-8 字符串
_redis.ValueSerializer = new JsonRedisSerializer();       // Value 默认 JSON
_redis.HashKeySerializer = new StringRedisSerializer();   // HashKey 默认 UTF-8
_redis.HashValueSerializer = new JsonRedisSerializer();   // HashValue 默认 JSON

使用 StringRedisTemplate（纯字符串场景）

// 内置 StringRedisSerializer，适合纯字符串存取
public class CacheService(StringRedisTemplate stringRedis)
{
    public async Task SetAsync(string key, string value, TimeSpan? ttl = null)
    {
        await stringRedis.OpsForValue().SetAsync(key, value, ttl);
    }
}

Pipeline 批量执行

await _redis.ExecuteInPipelineAsync(pipe =>
{
    pipe.SetString("key1", "value1"u8.ToArray());
    pipe.SetString("key2", "value2"u8.ToArray());
    pipe.SetHash("hash1", "field1"u8.ToArray(), "val"u8.ToArray());
});

IRedisCallback 底层操作

var result = await _redis.ExecuteAsync(new MyCallback());

public class MyCallback : IRedisCallback
{
    public Task<object> DoInRedis(IRedisConnection connection, CancellationToken ct)
    {
        // 直接调用 byte[] 级别的 IRedisConnection 方法
        return connection.StringGetAsync("raw:key"u8.ToArray(), ct);
    }
}

通用操作

await _redis.DeleteAsync("order:001");                    // 删除 key
await _redis.ExistsAsync("order:001");                    // 判断存在
await _redis.ExpireAsync("order:001", TimeSpan.FromHours(1)); // 设置过期
var ttl = await _redis.GetTtlAsync("order:001");          // 获取 TTL

消息队列（旧接口，保持兼容）

// 仅 FreeRedisTemplate 实现了消息队列
await redisTemplate.SendAsync("order.created", new OrderCreatedMessage { OrderNo = "001" });

redisTemplate.Handle<OrderCreatedMessage>(async msg =>
{
    Console.WriteLine($"处理订单: {msg.OrderNo}");
    return true;
}, "order.created");

---

RedisRepository（对标 Spring @RedisHash）

对标 Spring Data Redis 的 @RedisHash + CrudRepository 模式，实体映射为 Redis Hash，支持二级索引。

核心类型

类型	说明
[RedisHash("keyspace")]	标注实体类，指定 Keyspace 和可选 TTL
[RedisIndexed]	标注属性，自动维护二级索引
IRedisRepository<TEntity, TKey>	Repository 接口：FindById / FindAll / Save / Delete / Count
RedisRepository<TEntity, TKey>	通用实现类

DI 注册

services.AddRedisRepository<Person, string>();

使用示例

// 1. 定义实体
[RedisHash("persons", TimeToLive = 3600)]  // keyspace=persons, TTL=3600秒
public class Person
{
    public string Id { get; set; }
    public string Name { get; set; }

    [RedisIndexed]  // 自动维护二级索引: persons:name:张三 → Set { "1" }
    public int Age { get; set; }
}

// 2. 注入并使用
public class PersonService(IRedisRepository<Person, string> repo)
{
    public async Task ExampleAsync()
    {
        // 保存（自动写入 Hash + 维护索引 + 设置 TTL）
        await repo.SaveAsync(new Person { Id = "1", Name = "张三", Age = 30 });

        // 按 ID 查找
        var person = await repo.FindByIdAsync("1");

        // 查找全部
        var all = await repo.FindAllAsync();

        // 计数
        var count = await repo.CountAsync();

        // 删除（自动清理索引）
        await repo.DeleteAsync("1");
    }
}

Redis 存储结构

主数据:   persons:1 → Hash { "Id": "1", "Name": "张三", "Age": "30" }
二级索引: persons:Age:30 → Set { "1" }

---

Lua 脚本（IRedisScriptExecutor）

统一的 Lua 脚本执行抽象，自动使用 EVALSHA 缓存优化，NOSCRIPT 时自动 fallback 到 EVAL。

核心类型

类型	说明
IRedisScriptExecutor	Lua 脚本执行接口
RedisScript<T>	脚本定义：Script + Keys

使用示例

// 注入 IRedisScriptExecutor（由实现层注册）

// 方式一：使用 RedisScript 对象
var script = new RedisScript<long>
{
    Script = "return redis.call('INCR', KEYS[1])",
    Keys = new[] { "counter" }
};
var count = await executor.ExecuteAsync<long>(script);

// 方式二：直接传脚本字符串
var result = await executor.ExecuteAsync<string>(
    "return redis.call('GET', KEYS[1])",
    keys: new[] { "mykey" });

---

Transaction 事务支持

通过 RedisTemplate 提供 MULTI/EXEC 事务支持和 WATCH 乐观锁。

使用示例

// 事务内多条命令原子执行
await redisTemplate.ExecuteInTransactionAsync(conn =>
{
    // 在事务中执行多条命令
});

// WATCH 乐观锁
await redisTemplate.WatchAsync("account:001");
await redisTemplate.ExecuteInTransactionAsync(conn =>
{
    // 若 account:001 被修改，事务将失败
});

---

Key 过期事件监听

基于 IRedisMessageListenerContainer 的 Key 过期事件监听，自动注册。

配置要求

Redis 需要开启 keyspace notification：

# redis.conf
notify-keyspace-events Ex

使用示例

// 定义监听器
public class OrderKeyExpirationListener : KeyExpirationEventListener
{
    public OrderKeyExpirationListener() : base("orders") { }

    public override Task HandleAsync(KeyExpiredEvent e)
    {
        // e.Key 为过期的 key（不含 keyspace 前缀）
        Console.WriteLine($"订单过期: {e.Key}");
        return Task.CompletedTask;
    }
}

// 注册 DI 后，RedisTemplateBootstrapper 自动发现并注册
// 自动订阅 __keyevent@*__:expired 频道

---

核心接口与类

抽象层接口

接口	说明
IRedisConnection	底层连接抽象，byte[] 级别的 11 大命令组（含 Transaction、Pub/Sub）
IRedisSerializer	序列化/反序列化接口
IValueOperations	String/Value 操作视图
IHashOperations	Hash 操作视图
IListOperations	List 操作视图
ISetOperations	Set 操作视图
IZSetOperations	SortedSet 操作视图
IGeoOperations	Geo 操作视图
IStreamOperations	Stream 操作视图
IPipeline	Pipeline 批量命令接口
IRedisCallback	底层连接回调接口
IRedisScriptExecutor	Lua 脚本执行接口（EVALSHA 缓存 + fallback）
IRedisRepository<TEntity, TKey>	RedisRepository 接口（对标 Spring CrudRepository）
IDistributedLock	分布式锁统一接口（Microsoft.Extensions.Locking.Distributed）
IDistributedLockHandle	分布式锁句柄，IAsyncDisposable
IDistributedIdempotence	幂等性控制统一接口（Microsoft.Extensions.Idempotence）
ICache	缓存抽象接口：Get / Put / Evict / Clear
IMessageListener	Pub/Sub 消息监听器接口
IRedisMessageListenerContainer	消息监听容器（IHostedService）

核心类

类	说明
RedisTemplate	模板核心，OpsForXxx 工厂 + 序列化配置 + ConvertAndSendAsync + Transaction
StringRedisTemplate	便捷类，Value 使用 StringRedisSerializer
RedisRepository<TEntity, TKey>	通用 Repository 实现，Hash 映射 + 二级索引 + Keyspace 管理
RedisScript<T>	Lua 脚本定义类
RedisCacheManager	缓存管理器，Builder 模式构建，管理多个命名 ICache
RedisCacheConfiguration	缓存配置项：TTL、前缀、null 策略、序列化器
CacheStatistics	缓存统计：命中、未命中、条目数
ResilientRedisConnection	重试装饰器，指数退避 + 随机抖动，全方法覆盖
RedisHealthCheck	健康检查，PING 延迟检测，[HealthCheck("redis")]
RedisConnectionLogger	连接事件日志记录器
KeyExpirationEventListener	Key 过期事件监听器基类
RedisConnectionOptions	连接配置选项（Redis:Connection 配置节）
RedisRetryOptions	重试策略配置
RedisMessage	Pub/Sub 消息体：Channel + Body
ChannelTopic	频道主题，精确匹配
PatternTopic	模式主题，glob 模式匹配
JsonRedisSerializer	JSON 序列化器（System.Text.Json）
StringRedisSerializer	UTF-8 字符串序列化器
NullRedisSerializer	byte[] 透传序列化器
InMemoryDistributedLock	内存分布式锁实现（测试用）
InMemoryDistributedIdempotence	内存幂等性实现（测试用）
GeoUnit	距离单位枚举（Meters, Kilometers, Miles, Feet）
GeoPosition	地理位置坐标
StreamMessage	Stream 消息

特性

特性	说明
[RedisHash("keyspace")]	标注实体类为 Redis Hash 映射，可指定 TimeToLive
[RedisIndexed]	标注属性为二级索引字段

旧 API（标记 [Obsolete]）

类/接口	说明	迁移目标
IRedisCli	旧版 Redis 客户端接口	使用 RedisTemplate
RLock	分布式锁	IDistributedLock
RIdempotence	幂等性保证	IDistributedIdempotence
RDelayedQueue	延迟队列	IStreamOperations

---

值类型

GeoUnit

public enum GeoUnit
{
    Meters,      // 米（默认）
    Kilometers,  // 公里
    Miles,       // 英里
    Feet         // 英尺
}

GeoPosition

public struct GeoPosition
{
    public double Longitude { get; set; } // 经度
    public double Latitude { get; set; }  // 纬度
}

StreamMessage

public class StreamMessage
{
    public string Id { get; set; }                     // 消息 ID
    public Dictionary<string, string> Body { get; set; } // 消息体
}

RedisMessage

public class RedisMessage
{
    public string Channel { get; set; } // 消息所属频道
    public byte[] Body { get; set; }    // 消息体（原始字节）
}

---

依赖

• Galosys.Foundation.Core（IDistributedLock、IDistributedIdempotence、[HealthCheck]）
• Microsoft.Extensions.DependencyInjection
• Microsoft.Extensions.Logging
• Microsoft.Extensions.Options
• Microsoft.Extensions.Diagnostics.HealthChecks