# Quickuse.Caching

**Repository Path**: quickuse/Quickuse.Caching

## Basic Information

- **Project Name**: Quickuse.Caching
- **Description**: 快速应用.缓存组件，这个组件主要提供缓存的使用，方便在开发的过程使用环境的场景，
- **Primary Language**: C#
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 2
- **Forks**: 0
- **Created**: 2020-04-25
- **Last Updated**: 2026-03-25

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Quickuse.Caching

快速应用缓存组件 - 提供便捷的运行时缓存和 Redis 缓存支持

## 介绍

Quickuse.Caching 是一个面向 .NET 开发者的统一缓存抽象层类库，旨在简化分布式缓存和本地缓存的使用。

在线文档： http://quickuse.gitee.io/quickuse.caching

## 平台支持

- `netstandard2.1`
- 兼容 .NET Core 3.1+
- 兼容 .NET 5/6/7/8+

## 快速开始

### 1. 安装 NuGet 包

```bash
dotnet add package Quickuse.Caching
```

### 2. 配置服务

```csharp
// Startup.cs 或 Program.cs
services.AddQuickuseCaching(config =>
{
    config.OnError = (category, message, detail) => 
    {
        // 自定义错误日志处理
        Console.WriteLine($"[{category}] {message}");
    };
});

// 设置服务提供器
var app = builder.Build();
app.Services.UseQuickuseCaching();
```

### 3. 使用缓存

```csharp
public class MyService
{
    private readonly IRedisCache _redisCache;
    private readonly IRuntimeCache _runtimeCache;
    
    public MyService(IRedisCache redisCache, IRuntimeCache runtimeCache)
    {
        _redisCache = redisCache;
        _runtimeCache = runtimeCache;
    }
    
    public string GetData(string key)
    {
        // 使用 Redis 缓存
        return _redisCache.StringGet(key, () => 
        {
            return LoadFromDatabase(key);
        }, seconds: 3600);
    }
}
```

## Redis 配置

Quickuse.Caching 使用环境变量配置 Redis 连接，支持单节点和集群两种模式。

### 单节点模式

适用于开发环境或单机 Redis 部署。

#### 环境变量配置

| 环境变量 | 说明 | 默认值 | 必填 |
|---------|------|--------|------|
| `REDIS_HOST` | Redis 服务器地址 | `localhost` | 否 |
| `REDIS_PORT` | Redis 端口 | `6379` | 否 |
| `REDIS_PASSWORD` | Redis 密码 | 无 | 否 |
| `REDIS_USER` | Redis ACL 用户名（Redis 6+） | 无 | 否 |
| `REDIS_DATABASE` | 数据库索引 | `0` | 否 |
| `REDIS_SSL` | 是否启用 SSL/TLS | `false` | 否 |
| `REDIS_CONNECT_TIMEOUT` | 连接超时（毫秒） | `5000` | 否 |
| `REDIS_SYNC_TIMEOUT` | 同步操作超时（毫秒） | `5000` | 否 |
| `REDIS_ALLOW_ADMIN` | 是否允许管理命令 | `false` | 否 |
| `REDIS_ABORT_CONNECT` | 连接失败时是否中止 | `true` | 否 |

#### 配置示例

**Linux/Mac**
```bash
export REDIS_HOST=127.0.0.1
export REDIS_PORT=6379
export REDIS_PASSWORD=mypassword
export REDIS_DATABASE=0
export REDIS_SSL=false
```

**Windows (PowerShell)**
```powershell
$env:REDIS_HOST="127.0.0.1"
$env:REDIS_PORT="6379"
$env:REDIS_PASSWORD="mypassword"
$env:REDIS_DATABASE="0"
$env:REDIS_SSL="false"
```

**Docker Compose**
```yaml
services:
  myapp:
    image: myapp:latest
    environment:
      - REDIS_HOST=redis
      - REDIS_PORT=6379
      - REDIS_PASSWORD=secret
      - REDIS_DATABASE=0
      - REDIS_SSL=false
      - REDIS_CONNECT_TIMEOUT=10000
```

**Kubernetes ConfigMap**
```yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: redis-config
data:
  REDIS_HOST: "redis-service"
  REDIS_PORT: "6379"
  REDIS_PASSWORD: "secret"
  REDIS_DATABASE: "0"
  REDIS_SSL: "false"
```

### 集群模式

