@taicode/common-server 3.7.10 → 3.7.12

package/output/index.d.ts

@@ -1,5 +1,6 @@
 export * from './schema/index.js';
 export * from './redis-queue/index.js';
+export * from './redis-cache/index.js';
 export * from './rate-limiter/index.js';
 export * from './context/index.js';
 //# sourceMappingURL=index.d.ts.map

package/output/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../source/index.ts"],"names":[],"mappings":"AACA,cAAc,mBAAmB,CAAA;AACjC,cAAc,wBAAwB,CAAA;AACtC,cAAc,yBAAyB,CAAA;AACvC,cAAc,oBAAoB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../source/index.ts"],"names":[],"mappings":"AACA,cAAc,mBAAmB,CAAA;AACjC,cAAc,wBAAwB,CAAA;AACtC,cAAc,wBAAwB,CAAA;AACtC,cAAc,yBAAyB,CAAA;AACvC,cAAc,oBAAoB,CAAA"}

package/output/index.js

@@ -1,5 +1,6 @@
 // 根 index.ts，统一导出 mock 目录下所有能力
 export * from './schema/index.js';
 export * from './redis-queue/index.js';
+export * from './redis-cache/index.js';
 export * from './rate-limiter/index.js';
 export * from './context/index.js';

package/output/rate-limiter/index.d.ts

@@ -1,4 +1,5 @@
 export * from './types.js';
 export * from './rate-limiter.js';
 export * from './memory-store.js';
+export * from './redis-store.js';
 //# sourceMappingURL=index.d.ts.map

package/output/rate-limiter/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../source/rate-limiter/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAA;AAC1B,cAAc,mBAAmB,CAAA;AACjC,cAAc,mBAAmB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../source/rate-limiter/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAA;AAC1B,cAAc,mBAAmB,CAAA;AACjC,cAAc,mBAAmB,CAAA;AACjC,cAAc,kBAAkB,CAAA"}

package/output/rate-limiter/index.js

@@ -1,3 +1,4 @@
 export * from './types.js';
 export * from './rate-limiter.js';
 export * from './memory-store.js';
+export * from './redis-store.js';

package/output/rate-limiter/redis-store.d.ts

@@ -0,0 +1,45 @@
+import { type RedisClientType } from 'redis';
+import type { RateLimitInfo, RateLimitStore } from './types.js';
+export interface RedisRateLimitStoreOptions {
+    /** 键前缀，避免与其他用途的键混在一起 */
+    prefix?: string;
+    /** Redis 连接串；与 redisClient 二选一 */
+    redisUrl?: string;
+    /** 外部 Redis 客户端；与 redisUrl 二选一 */
+    redisClient?: RedisClientType;
+    /**
+     * Redis 不可用时的降级存储，默认使用进程内 MemoryRateLimitStore。
+     * 刻意不降级为「不限流」：多实例之间不再共享计数已经是能力损失，
+     * 但单实例内仍然能挡住突发，比彻底放行安全得多。
+     */
+    fallback?: RateLimitStore;
+}
+/**
+ * 基于 Redis 的限流存储。
+ *
+ * 与 MemoryRateLimitStore 保持完全相同的「固定窗口」语义：
+ * 窗口在第一次请求时开启，窗口结束时间写入存储并随窗口一起过期。
+ * 区别只在于计数放在 Redis 里，因此多副本部署下 limit 是全局生效的
+ * （进程内计数在 N 个副本下等于把 limit 放大了 N 倍）。
+ *
+ * 读改写之间存在极小的竞态窗口（并发请求可能少计一次），
+ * 对限流来说这种近似完全可接受，换来的是无需 Lua 脚本的简单实现。
+ */
+export declare class RedisRateLimitStore implements RateLimitStore {
+    private readonly prefix;
+    private readonly redis;
+    private readonly isExternalRedis;
+    private readonly fallback;
+    private lastErrorLogTime;
+    constructor(options?: RedisRateLimitStoreOptions);
+    connect(): Promise<void>;
+    disconnect(): void;
+    get(key: string): Promise<RateLimitInfo | null>;
+    set(key: string, info: RateLimitInfo): Promise<void>;
+    delete(key: string): Promise<void>;
+    /** Redis 的键自带过期时间，无需额外清理 */
+    cleanup(): Promise<void>;
+    private buildKey;
+    private logError;
+}
+//# sourceMappingURL=redis-store.d.ts.map

package/output/rate-limiter/redis-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"redis-store.d.ts","sourceRoot":"","sources":["../../source/rate-limiter/redis-store.ts"],"names":[],"mappings":"AAAA,OAAO,EAAgB,KAAK,eAAe,EAAE,MAAM,OAAO,CAAA;AAG1D,OAAO,KAAK,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA;AAE/D,MAAM,WAAW,0BAA0B;IACzC,wBAAwB;IACxB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,kCAAkC;IAClC,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,kCAAkC;IAClC,WAAW,CAAC,EAAE,eAAe,CAAA;IAC7B;;;;OAIG;IACH,QAAQ,CAAC,EAAE,cAAc,CAAA;CAC1B;AAED;;;;;;;;;;GAUG;AACH,qBAAa,mBAAoB,YAAW,cAAc;IACxD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAQ;IAC/B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA+B;IACrD,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAiB;IACjD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAgB;IAEzC,OAAO,CAAC,gBAAgB,CAAI;gBAEhB,OAAO,GAAE,0BAA+B;IAyBvC,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAK9B,UAAU,IAAI,IAAI;IAKZ,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC;IAqB/C,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC;IAgBpD,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAY/C,4BAA4B;IACf,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAIrC,OAAO,CAAC,QAAQ;IAIhB,OAAO,CAAC,QAAQ;CAOjB"}

package/output/rate-limiter/redis-store.js

