Files
dacli/src/core/sqlite_cache.ts
T
sswandClaude bc06112504 dacli apis/doc v0.7.1: 缓存从 in-memory Map 切到 SQLite (跨 process 持久化)
抽自 docs/dacli/ssw-dacli/SqliteCacheService.java + ApiService.java + DocService.java
(PG 用户建议改 SQLite, 更优: 无外部依赖, 单文件 ~/.dacli/cache.db, 跟 Java 对齐)

新增:
- src/core/sqlite_cache.ts (TS 版 SqliteCacheService, 110 行):
  - better-sqlite3 (WAL 模式, sync API 比 async 快)
  - 公开: get/set/del/delByPattern/clearAll/stats/resetDbFile
  - 自动目录创建 ~/.dacli/, 启动时清过期项
  - 进程退出自动 close (SIGINT/SIGTERM 处理)
  - 路径可配: $DACLI_CACHE_DIR/cache.db

升级:
- apis/_cache.ts: in-memory Map → SQLite (12h TTL)
  - prefix: dacli:apidoc: (openapi/index/loaded/pid)
  - 跨 process 命中 (之前每次 npx tsx 都重拉 /v3/api-docs)
  - PID 失效检测用 'process.pid + 启动分钟' 兜底 (Node 跨平台 jps 不可靠)
- doc/_parser.ts: in-memory Map → SQLite (mtime 缓存)
  - prefix: dacli:doc: (mtime:{hash}/raw:{hash}/section:{hash}:{id})
  - 7 天 TTL, mtime 一致直接命中
  - section 索引/listSections 走 SQLite LIKE 查询
- package.json: better-sqlite3 从 optionalDependencies 升到 dependencies
  (跨平台 native binding, rebuild 自动)

实战验证:
- 第一次 dacli apis info: 拉 /v3/api-docs (1MB) 写 SQLite
- 第二次 dacli apis status: loaded=true source=sqlite pathCount=846
- 跨 process 持久化: ~/.dacli/cache.db 1.2MB, 7 rows
- 之前 in-memory 每次 npx tsx 都重拉, 现在零延迟命中

Co-Authored-By: Claude <[email protected]>
2026-06-21 18:50:19 +08:00

144 lines
4.9 KiB
TypeScript