适用于生产环境的 Redis 集群部署，提供高可用性和自动故障转移。

#### 环境变量配置

| 环境变量 | 说明 | 示例 | 必填 |
|---------|------|------|------|
| `REDIS_CLUSTER_NODES` | 集群节点列表（逗号分隔） | `node1:6379,node2:6379,node3:6379` | 是 |
| `REDIS_PASSWORD` | 集群密码 | `cluster_password` | 否 |
| `REDIS_USER` | Redis ACL 用户名 | `admin` | 否 |
| `REDIS_SSL` | 是否启用 SSL/TLS | `true` | 否 |
| `REDIS_CONNECT_TIMEOUT` | 连接超时（毫秒） | `10000` | 否 |
| `REDIS_SYNC_TIMEOUT` | 同步操作超时（毫秒） | `5000` | 否 |
| `REDIS_ALLOW_ADMIN` | 是否允许管理命令 | `false` | 否 |
| `REDIS_ABORT_CONNECT` | 连接失败时是否中止 | `true` | 否 |

#### 配置示例

**Linux/Mac**
```bash
export REDIS_CLUSTER_NODES=node1.redis.com:6379,node2.redis.com:6379,node3.redis.com:6379
export REDIS_PASSWORD=cluster_password
export REDIS_SSL=true
export REDIS_CONNECT_TIMEOUT=10000
```

**Windows (PowerShell)**
```powershell
$env:REDIS_CLUSTER_NODES="node1.redis.com:6379,node2.redis.com:6379,node3.redis.com:6379"
$env:REDIS_PASSWORD="cluster_password"
$env:REDIS_SSL="true"
$env:REDIS_CONNECT_TIMEOUT="10000"
```

**Docker Compose**
```yaml
services:
  myapp:
    image: myapp:latest
    environment:
      - REDIS_CLUSTER_NODES=redis-node1:6379,redis-node2:6379,redis-node3:6379
      - REDIS_PASSWORD=cluster_secret
      - REDIS_SSL=false
      - REDIS_CONNECT_TIMEOUT=10000
      - REDIS_SYNC_TIMEOUT=5000
```

**Kubernetes ConfigMap**
```yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: redis-cluster-config
data:
  REDIS_CLUSTER_NODES: "10.0.1.10:6379,10.0.1.11:6379,10.0.1.12:6379"
  REDIS_PASSWORD: "cluster_password"
  REDIS_SSL: "true"
  REDIS_CONNECT_TIMEOUT: "10000"
```

**代码中设置（测试用）**
```csharp
// 单节点模式
Environment.SetEnvironmentVariable("REDIS_HOST", "127.0.0.1");
Environment.SetEnvironmentVariable("REDIS_PORT", "6379");
Environment.SetEnvironmentVariable("REDIS_PASSWORD", "password");

// 集群模式
Environment.SetEnvironmentVariable("REDIS_CLUSTER_NODES", 
    "node1:6379,node2:6379,node3:6379");
Environment.SetEnvironmentVariable("REDIS_PASSWORD", "cluster_password");
```

### 配置模式选择

- **如果设置了 `REDIS_CLUSTER_NODES`**：自动使用集群模式，忽略 `REDIS_HOST` 和 `REDIS_PORT`
- **如果未设置 `REDIS_CLUSTER_NODES`**：使用单节点模式

### 集群模式注意事项

1. **节点格式**：必须是 `host:port` 格式，多个节点用逗号分隔
2. **数据库选择**：Redis 集群不支持多数据库，所有数据存储在 database 0
3. **最小节点数**：建议至少配置 3 个主节点以确保高可用
4. **自动发现**：StackExchange.Redis 会自动发现集群中的所有节点

## 功能特性

- ✅ 支持 Redis 全部数据类型（String、Hash、List、Set、Sorted Set）
- ✅ 支持内存缓存（IMemoryCache）
- ✅ 支持混合缓存模式（Redis + 内存）
- ✅ 支持 Redis 单节点和集群模式
- ✅ 依赖注入集成
- ✅ 环境变量配置
- ✅ 自定义日志处理
- ✅ 缓存回源模式（Cache-Aside Pattern）
- ✅ 支持绝对过期和滑动过期

## 许可证

MIT License

## 相关链接

- 在线文档：http://quickuse.gitee.io/quickuse.caching
- 源码仓库：https://gitee.com/quickuse/Quickuse.Caching