@@ -0,0 +1,114 @@
+import { createClient } from 'redis';
+import { logger } from '@taicode/common-base';
+import { MemoryRateLimitStore } from './memory-store.js';
+/**
+ * 基于 Redis 的限流存储。
+ *
+ * 与 MemoryRateLimitStore 保持完全相同的「固定窗口」语义：
+ * 窗口在第一次请求时开启，窗口结束时间写入存储并随窗口一起过期。
+ * 区别只在于计数放在 Redis 里，因此多副本部署下 limit 是全局生效的
+ * （进程内计数在 N 个副本下等于把 limit 放大了 N 倍）。
+ *
+ * 读改写之间存在极小的竞态窗口（并发请求可能少计一次），
+ * 对限流来说这种近似完全可接受，换来的是无需 Lua 脚本的简单实现。
+ */
+export class RedisRateLimitStore {
+    prefix;
+    redis = null;
+    isExternalRedis = false;
+    fallback;
+    lastErrorLogTime = 0;
+    constructor(options = {}) {
+        if (options.redisUrl && options.redisClient) {
+            throw new Error('[RedisRateLimitStore] Cannot specify both redisUrl and redisClient');
+        }
+        this.prefix = options.prefix ?? 'rate-limit:';
+        this.fallback = options.fallback ?? new MemoryRateLimitStore();
+        if (options.redisClient) {
+            this.redis = options.redisClient;
+            this.isExternalRedis = true;
+        }
+        else if (options.redisUrl) {
+            this.redis = createClient({
+                url: options.redisUrl,
+                socket: {
+                    connectTimeout: 5_000,
+                    reconnectStrategy: (retries) => Math.min(retries * 200, 3_000),
+                },
+            });
+            this.redis.on('error', (error) => {
+                logger.error('[RedisRateLimitStore] Redis Client Error:', error);
+            });
+        }
+    }
+    async connect() {
+        if (this.redis === null || this.isExternalRedis || this.redis.isOpen)
+            return;
+        await this.redis.connect();
+    }
+    disconnect() {
+        if (this.redis === null || this.isExternalRedis || !this.redis.isOpen)
+            return;
+        this.redis.disconnect();
+    }
+    async get(key) {
+        if (!this.redis?.isReady) {
+            return this.fallback.get(key);
+        }
+        try {
+            const raw = await this.redis.get(this.buildKey(key));
+            if (raw === null)
+                return null;
+            const info = JSON.parse(raw);
+            return {
+                count: info.count,
+                windowStart: new Date(info.windowStart),
+                windowEnd: new Date(info.windowEnd),
+            };
+        }
+        catch (error) {
+            this.logError('get', error);
+            return this.fallback.get(key);
+        }
+    }
+    async set(key, info) {
+        if (!this.redis?.isReady) {
+            return this.fallback.set(key, info);
+        }
+        const ttlSeconds = Math.ceil((info.windowEnd.getTime() - Date.now()) / 1000);
+        if (ttlSeconds <= 0)
+            return;
+        try {
+            await this.redis.set(this.buildKey(key), JSON.stringify(info), { EX: ttlSeconds });
+        }
+        catch (error) {
+            this.logError('set', error);
+            await this.fallback.set(key, info);
+        }
+    }
+    async delete(key) {
+        await this.fallback.delete(key);
+        if (!this.redis?.isReady)
+            return;
+        try {
+            await this.redis.del(this.buildKey(key));
+        }
+        catch (error) {
+            this.logError('delete', error);
+        }
+    }
+    /** Redis 的键自带过期时间，无需额外清理 */
+    async cleanup() {
+        await this.fallback.cleanup?.();
+    }
+    buildKey(key) {
+        return `${this.prefix}${key}`;
+    }
+    logError(operation, error) {
+        const now = Date.now();
+        if (now - this.lastErrorLogTime < 30_000)
+            return;
+        this.lastErrorLogTime = now;
+        logger.error(`[RedisRateLimitStore] ${operation} failed, fallback to memory store:`, error);
+    }
+}

package/output/rate-limiter/redis-store.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=redis-store.test.d.ts.map

package/output/rate-limiter/redis-store.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"redis-store.test.d.ts","sourceRoot":"","sources":["../../source/rate-limiter/redis-store.test.ts"],"names":[],"mappings":""}

package/output/rate-limiter/redis-store.test.js

