PlumX.Core.Caching 1.0.0-preview.9

PlumX.Core.Caching

NuGet 包 ID：PlumX.Core.Caching

定位

PlumX.Core.Caching 提供可插拔的内存缓存和 Redis 缓存能力，并暴露 Redis 数据库、原子计数、Lua 脚本和锁等基础接口。Redis 多实例限流位于独立的 PlumX.Core.Caching.RateLimiting 项目。

目标框架与依赖

• 目标框架：net8.0
• 项目引用：Common
• 主要依赖：StackExchange.Redis、Microsoft.Extensions.Options.ConfigurationExtensions、ASP.NET Core shared framework

接入方式

builder.AddCaching();

也可以调用 services.AddCaching(options => ...) 选择或扩展缓存 provider。默认扩展注册内存和 Redis provider；使用 Redis 限流时必须先完成 Caching 注册。

配置

主要配置节为源码默认读取的 Cache:Redis 和 Cache:Memory（配置键大小写不敏感）。Redis 支持多个命名连接，每个 provider 通过 RedisName 区分；数据库编号通过 Redis DB 配置选择。连接字符串、用户名和密码应由环境变量或配置中心注入。

主要 API

• ICachingProvider/IMemoryCachingProvider：统一缓存读写契约。
• IRedisCachingProvider：字符串、Hash、集合、SortedSet、脚本和锁操作。
• IRedisDatabaseProvider：按名称获取 Redis database。
• IRedisAtomicStore：原子递增并设置过期时间。
• IRedisWindowCounterStore：可选地返回计数和 TTL，供分布式限流使用。

边界与运维说明

内存 provider 支持 TTL、容量限制、前缀删除和读写深拷贝；它只适用于单实例。Redis provider 和连接通常为单例，配置变更及连接替换必须纳入应用生命周期。Redis 诊断仅使用 .NET 8 shared framework 提供的 Microsoft.Extensions.Logging 抽象：未注册 ILoggerFactory 时保持无日志行为，不需要引用 PlumX.Core.Logging、PlumX.Core.Observability 或 PlumX.Core.Platform。旧的未编译 provider 文件不属于当前默认实现，文档不应按旧接口接入。

Redis Configuration Validation

Cache:Redis is optional. A Redis provider is registered only when that configuration section exists. When Redis is first used, configure either a non-empty DBConfig:Configuration connection string or at least one DBConfig:Endpoints item with a non-empty Host and a Port from 1 through 65535. Redis passwords are optional and should be supplied through environment variables or a configuration center.

配置中心中的完整缓存配置

AddCaching 从兼容静态配置读取 Cache:Redis 和 Cache:Memory。配置键大小写不敏感，JSON 中可以使用其他大小写写法；远程配置中心中的同名节会覆盖本地值。

{
  "Cache": {
    "Redis": {
      "RedisName": "DefaultRedis",
      "DBConfig": {
        "Password": "由密钥管理服务提供",
        "Database": 0,
        "ConnectionTimeout": 5000,
        "SyncTimeout": 5000,
        "AllowAdmin": false,
        "Configuration": "由密钥管理服务提供",
        "AbortOnConnectFail": false,
        "Endpoints": [{ "Host": "redis.internal", "Port": 6379 }]
      }
    },
    "Memory": {
      "InMemoryName": "DefaultInMemory",
      "MemoryConfig": {
        "SizeLimit": 10000,
        "ExpirationScanFrequency": 60,
        "EnableReadDeepClone": true,
        "EnableWriteDeepClone": false
      }
    }
  }
}

RedisName 默认 DefaultRedis；DBConfig:Password 默认空，Database 默认 0，ConnectionTimeout/SyncTimeout 默认 5000 毫秒，AllowAdmin 和 AbortOnConnectFail 默认 false，Configuration 默认空，Endpoints 默认空列表。首次使用 Redis 时，Configuration 必须非空，或至少提供一个 Host 非空且 Port 在 1..65535 的 endpoint。InMemoryName 默认 DefaultInMemory；SizeLimit 默认空，ExpirationScanFrequency 默认 60 秒，读取深拷贝默认开启，写入深拷贝默认关闭。完整的 ConfigCenter 加载顺序见 配置中心文档。

完整使用示例

缓存注册、命名 Redis 与业务服务注入方式见 模块使用示例。完整可运行的缓存读写与 Redis 限流接口见 PlumX.Demo.Redis。