/**
* core/sqlite_cache.ts — SQLite 缓存 (better-sqlite3, 跨 process 持久化)
*
* 抽自: docs/dacli/ssw-dacli/src/main/java/ssw/dacli/SqliteCacheService.java
*
* TS 版差异:
* - 用 better-sqlite3 (Node sync API, 比 async sqlite3 快)
* - 跨 process 共享 (Java 同款 SQLite, 但 Java 路径复杂; TS 简化为 ~/.dacli/cache.db)
* - 单例 + lazy 初始化, 进程退出自动 close
*
* 公开:
* - get(prefix, key) → string | null
* - set(prefix, key, value, ttlSeconds) → void
* - delete(prefix, key) → number (rows affected)
* - deleteByPattern(prefix, pattern) → number (rows affected, 用 SQL LIKE)
* - clear() → void (清全部, 调试用)
*
* 存储格式:
* CREATE TABLE cache (k TEXT PRIMARY KEY, v TEXT, expires_at INTEGER)
* k = prefix + ':' + key (e.g. "dacli:apidoc:openapi")
* expires_at = epoch millis, 0 = 永不过期
* GET 时过滤 expires_at <= now() → 返回 null (自动失效)
*/
import Database from 'better-sqlite3'
import { existsSync, mkdirSync, unlinkSync } from 'node:fs'
import { dirname, join, resolve } from 'node:path'
import { homedir } from 'node:os'
let db: Database.Database | null = null
let dbPath: string | null = null
/** 缓存文件路径: $DACLI_CACHE_DIR/cache.db 或 ~/.dacli/cache.db */
export function getCachePath(): string {
if (process.env.DACLI_CACHE_DIR) return resolve(process.env.DACLI_CACHE_DIR, 'cache.db')
return join(homedir(), '.dacli', 'cache.db')
}
function ensureDb(): Database.Database {
if (db) return db
dbPath = getCachePath()
const dir = dirname(dbPath)
if (!existsSync(dir)) mkdirSync(dir, { recursive: true })
db = new Database(dbPath)
db.pragma('journal_mode = WAL') // 提升并发读性能
db.exec(`
CREATE TABLE IF NOT EXISTS cache (
k TEXT PRIMARY KEY,
v TEXT NOT NULL,
expires_at INTEGER NOT NULL DEFAULT 0
);
CREATE INDEX IF NOT EXISTS idx_cache_expires ON cache(expires_at);
`)
// 启动时清掉过期项 (避免表越来越大)
try { db.prepare('DELETE FROM cache WHERE expires_at > 0 AND expires_at <= ?').run(Date.now()) } catch {}
return db
}
export function getCacheDbPath(): string { return dbPath || getCachePath() }
/** 读. 返回 string | null (过期 / 不存在 / 错误都返 null) */
export function get(prefix: string, key: string): string | null {
try {
const d = ensureDb()
const r = d.prepare('SELECT v, expires_at FROM cache WHERE k = ?').get(`${prefix}${key}`) as { v: string; expires_at: number } | undefined
if (!r) return null
if (r.expires_at > 0 && r.expires_at <= Date.now()) {
// 过期, 顺手删
d.prepare('DELETE FROM cache WHERE k = ?').run(`${prefix}${key}`)
return null
}
return r.v
} catch (e) {
return null
}
}
/** 写. ttlSeconds <= 0 表示永不过期 */
export function set(prefix: string, key: string, value: string, ttlSeconds = 0): void {
try {
const d = ensureDb()
const expires = ttlSeconds > 0 ? Date.now() + ttlSeconds * 1000 : 0
d.prepare(`
INSERT INTO cache (k, v, expires_at) VALUES (?, ?, ?)
ON CONFLICT(k) DO UPDATE SET v = excluded.v, expires_at = excluded.expires_at
`).run(`${prefix}${key}`, value, expires)
} catch (e) {
// 写失败不抛 (缓存是 best-effort)
}
}
/** 删单条. 返回 affected rows (0 或 1) */
export function del(prefix: string, key: string): number {
try {
const d = ensureDb()
return d.prepare('DELETE FROM cache WHERE k = ?').run(`${prefix}${key}`).changes
} catch { return 0 }
}
/** 按 pattern 删 (SQL LIKE). pattern 可含 %, e.g. "section:abc1234:*" 删所有 section */
export function delByPattern(prefix: string, pattern: string): number {
try {
const d = ensureDb()
return d.prepare(`DELETE FROM cache WHERE k LIKE ?`).run(`${prefix}${pattern}`).changes
} catch { return 0 }
}
/** 清全部 (调试用) */
export function clearAll(): void {
try {
const d = ensureDb()
d.exec('DELETE FROM cache')
} catch {}
}
/** 显式关闭 (测试用) */
export function close(): void {
if (db) { try { db.close() } catch {}; db = null }
}
/** 健康检查: 库可访问, 路径, 行数 */
export function stats(): { path: string; ok: boolean; rows: number; error?: string } {
try {
const d = ensureDb()
const r = d.prepare('SELECT COUNT(*) as n FROM cache').get() as { n: number }
return { path: getCacheDbPath(), ok: true, rows: r.n }
} catch (e) {
return { path: getCacheDbPath(), ok: false, rows: 0, error: (e as Error).message }
}
}
// 进程退出时自动 close
process.on('exit', close)
process.on('SIGINT', () => { close(); process.exit(0) })
process.on('SIGTERM', () => { close(); process.exit(0) })
// 暴露给 JNPF 端点 (跟 Java 版保持一致, 提供 reset/import 入口)
import { existsSync as _exists, rmSync as _rm } from 'node:fs'
export function resetDbFile(): boolean {
close()
const p = getCacheDbPath()
if (_exists(p)) { try { _rm(p) } catch {} }
return true
}