@@ -0,0 +1,70 @@
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { createRedisClient } from '../redis-cache/redis-cache.js';
+import { RateLimiter } from './rate-limiter.js';
+import { RedisRateLimitStore } from './redis-store.js';
+const REDIS_URL = process.env.REDIS_URL || 'redis://localhost:6379';
+describe('RedisRateLimitStore', () => {
+    let redis;
+    let store;
+    beforeEach(async () => {
+        redis = createRedisClient({ url: REDIS_URL });
+        await redis.connect();
+        store = new RedisRateLimitStore({ prefix: 'test:rate-limit:', redisClient: redis });
+        await store.delete('ip:1.2.3.4');
+    });
+    afterEach(async () => {
+        await store.delete('ip:1.2.3.4');
+        if (redis.isOpen)
+            redis.disconnect();
+    });
+    it('应该在窗口内累计计数', async () => {
+        await store.set('ip:1.2.3.4', {
+            count: 1,
+            windowStart: new Date(),
+            windowEnd: new Date(Date.now() + 60_000),
+        });
+        const info = await store.get('ip:1.2.3.4');
+        expect(info?.count).toBe(1);
+    });
+    it('应该让 RateLimiter 在多实例间共享计数', async () => {
+        const anotherStore = new RedisRateLimitStore({ prefix: 'test:rate-limit:', redisClient: redis });
+        const limiterA = new RateLimiter({ store });
+        const limiterB = new RateLimiter({ store: anotherStore });
+        const config = { limit: 2, window: 60 };
+        expect((await limiterA.checkLimit('ip:1.2.3.4', config)).allowed).toBe(true);
+        // 另一个「实例」能看到前一个实例的计数，因此第三次就被拦下
+        expect((await limiterB.checkLimit('ip:1.2.3.4', config)).allowed).toBe(true);
+        const third = await limiterA.checkLimit('ip:1.2.3.4', config);
+        expect(third.allowed).toBe(false);
+        expect(third.remaining).toBe(0);
+    });
+    it('应该为限流键设置与窗口一致的过期时间', async () => {
+        await store.set('ip:1.2.3.4', {
+            count: 1,
+            windowStart: new Date(),
+            windowEnd: new Date(Date.now() + 30_000),
+        });
+        const ttl = await redis.ttl('test:rate-limit:ip:1.2.3.4');
+        expect(ttl).toBeGreaterThan(0);
+        expect(ttl).toBeLessThanOrEqual(30);
+    });
+    it('窗口已过期时不应写入', async () => {
+        await store.set('ip:1.2.3.4', {
+            count: 1,
+            windowStart: new Date(Date.now() - 120_000),
+            windowEnd: new Date(Date.now() - 60_000),
+        });
+        expect(await redis.get('test:rate-limit:ip:1.2.3.4')).toBeNull();
+    });
+    it('Redis 不可用时应降级到进程内存储而不是放行', async () => {
+        redis.disconnect();
+        const result = await store.get('ip:1.2.3.4');
+        expect(result).toBeNull();
+        await store.set('ip:1.2.3.4', {
+            count: 3,
+            windowStart: new Date(),
+            windowEnd: new Date(Date.now() + 60_000),
+        });
+        expect((await store.get('ip:1.2.3.4'))?.count).toBe(3);
+    });
+});

package/output/redis-cache/index.d.ts

@@ -0,0 +1,4 @@
+export { RedisCache, createRedisClient } from './redis-cache.js';
+export type { RedisCacheL1Options, RedisCacheOptions } from './redis-cache.js';
+export type { RedisClientType } from 'redis';
+//# sourceMappingURL=index.d.ts.map

package/output/redis-cache/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../source/redis-cache/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAA;AAChE,YAAY,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAA;AAE9E,YAAY,EAAE,eAAe,EAAE,MAAM,OAAO,CAAA"}

package/output/redis-cache/index.js

@@ -0,0 +1 @@
+export { RedisCache, createRedisClient } from './redis-cache.js';

package/output/redis-cache/redis-cache.d.ts

