Redis 快速开始

ace-redis 是 ACE Framework 的 Redis 适配组件，特点：

• 纯仓颉实现：基于 std.net TCP 直接实现 RESP2 协议，不依赖 hiredis 等任何 C 库，跨平台部署零摩擦
• 一个 import 完成装配：import ace_redis.* 即触发 RedisComponent 自注册，配置驱动，无 Redis 环境启动不受影响
• 五大能力：客户端命令 API、@Cacheable 分布式缓存后端、分布式锁、Pub/Sub（含事件总线桥接）、分布式限流后端

引入

cjpm.toml 添加依赖：

[dependencies]
  ace_framework = { path = "../../ace-framework/ace-framework" }
  ace_framework_macros = { path = "../../ace-framework/ace-framework-macros" }
  ace_redis = { path = "../../ace-redis" }

业务代码 import：

import ace_framework.*
import ace_framework_macros.*
import ace_redis.*   // 触发 RedisComponent 自注册

配置

配置命名空间 [redis]（application.toml），所有键都有合理默认值：

[redis]
host = "127.0.0.1"
port = 6379
db = 0
password = ""              # 非空时建连自动 AUTH
timeoutMs = 2000           # 命令连接读写超时(订阅连接不受此限)
"pool.max" = 8             # 连接池上限(借满阻塞等待)
"pool.min" = 0             # 预热连接数(0 = 惰性建连)
"pool.idleTimeoutMs" = 30000
cachePrefix = ""           # @Cacheable Redis 键的全局前缀(多应用共享实例时隔离)
pingOnReady = false        # 启动就绪时 PING 探活(fail-fast 需求打开)
"pubsub.bridgeChannels" = ""  # 逗号分隔通道,非空时桥接为应用事件,见 Pub/Sub 篇

键	默认	说明
enabled	true	条件装配开关；关闭后组件整体不装配
host / port / db / password	127.0.0.1 / 6379 / 0 / ""	连接参数；db > 0 建连自动 SELECT，密码非空自动 AUTH
timeoutMs	2000	命令连接读写超时（毫秒），<= 0 不限
pool.max / pool.min / pool.idleTimeoutMs	8 / 0 / 30000	连接池：上限阻塞 / 预热 / 空闲回收
cachePrefix	""	分布式缓存键前缀
pingOnReady	false	onReady 阶段 PING 探活并打印结果
pubsub.bridgeChannels	""	Pub/Sub → 事件总线桥接通道列表

无 Redis 环境也能启动

默认 pool.min = 0 惰性建连，启动期不触碰网络；@Cacheable 命名后端未注册时自动回退进程内缓存。需要"起服务就确认 Redis 可用"的场景设 pingOnReady = true 或 pool.min = 1。

注入使用

@Controller["/redis"]
public class DemoController {
    @Inject
    var redis: RedisClient        // 客户端(命令 API)
    @Inject
    var locks: RedisLockManager   // 分布式锁

    @Get["/kv/:key"]
    public func kvGet(@Param["key"] key: String): String {
        redis.get("demo:" + key) ?? "<none>"
    }

    @Post["/kv/:key"]
    public func kvSet(@Param["key"] key: String, @Query["v!"] v: String): String {
        redis.set("demo:" + key, v)
        "OK ${key}=${v}"
    }
}

五分钟全景

// ① 分布式缓存:结果落 Redis,多实例共享(方法必须返回 String)
@Service
public class PriceService {
    @Cacheable[5000, "redis"]
    public func priceOf(sku: String): String { ... }
}

// ② 分布式锁:跨实例互斥
locks.withLock("job:sync", 3000, {=> doSync(); ()})

// ③ Pub/Sub 桥接:application.toml 配 pubsub.bridgeChannels = "orders" 后
@EventListener
public func onOrder(e: RedisMessage): Unit {
    println("channel=${e.channel} payload=${e.payload}")
}

// ④ 分布式限流:多实例共享限流窗口([ratelimit] store = "redis")

完整可运行示例见 examples/redis-demo。

分层与测试

ace_redis 按子包解耦：ace_redis.resp（RESP2 编解码，零 IO）/ ace_redis.client（连接、池、命令、Pub/Sub、锁，仅触 std.net）/ ace_redis.integration（组件装配）。前两层可完全离线单测；需要真实 Redis 的集成测试在连不上时自动 skip，cjpm test 在无 Redis 环境保持全绿。