@@ -0,0 +1,138 @@
+import { type RedisClientType } from 'redis';
+/**
+ * 进程内一级缓存配置。
+ *
+ * 一级缓存的意义是把「同一个进程内的高频重复读取」压缩到零网络开销：
+ * Redis 的一次 GET 大约 0.2~1ms，而进程内查表是纳秒级。
+ * 鉴权这类每请求都要走的路径，一级缓存带来的收益非常可观。
+ */
+export interface RedisCacheL1Options {
+    /**
+     * 一级缓存容量（条目数），默认 500。
+     * 达到容量后按 LRU 淘汰，因此只需保证「热点」能装下即可。
+     */
+    maxSize?: number;
+    /**
+     * 一级缓存存活时间（毫秒），默认 5000。
+     *
+     * 刻意比二级缓存短一个数量级：跨实例的失效通知依赖 Redis 的键删除，
+     * 一级缓存无法被其他实例感知，只能靠短 TTL 自然过期来收敛。
+     * 这也意味着一级缓存越短，权限变更生效越快。
+     */
+    ttlMs?: number;
+}
+export interface RedisCacheOptions {
+    /**
+     * 键前缀，通常形如 `account:`。
+     * 服务名 + 环境一起放进来可以避免不同服务、不同环境互相污染。
+     */
+    prefix: string;
+    /** Redis 连接串；与 redisClient 二选一 */
+    redisUrl?: string;
+    /** 外部 Redis 客户端（多个缓存共享同一条连接时使用）；与 redisUrl 二选一 */
+    redisClient?: RedisClientType;
+    /** 默认过期时间（秒），默认 300 */
+    defaultTtlSeconds?: number;
+    /**
+     * 空值（null / undefined）的过期时间（秒），默认 10。
+     * 空值必须缓存但必须短，否则「删除后立刻重建」的语义会被缓存彻底挡住（缓存穿透）。
+     */
+    nullTtlSeconds?: number;
+    /** 一级缓存配置；传 false 关闭一级缓存，默认为开启 */
+    l1?: RedisCacheL1Options | false;
+}
+/**
+ * Redis 缓存（可选带进程内一级缓存）。
+ *
+ * 设计原则：
+ * 1. **缓存故障绝不影响业务**：所有方法都不会抛出异常，Redis 不可用时
+ *    自动退化为「不带缓存的直读」或「仅一级缓存」，调用方无需 try/catch。
+ * 2. **一级缓存是可选加速层**：`l1` 关闭时退化为纯 Redis 缓存；
+ *    不传 `redisUrl`/`redisClient` 时退化为纯一级缓存（单测里就这么用）。
+ * 3. **空值也缓存**：防止不存在的 key 每次穿透到数据库。
+ * 4. **TTL 带抖动**：避免同一时刻写入的大量键同时过期，形成瞬时数据库尖峰。
+ */
+export declare class RedisCache {
+    private readonly prefix;
+    private readonly redis;
+    private readonly isExternalRedis;
+    private readonly defaultTtlSeconds;
+    private readonly nullTtlSeconds;
+    private readonly l1;
+    private readonly l1TtlMs;
+    /** 请求合并：同一个 key 的并发 miss 只触发一次 loader，防止缓存击穿 */
+    private readonly inFlight;
+    private lastErrorLogTime;
+    constructor(options: RedisCacheOptions);
+    /** 一级缓存条目数（未开启时为 0） */
+    get size(): number;
+    /** 一级缓存容量（未开启时为 0） */
+    get capacity(): number;
+    /** 二级缓存是否可用。不可用时所有操作都会安静地退化为直读，不会抛错。 */
+    get remoteReady(): boolean;
+    /**
+     * 建立连接。
+     * 外部传入的客户端由持有者负责连接，这里直接返回。
+     */
+    connect(): Promise<void>;
+    /** 断开连接（外部分享的客户端不会被断开） */
+    disconnect(): void;
+    /**
+     * 释放实例资源。
+     *
+     * 只清理进程内的东西，**不会**动 Redis：二级缓存是多实例共享的，
+     * 某个进程退出不应该把别人的缓存一起清掉。
+     */
+    dispose(): Promise<void>;
+    /**
+     * 清空一级缓存（同步），并尽力异步清空二级缓存里该前缀下的全部键。
+     * 二级缓存的清理不阻塞调用方，失败也不影响结果。
+     */
+    clear(): void;
+    get<T>(key: string): Promise<T | null>;
+    set<T>(key: string, value: T, ttlSeconds?: number): Promise<void>;
+    delete(key: string): Promise<void>;
+    /**
+     * 按前缀批量删除。传空字符串表示清空当前缓存实例的全部键。
+     *
+     * 用于「改了一批数据，相关的缓存全部作废」的场景：
+     * 与其维护精细的依赖关系，不如按命名空间整体作废——
+     * 这类写操作本身频率很低，一次 SCAN 的代价可以接受。
+     */
+    deleteByPrefix(prefix: string): Promise<number>;
+    /**
+     * 读缓存，未命中时执行 loader 并回填。
+     *
+     * 并发调用同一个 key 时只会执行一次 loader（请求合并），
+     * 这是鉴权链路上最容易被打穿的场景：热点用户缓存刚失效，
+     * 同一瞬间几十个请求同时涌入。
+     */
+    getOrSet<T>(key: string, loader: () => Promise<T>, ttlSeconds?: number): Promise<T>;
+    /**
+     * 生成最终键。
+     * 注意：调用方传入的 key 里已经带了业务前缀（如 `user:`），
+     * 因此这里只负责拼接实例前缀。
+     */
+    private buildKey;
+    /** 以下两个方法接收「已经拼好前缀的最终键」，供 getOrSet 避免重复拼前缀 */
+    private getByCacheKey;
+    private setByCacheKey;
+    private getLocal;
+    private setLocal;
+    private resolveTtl;
+    private getLogPrefix;
+    private logError;
+}
+/**
+ * 创建 Redis 客户端。
+ *
+ * 与 RedisQueueCommon 保持同样的连接策略，但补了两点：
+ * - 连接超时受限，避免 Redis 不可达时启动流程被拖住；
+ * - 重连采用固定上限的退避，避免无意义的密集重试。
+ */
+export declare function createRedisClient(options: {
+    url: string;
+    logPrefix?: string;
+    connectTimeoutMs?: number;
+}): RedisClientType;
+//# sourceMappingURL=redis-cache.d.ts.map

package/output/redis-cache/redis-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"redis-cache.d.ts","sourceRoot":"","sources":["../../source/redis-cache/redis-cache.ts"],"names":[],"mappings":"AACA,OAAO,EAAgB,KAAK,eAAe,EAAE,MAAM,OAAO,CAAA;AAE1D;;;;;;GAMG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB;;;;;;OAMG;IACH,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AAED,MAAM,WAAW,iBAAiB;IAChC;;;OAGG;IACH,MAAM,EAAE,MAAM,CAAA;IACd,kCAAkC;IAClC,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,kDAAkD;IAClD,WAAW,CAAC,EAAE,eAAe,CAAA;IAC7B,uBAAuB;IACvB,iBAAiB,CAAC,EAAE,MAAM,CAAA;IAC1B;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,kCAAkC;IAClC,EAAE,CAAC,EAAE,mBAAmB,GAAG,KAAK,CAAA;CACjC;AAaD;;;;;;;;;;GAUG;AACH,qBAAa,UAAU;IACrB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAQ;IAC/B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA+B;IACrD,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAiB;IACjD,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAQ;IAC1C,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAQ;IAEvC,OAAO,CAAC,QAAQ,CAAC,EAAE,CAA0B;IAC7C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAQ;IAEhC,gDAAgD;IAChD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAsC;IAE/D,OAAO,CAAC,gBAAgB,CAAI;gBAEhB,OAAO,EAAE,iBAAiB;IA6BtC,uBAAuB;IACvB,IAAW,IAAI,IAAI,MAAM,CAExB;IAED,sBAAsB;IACtB,IAAW,QAAQ,IAAI,MAAM,CAE5B;IAED,wCAAwC;IACxC,IAAW,WAAW,IAAI,OAAO,CAEhC;IAED;;;OAGG;IACU,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAOrC,0BAA0B;IACnB,UAAU,IAAI,IAAI;IAOzB;;;;;OAKG;IACU,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAMrC;;;OAGG;IACI,KAAK,IAAI,IAAI;IAQP,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC;IAItC,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIjE,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAa/C;;;;;;OAMG;IACU,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAwB5D;;;;;;OAMG;IACU,QAAQ,CAAC,CAAC,EACrB,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACxB,UAAU,CAAC,EAAE,MAAM,GAClB,OAAO,CAAC,CAAC,CAAC;IA6Bb;;;;OAIG;IACH,OAAO,CAAC,QAAQ;IAIhB,8CAA8C;YAChC,aAAa;YAmBb,aAAa;IAY3B,OAAO,CAAC,QAAQ;IAahB,OAAO,CAAC,QAAQ;IAUhB,OAAO,CAAC,UAAU;IAalB,OAAO,CAAC,YAAY;IAIpB,OAAO,CAAC,QAAQ;CAOjB;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE;IACzC,GAAG,EAAE,MAAM,CAAA;IACX,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,gBAAgB,CAAC,EAAE,MAAM,CAAA;CAC1B,GAAG,eAAe,CAkBlB"}

package/output/redis-cache/redis-cache.js

@@ -0,0 +1,289 @@
+import { LruCache, logger } from '@taicode/common-base';
+import { createClient } from 'redis';
+/** 单次日志的最小间隔（毫秒），避免 Redis 故障时刷爆日志 */
+const ERROR_LOG_INTERVAL_MS = 30_000;
+/** 删除键时的批大小 */
+const SCAN_COUNT = 200;
+/**
+ * Redis 缓存（可选带进程内一级缓存）。
+ *
+ * 设计原则：
+ * 1. **缓存故障绝不影响业务**：所有方法都不会抛出异常，Redis 不可用时
+ *    自动退化为「不带缓存的直读」或「仅一级缓存」，调用方无需 try/catch。
+ * 2. **一级缓存是可选加速层**：`l1` 关闭时退化为纯 Redis 缓存；
+ *    不传 `redisUrl`/`redisClient` 时退化为纯一级缓存（单测里就这么用）。
+ * 3. **空值也缓存**：防止不存在的 key 每次穿透到数据库。
+ * 4. **TTL 带抖动**：避免同一时刻写入的大量键同时过期，形成瞬时数据库尖峰。
+ */
+export class RedisCache {
+    prefix;
+    redis = null;
+    isExternalRedis = false;
+    defaultTtlSeconds;
+    nullTtlSeconds;
+    l1;
+    l1TtlMs;
+    /** 请求合并：同一个 key 的并发 miss 只触发一次 loader，防止缓存击穿 */
+    inFlight = new Map();
+    lastErrorLogTime = 0;
+    constructor(options) {
+        if (!options.prefix) {
+            throw new Error('[RedisCache] prefix is required');
+        }
+        if (options.redisUrl && options.redisClient) {
+            throw new Error('[RedisCache] Cannot specify both redisUrl and redisClient');
+        }
+        this.prefix = options.prefix;
+        this.defaultTtlSeconds = options.defaultTtlSeconds ?? 300;
+        this.nullTtlSeconds = options.nullTtlSeconds ?? 10;
+        if (options.l1 !== false) {
+            const l1Options = options.l1 ?? {};
+            this.l1TtlMs = l1Options.ttlMs ?? 5_000;
+            this.l1 = new LruCache(l1Options.maxSize ?? 500);
+        }
+        else {
+            this.l1 = null;
+            this.l1TtlMs = 0;
+        }
+        if (options.redisClient) {
+            this.redis = options.redisClient;
+            this.isExternalRedis = true;
+        }
+        else if (options.redisUrl) {
+            this.redis = createRedisClient({ url: options.redisUrl, logPrefix: this.getLogPrefix() });
+        }
+    }
+    /** 一级缓存条目数（未开启时为 0） */
+    get size() {
+        return this.l1?.size ?? 0;
+    }
+    /** 一级缓存容量（未开启时为 0） */
+    get capacity() {
+        return this.l1?.capacity ?? 0;
+    }
+    /** 二级缓存是否可用。不可用时所有操作都会安静地退化为直读，不会抛错。 */
+    get remoteReady() {
+        return this.redis === null || this.redis.isReady;
+    }
+    /**
+     * 建立连接。
+     * 外部传入的客户端由持有者负责连接，这里直接返回。
+     */
+    async connect() {
+        if (this.redis === null || this.isExternalRedis)
+            return;
+        if (this.redis.isOpen)
+            return;
+        await this.redis.connect();
+    }
+    /** 断开连接（外部分享的客户端不会被断开） */
+    disconnect() {
+        if (this.redis === null || this.isExternalRedis)
+            return;
+        if (!this.redis.isOpen)
+            return;
+        this.redis.disconnect();
+    }
+    /**
+     * 释放实例资源。
+     *
+     * 只清理进程内的东西，**不会**动 Redis：二级缓存是多实例共享的，
+     * 某个进程退出不应该把别人的缓存一起清掉。
+     */
+    async dispose() {
+        this.l1?.clear();
+        this.inFlight.clear();
+        this.disconnect();
+    }
+    /**
+     * 清空一级缓存（同步），并尽力异步清空二级缓存里该前缀下的全部键。
+     * 二级缓存的清理不阻塞调用方，失败也不影响结果。
+     */
+    clear() {
+        this.l1?.clear();
+        if (this.redis?.isReady) {
+            void this.deleteByPrefix('');
+        }
+    }
+    async get(key) {
+        return await this.getByCacheKey(this.buildKey(key));
+    }
+    async set(key, value, ttlSeconds) {
+        await this.setByCacheKey(this.buildKey(key), value, ttlSeconds);
+    }
+    async delete(key) {
+        const cacheKey = this.buildKey(key);
+        this.l1?.delete(cacheKey);
+        if (!this.redis?.isReady)
+            return;
+        try {
+            await this.redis.del(cacheKey);
+        }
+        catch (error) {
+            this.logError('delete', cacheKey, error);
+        }
+    }
+    /**
+     * 按前缀批量删除。传空字符串表示清空当前缓存实例的全部键。
+     *
+     * 用于「改了一批数据，相关的缓存全部作废」的场景：
+     * 与其维护精细的依赖关系，不如按命名空间整体作废——
+     * 这类写操作本身频率很低，一次 SCAN 的代价可以接受。
+     */
+    async deleteByPrefix(prefix) {
+        this.l1?.clear();
+        if (!this.redis?.isReady)
+            return 0;
+        const match = `${this.prefix}${prefix}*`;
+        let deleted = 0;
+        let cursor = '0';
+        try {
+            do {
+                const result = await this.redis.scan(cursor, { MATCH: match, COUNT: SCAN_COUNT });
+                cursor = result.cursor;
+                if (result.keys.length > 0) {
+                    deleted += await this.redis.del(result.keys);
+                }
+            } while (cursor !== '0');
+        }
+        catch (error) {
+            this.logError('deleteByPrefix', match, error);
+        }
+        return deleted;
+    }
+    /**
+     * 读缓存，未命中时执行 loader 并回填。
+     *
+     * 并发调用同一个 key 时只会执行一次 loader（请求合并），
+     * 这是鉴权链路上最容易被打穿的场景：热点用户缓存刚失效，
+     * 同一瞬间几十个请求同时涌入。
+     */
+    async getOrSet(key, loader, ttlSeconds) {
+        const cacheKey = this.buildKey(key);
+        const local = this.getLocal(cacheKey);
+        if (local !== undefined)
+            return local;
+        const remote = await this.getByCacheKey(cacheKey);
+        if (remote !== null)
+            return remote;
+        const pending = this.inFlight.get(cacheKey);
+        if (pending !== undefined)
+            return await pending;
+        const task = (async () => {
+            const value = await loader();
+            await this.setByCacheKey(cacheKey, value, ttlSeconds);
+            return value;
+        })();
+        this.inFlight.set(cacheKey, task);
+        try {
+            return await task;
+        }
+        finally {
+            if (this.inFlight.get(cacheKey) === task) {
+                this.inFlight.delete(cacheKey);
+            }
+        }
+    }
+    /**
+     * 生成最终键。
+     * 注意：调用方传入的 key 里已经带了业务前缀（如 `user:`），
+     * 因此这里只负责拼接实例前缀。
+     */
+    buildKey(key) {
+        return `${this.prefix}${key}`;
+    }
+    /** 以下两个方法接收「已经拼好前缀的最终键」，供 getOrSet 避免重复拼前缀 */
+    async getByCacheKey(cacheKey) {
+        const local = this.getLocal(cacheKey);
+        if (local !== undefined)
+            return local;
+        if (!this.redis?.isReady)
+            return null;
+        try {
+            const raw = await this.redis.get(cacheKey);
+            if (raw === null)
+                return null;
+            const value = JSON.parse(raw);
+            this.setLocal(cacheKey, value);
+            return value;
+        }
+        catch (error) {
+            this.logError('get', cacheKey, error);
+            return null;
+        }
+    }
+    async setByCacheKey(cacheKey, value, ttlSeconds) {
+        this.setLocal(cacheKey, value);
+        if (!this.redis?.isReady)
+            return;
+        try {
+            await this.redis.set(cacheKey, JSON.stringify(value), { EX: this.resolveTtl(value, ttlSeconds) });
+        }
+        catch (error) {
+            this.logError('set', cacheKey, error);
+        }
+    }
+    getLocal(cacheKey) {
+        if (this.l1 === null)
+            return undefined;
+        const entry = this.l1.get(cacheKey);
+        if (entry === undefined)
+            return undefined;
+        if (entry.expiredTime < Date.now()) {
+            this.l1.delete(cacheKey);
+            return undefined;
+        }
+        return entry.value;
+    }
+    setLocal(cacheKey, value) {
+        if (this.l1 === null)
+            return;
+        // 空值不写入一级缓存：一级缓存无法被其他实例失效，
+        // 让「不存在」在本地停留可能会显著拖慢新建资源的可见性。
+        if (value === null || value === undefined)
+            return;
+        this.l1.set(cacheKey, { value, expiredTime: Date.now() + this.l1TtlMs });
+    }
+    resolveTtl(value, ttlSeconds) {
+        if (value === null || value === undefined) {
+            return this.nullTtlSeconds;
+        }
+        const base = ttlSeconds ?? this.defaultTtlSeconds;
+        // ±10% 抖动：避免大批量键在同毫秒写入后在同一个时刻集体过期
+        const jitter = base * (0.9 + Math.random() * 0.2);
+        return Math.max(1, Math.round(jitter));
+    }
+    getLogPrefix() {
+        return `RedisCache:${this.prefix}`;
+    }
+    logError(operation, key, error) {
+        const now = Date.now();
+        if (now - this.lastErrorLogTime < ERROR_LOG_INTERVAL_MS)
+            return;
+        this.lastErrorLogTime = now;
+        logger.error(`[${this.getLogPrefix()}] ${operation} failed, cache degraded to pass-through:`, key, error);
+    }
+}
+/**
+ * 创建 Redis 客户端。
+ *
+ * 与 RedisQueueCommon 保持同样的连接策略，但补了两点：
+ * - 连接超时受限，避免 Redis 不可达时启动流程被拖住；
+ * - 重连采用固定上限的退避，避免无意义的密集重试。
+ */
+export function createRedisClient(options) {
+    const logPrefix = options.logPrefix ?? 'Redis';
+    const client = createClient({
+        url: options.url,
+        socket: {
+            connectTimeout: options.connectTimeoutMs ?? 5_000,
+            reconnectStrategy: (retries) => Math.min(retries * 200, 3_000),
+        },
+    });
+    client.on('error', (error) => {
+        logger.error(`[${logPrefix}] Redis Client Error:`, error);
+    });
+    // 带 socket 配置调用 createClient 时 TS 会把 RESP 推断成联合类型，
+    // 与默认的 RESP2 客户端类型不等价，这里收敛回公开的 RedisClientType。
+    return client;
+}

package/output/redis-cache/redis-cache.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=redis-cache.test.d.ts.map

package/output/redis-cache/redis-cache.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"redis-cache.test.d.ts","sourceRoot":"","sources":["../../source/redis-cache/redis-cache.test.ts"],"names":[],"mappings":""}

package/output/redis-cache/redis-cache.test.js

@@ -0,0 +1,156 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { RedisCache, createRedisClient } from './redis-cache.js';
+const REDIS_URL = process.env.REDIS_URL || 'redis://localhost:6379';
+describe('RedisCache', () => {
+    describe('纯一级缓存（未配置 Redis）', () => {
+        let cache;
+        beforeEach(() => {
+            cache = new RedisCache({ prefix: 'test-l1-only:', l1: { maxSize: 2, ttlMs: 1000 } });
+        });
+        afterEach(async () => {
+            await cache.dispose();
+        });
+        it('应该在未配置 Redis 时退化为纯进程内缓存', async () => {
+            await cache.set('a', { value: 1 });
+            expect(await cache.get('a')).toEqual({ value: 1 });
+            expect(cache.size).toBe(1);
+            expect(cache.capacity).toBe(2);
+        });
+        it('应该按 LRU 容量淘汰', async () => {
+            await cache.set('a', 1);
+            await cache.set('b', 2);
+            await cache.get('a'); // 让 a 变成最近使用
+            await cache.set('c', 3);
+            expect(await cache.get('b')).toBeNull();
+            expect(await cache.get('a')).toBe(1);
+            expect(await cache.get('c')).toBe(3);
+        });
+        it('一级缓存过期后应该重新读取', async () => {
+            await cache.set('a', 1);
+            expect(await cache.get('a')).toBe(1);
+            vi.spyOn(Date, 'now').mockReturnValue(Date.now() + 60_000);
+            expect(await cache.get('a')).toBeNull();
+            vi.restoreAllMocks();
+        });
+        it('clear 应该清空一级缓存', async () => {
+            await cache.set('a', 1);
+            cache.clear();
+            expect(cache.size).toBe(0);
+            expect(await cache.get('a')).toBeNull();
+        });
+        it('getOrSet 应该只在未命中时执行 loader', async () => {
+            const loader = vi.fn(async () => ({ value: 42 }));
+            expect(await cache.getOrSet('key', loader)).toEqual({ value: 42 });
+            expect(await cache.getOrSet('key', loader)).toEqual({ value: 42 });
+            expect(loader).toHaveBeenCalledTimes(1);
+        });
+        it('getOrSet 应该与 get/set/delete 共用同一份缓存', async () => {
+            await cache.set('shared', { value: 1 });
+            const loader = vi.fn(async () => ({ value: 2 }));
+            expect(await cache.getOrSet('shared', loader)).toEqual({ value: 1 });
+            expect(loader).not.toHaveBeenCalled();
+            await cache.delete('shared');
+            expect(await cache.getOrSet('shared', loader)).toEqual({ value: 2 });
+            expect(loader).toHaveBeenCalledTimes(1);
+        });
+        it('并发 getOrSet 应该只执行一次 loader', async () => {
+            let release;
+            const gate = new Promise(resolve => { release = resolve; });
+            const loader = vi.fn(async () => {
+                await gate;
+                return 7;
+            });
+            const tasks = [cache.getOrSet('key', loader), cache.getOrSet('key', loader), cache.getOrSet('key', loader)];
+            release();
+            expect(await Promise.all(tasks)).toEqual([7, 7, 7]);
+            expect(loader).toHaveBeenCalledTimes(1);
+        });
+    });
+    describe('二级缓存（Redis）', () => {
+        let redis;
+        let cache;
+        let other;
+        beforeEach(async () => {
+            redis = createRedisClient({ url: REDIS_URL });
+            await redis.connect();
+            cache = new RedisCache({ prefix: 'test:redis-cache:', redisClient: redis, defaultTtlSeconds: 60 });
+            // 另一个实例模拟「另一个进程」，一级缓存不共享，二级缓存共享
+            other = new RedisCache({ prefix: 'test:redis-cache:', redisClient: redis, defaultTtlSeconds: 60 });
+            await cache.deleteByPrefix('');
+        });
+        afterEach(async () => {
+            await cache.deleteByPrefix('');
+            await cache.dispose();
+            await other.dispose();
+            if (redis.isOpen)
+                redis.disconnect();
+        });
+        it('应该通过 Redis 让不同实例共享缓存', async () => {
+            await cache.set('shared', { hello: 'world' });
+            expect(await other.get('shared')).toEqual({ hello: 'world' });
+        });
+        it('Redis 中的键名应该只拼接一次前缀', async () => {
+            await cache.getOrSet('user:1', async () => 'ok');
+            expect(await redis.keys('test:redis-cache:*')).toEqual(['test:redis-cache:user:1']);
+            expect(await other.get('user:1')).toBe('ok');
+        });
+        it('应该缓存空值以防止穿透', async () => {
+            await cache.set('missing', null);
+            expect(await other.get('missing')).toBeNull();
+            expect(await redis.get('test:redis-cache:missing')).toBe('null');
+        });
+        it('空值不应该写入一级缓存', async () => {
+            await cache.set('missing', null);
+            expect(cache.size).toBe(0);
+        });
+        it('deleteByPrefix 应该只删除本前缀下的键', async () => {
+            const otherPrefix = new RedisCache({ prefix: 'test:other-prefix:', redisClient: redis });
+            await otherPrefix.deleteByPrefix('');
+            await cache.set('user:1', 1);
+            await cache.set('user:2', 2);
+            await cache.set('role:1', 3);
+            await otherPrefix.set('user:1', 99);
+            const deleted = await cache.deleteByPrefix('user:');
+            expect(deleted).toBe(2);
+            expect(await cache.get('user:1')).toBeNull();
+            expect(await cache.get('role:1')).toBe(3);
+            expect(await otherPrefix.get('user:1')).toBe(99);
+            await otherPrefix.deleteByPrefix('');
+            await otherPrefix.dispose();
+        });
+        it('deleteByPrefix 应该同时清空一级缓存', async () => {
+            await cache.set('user:1', 1);
+            expect(cache.size).toBe(1);
+            await cache.deleteByPrefix('user:');
+            expect(cache.size).toBe(0);
+            expect(await cache.get('user:1')).toBeNull();
+        });
+        it('clear 应该同时清理一二级缓存', async () => {
+            await cache.set('user:1', 1);
+            cache.clear();
+            expect(cache.size).toBe(0);
+            // clear 内部的二级缓存清理是异步的，等待其落地
+            await vi.waitFor(async () => {
+                expect(await redis.get('test:redis-cache:user:1')).toBeNull();
+            });
+        });
+        it('delete 应该同时删除一二级缓存', async () => {
+            await cache.set('user:1', 1);
+            await other.get('user:1'); // 让另一个实例也有一级缓存
+            await cache.delete('user:1');
+            expect(await cache.get('user:1')).toBeNull();
+            expect(await redis.get('test:redis-cache:user:1')).toBeNull();
+        });
+        it('Redis 不可用时应安静降级而不抛错', async () => {
+            redis.disconnect();
+            await expect(cache.get('anything')).resolves.toBeNull();
+            await expect(cache.set('anything', 1)).resolves.toBeUndefined();
+            await expect(cache.delete('anything')).resolves.toBeUndefined();
+            await expect(cache.deleteByPrefix('')).resolves.toBe(0);
+        });
+        it('Redis 不可用时 getOrSet 仍应返回 loader 结果', async () => {
+            redis.disconnect();
+            await expect(cache.getOrSet('k', async () => 'value')).resolves.toBe('value');
+        });
+    });
+});

package/output/schema/index.d.ts

@@ -19,7 +19,7 @@ export declare function queryParamsSchema<F extends ZodType, E extends ZodEnum>(
             ASC: "ASC";
             DESC: "DESC";
         }>;
-    }, z.core.$strip>> | z.ZodUndefined;
+    }, z.core.$strip>> | z.ZodOptional<z.ZodUndefined>;
 }, z.core.$strip>;
 /**
  * 查询结果 Schema
@@ -56,7 +56,7 @@ export declare function listResultSchema<T extends ZodType>(t: T): z.ZodObject<{
  */
 export declare function rangeQueryParamsSchema<F extends ZodType, E extends ZodEnum>(f: F, e?: E): z.ZodObject<{
     filter: F;
-    sort: z.ZodUndefined | z.ZodArray<z.ZodObject<{
+    sort: z.ZodOptional<z.ZodUndefined> | z.ZodArray<z.ZodObject<{
         key: E;
         order: z.ZodEnum<{
             ASC: "ASC";
@@ -117,7 +117,7 @@ export declare function fuzzQueryParamsSchema<F extends ZodType, E extends ZodEn
         size: z.ZodNumber;
         index: z.ZodNumber;
     }, z.core.$strip>;
-    sort: z.ZodUndefined | z.ZodArray<z.ZodObject<{
+    sort: z.ZodOptional<z.ZodUndefined> | z.ZodArray<z.ZodObject<{
         key: E;
         order: z.ZodEnum<{
             ASC: "ASC";

package/output/schema/index.js

@@ -33,7 +33,7 @@ export function queryParamsSchema(f, e) {
     return z.object({
         filter: f.describe('过滤条件'),
         paging: _pagingSchema().describe('分页参数'),
-        sort: e ? _sortSchema(e).describe('排序条件') : z.undefined(),
+        sort: e ? _sortSchema(e).describe('排序条件') : z.undefined().optional().describe('排序条件'),
     });
 }
 /**
@@ -78,7 +78,7 @@ export function listResultSchema(t) {
 export function rangeQueryParamsSchema(f, e) {
     return z.object({
         filter: f.describe('过滤条件'),
-        sort: e ? _sortSchema(e).describe('排序条件') : z.undefined(),
+        sort: e ? _sortSchema(e).describe('排序条件') : z.undefined().optional().describe('排序条件'),
         range: z.tuple([z.iso.datetime(), z.iso.datetime()]).describe('时间范围，格式为 [开始时间, 结束时间]'),
     });
 }
@@ -131,7 +131,7 @@ export function fuzzQueryParamsSchema(f, e) {
     return z.object({
         filter: f.describe('模糊搜索关键词，长度1-50字符'),
         paging: _pagingSchema().describe('分页参数'),
-        sort: e ? _sortSchema(e).describe('排序条件') : z.undefined(),
+        sort: e ? _sortSchema(e).describe('排序条件') : z.undefined().optional().describe('排序条件'),
     });
 }
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@taicode/common-server",
-  "version": "3.7.10",
+  "version": "3.7.12",
   "author": "Alain",
   "license": "ISC",
   "description": "",
@@ -27,7 +27,7 @@
     "fastify": "^5.5.0",
     "redis": "^5.11.0",
     "zod": "^4.1.0",
-    "@taicode/common-base": "^3.7.10"
+    "@taicode/common-base": "^3.7.12"
   },
   "devDependencies": {
     "@types/node": "^22.19.13",
@@ -35,7 +35,7 @@
     "redis": "^5.11.0",
     "vitest": "^3.2.4",
     "zod": "^4.3.6",
-    "@taicode/common-base": "^3.7.10"
+    "@taicode/common-base": "^3.7.12"
   },
   "scripts": {
     "test": "vitest run",