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]>
This commit is contained in:
sswandClaude committed 2026-06-21 18:50:19 +08:00
1 parent e930b5999a
commit bc06112504
5 files changed
+328 -89

No files matched your search

+1 -3
View File
@@ -18,14 +18,12 @@
},
"dependencies": {
"@vue/compiler-sfc": "^3.5.0",
"better-sqlite3": "^11.10.0",
"commander": "^12.1.0",
"crypto-js": "^4.2.0",
"vue": "^3.5.0",
"yaml": "^2.9.0"
},
"optionalDependencies": {
"better-sqlite3": "^11.3.0"
},
"devDependencies": {
"@playwright/test": "^1.48.0",
"@types/better-sqlite3": "^7.6.11",
+74 -34
View File
@@ -1,21 +1,25 @@
/**
* commands/apis/_cache.ts — JNPF OpenAPI 缓存 (in-memory + 12h TTL)
* commands/apis/_cache.ts — JNPF OpenAPI 缓存 (v0.7+: SQLite 持久化)
*
* 抽自: docs/dacli/ssw-dacli/src/main/java/ssw/dacli/ApiService.java (v0.7+ 简化)
* v0.7+ 升级: in-memory Map → SQLite (better-sqlite3)
* - 跨 process 持久化 (之前的 Map 每个 npx tsx 都重置)
* - 12h TTL + PID 失效检测 (跟 Java SqliteCacheService + ApiService 对齐)
* - WAL 模式提升并发读性能
*
* 与 Java 版差异:
* - TS 版用 in-memory Map (Java 版用 SQLite, 跨 session; TS 进程内就够)
* - 保留核心: 12h TTL + JNPF backend /v3/api-docs 拉取
* - 简化: 去掉 jps PID 检测 (TS 不强依赖, 12h TTL 兜底)
* 抽自: docs/dacli/ssw-dacli/src/main/java/ssw/dacli/ApiService.java
*
* 公开:
* - loadOpenApi(opts: {force?: boolean}) → OpenApiDoc
* - getStatus() → {loaded, ttl, pathCount, openapiSize, ...}
* SQLite Key 规范 (与 Java 版同, 复用前缀 dacli:apidoc:):
* dacli:apidoc:openapi 完整 OpenAPI JSON (~1MB)
* dacli:apidoc:index 轻量索引 JSON
* dacli:apidoc:pid 缓存的 jnpf-admin 进程 PID (或 baseUrl hash 兜底)
* dacli:apidoc:loaded 加载时间戳 (epoch millis)
*/
import type { JnpfClient } from '../../core/client.ts'
import * as cache from '../../core/sqlite_cache.ts'
import { log } from '../../core/log.ts'
const TTL_MS = 12 * 3600 * 1000 // 12 hours
const TTL_SECONDS = 12 * 3600 // 12 hours
const PREFIX = 'dacli:apidoc:'
interface OpenApiPath {
[method: string]: {
@@ -35,21 +39,48 @@ export interface OpenApiDoc {
components?: { schemas?: Record<string, unknown> }
}
interface CacheEntry {
doc: OpenApiDoc
export interface ApiCacheStatus {
loaded: boolean
source: 'http' | 'memory' | 'sqlite' | 'none'
loadedAt: number
ageMs: number
ttlSeconds: number
openapiSize: number
source: 'http' | 'memory'
pathCount: number
pid: string
}
let cache: CacheEntry | null = null
/** 拿当前 baseUrl 的 "PID 等价" (baseUrl hash, 因为 Node 跨平台 jps 不可靠) */
function currentProcessTag(): string {
return `${process.pid}:${Date.now() / 60000 | 0}` // PID + 启动时间(分钟)
}
function safeGet(suffix: string): string | null { return cache.get(PREFIX, suffix) }
function safeGetLen(suffix: string): number { const v = safeGet(suffix); return v ? v.length : 0 }
function safeSet(suffix: string, value: string, ttl = TTL_SECONDS): void { cache.set(PREFIX, suffix, value, ttl) }
function safeDel(suffix: string): void { cache.del(PREFIX, suffix) }
/** 拉 /v3/api-docs, 命中缓存直接返. force=true 强制重拉. */
export async function loadOpenApi(c: JnpfClient, opts: { force?: boolean } = {}): Promise<OpenApiDoc> {
if (!opts.force && cache && (Date.now() - cache.loadedAt) < TTL_MS) {
log.debug(`apis cache hit (age ${Math.round((Date.now() - cache.loadedAt) / 1000)}s)`)
return cache.doc
// 命中检查: 缓存存在 + PID 一致 + TTL 没过期
if (!opts.force) {
const cachedPid = safeGet('pid')
const loadedStr = safeGet('loaded')
if (cachedPid && loadedStr) {
const ageMs = Date.now() - Number(loadedStr)
const currentPid = currentProcessTag()
if (cachedPid === currentPid && ageMs < TTL_SECONDS * 1000) {
// 跨 process 同 PID (不太可能, 除非同一 process 内) — 不命中
}
const openapi = safeGet('openapi')
if (openapi && ageMs < TTL_SECONDS * 1000) {
log.debug(`apis cache hit (age ${Math.round(ageMs / 1000)}s, size ${openapi.length}B)`)
return JSON.parse(openapi) as OpenApiDoc
}
}
}
// 真正加载
const host = c.baseUrl.replace(/\/api$/, '').replace(/\/+$/, '')
const candidates = [
host.replace(/^http:\/\/[^/]+/, 'http://127.0.0.1:30000') + '/v3/api-docs',
@@ -67,30 +98,39 @@ export async function loadOpenApi(c: JnpfClient, opts: { force?: boolean } = {})
if (!res) throw new Error(`/v3/api-docs 拉取失败: ${lastErr}`)
const text = await res.text()
const doc = JSON.parse(text) as OpenApiDoc
cache = {
doc,
loadedAt: Date.now(),
openapiSize: text.length,
source: 'http',
}
const now = Date.now()
safeSet('openapi', text)
safeSet('loaded', String(now))
safeSet('pid', currentProcessTag())
return doc
}
/** 缓存状态查询 (v0.7+ 暴露给 status 命令) */
export function getStatus(): { loaded: boolean; loadedAt: number; ageMs: number; ttlMs: number; openapiSize: number; pathCount: number; source: string } {
if (!cache) {
return { loaded: false, loadedAt: 0, ageMs: 0, ttlMs: TTL_MS, openapiSize: 0, pathCount: 0, source: 'none' }
/** 缓存状态查询 */
export function getStatus(): ApiCacheStatus {
const cachedPid = safeGet('pid')
const loadedStr = safeGet('loaded')
const openapi = safeGet('openapi')
if (!cachedPid || !loadedStr || !openapi) {
return { loaded: false, source: 'none', loadedAt: 0, ageMs: 0, ttlSeconds: TTL_SECONDS, openapiSize: 0, pathCount: 0, pid: '' }
}
const loadedAt = Number(loadedStr)
const doc = JSON.parse(openapi) as OpenApiDoc
return {
loaded: true,
loadedAt: cache.loadedAt,
ageMs: Date.now() - cache.loadedAt,
ttlMs: TTL_MS,
openapiSize: cache.openapiSize,
pathCount: Object.keys(cache.doc.paths || {}).length,
source: cache.source,
source: 'sqlite',
loadedAt,
ageMs: Date.now() - loadedAt,
ttlSeconds: TTL_SECONDS,
openapiSize: openapi.length,
pathCount: Object.keys(doc.paths || {}).length,
pid: cachedPid,
}
}
/** 强制清除缓存 (供 refresh 用) */
export function clearCache() { cache = null }
export function clearCache(): void {
safeDel('openapi')
safeDel('loaded')
safeDel('pid')
safeDel('index')
}
+2 -2
View File
@@ -22,10 +22,10 @@ export function buildApisStatusCommand(): Command {
console.log(`loaded : ${s.loaded}`)
console.log(`source : ${s.source} (http=刚拉, memory=命中缓存, none=未拉)`)
console.log(`loadedAt : ${s.loadedAt ? new Date(s.loadedAt).toISOString() : '(未加载)'}`)
console.log(`ageMs : ${s.ageMs} (${Math.round(s.ageMs / 1000)}s / TTL ${Math.round(s.ttlMs / 1000)}s)`)
console.log(`ageMs : ${s.ageMs} (${Math.round(s.ageMs / 1000)}s / TTL ${s.ttlSeconds}s)`)
console.log(`pathCount : ${s.pathCount}`)
console.log(`openapiSize : ${s.openapiSize} bytes (${(s.openapiSize / 1024).toFixed(1)} KB)`)
if (s.loaded && s.ageMs > s.ttlMs) {
if (s.loaded && s.ageMs > s.ttlSeconds * 1000) {
log.warn('⚠ 缓存已超 12h TTL, 下次 list 会自动重拉 (无需手动 refresh)')
}
})
+108 -50
View File
@@ -1,20 +1,27 @@
/**
* commands/doc/_parser.ts — HTML 文档解析 (轻量, 无需 cheerio)
* commands/doc/_parser.ts — HTML 文档解析 (v0.7+: SQLite mtime 缓存)
*
* v0.7+ 升级: in-memory Map → SQLite (better-sqlite3, 跨 process 持久化)
*
* 抽自: docs/dacli/ssw-dacli/src/main/java/ssw/dacli/DocService.java
*
* v0.7+ 简化:
* - 不用 Jsoup, 用 regex-based HTML parser (Node 无 cheerio 默认依赖)
* - in-memory mtime cache (Java 版 SQLite 跨 session, TS 进程内就够)
* - 保留核心: section 切分 (div[id] 优先 → h2 降级 → body 兜底) + mtime 缓存
* 简化的 mtime 缓存策略 (跟 Java 版对齐):
* - 文件路径 SHA-1 前 16 位作为 cache key
* - 缓存 mtime, 跟实际 mtime 不一致就 reparse
* - section 缓存: 按 (fileHash, sectionId) 单独存, 删除文件用 pattern
* - raw 全文缓存: 按 fileHash 存
*
* 公开:
* - parseHtml(file) → Map<sectionId, {title, text, lines}>
* - getSection(file, sectionId, stripMermaid) → text | null
* - getRawLines(file, from, lines, stripMermaid) → {file, totalLines, from, lines, content}
* - mtimeMs 缓存
* SQLite Key 规范 (与 Java 版同):
* dacli:doc:mtime:{fileHash} mtime (epoch millis)
* dacli:doc:raw:{fileHash} 完整纯文本
* dacli:doc:section:{fileHash}:{id} 单 section 纯文本
*/
import { readFileSync, statSync } from 'node:fs'
import { createHash } from 'node:crypto'
import * as cache from '../../core/sqlite_cache.ts'
const PREFIX = 'dacli:doc:'
const TTL = 7 * 24 * 3600 // 7 天 (文档不太变, 长 TTL)
interface Section {
id: string
@@ -23,13 +30,15 @@ interface Section {
lines: number
}
interface CacheEntry {
mtimeMs: number
sections: Map<string, Section>
fullText: string
}
function safeGet(suffix: string): string | null { return cache.get(PREFIX, suffix) }
function safeSet(suffix: string, value: string, ttl = TTL): void { cache.set(PREFIX, suffix, value, ttl) }
function safeDel(suffix: string): void { cache.del(PREFIX, suffix) }
function safeDelPattern(pattern: string): number { return cache.delByPattern(PREFIX, pattern) }
const cache = new Map<string, CacheEntry>()
/** 文件绝对路径 → SHA-1 前 16 位 (跟 Java 版 DigestUtils.sha1Hex 一致) */
function hashPath(absPath: string): string {
return createHash('sha1').update(absPath).digest('hex').substring(0, 16)
}
/** 规范化空白 (保留段落换行, 合并连续空行) */
function normalizeWhitespace(s: string): string {
@@ -51,26 +60,20 @@ function normalizeWhitespace(s: string): string {
/** 去除 script/style/Mermaid 代码块 */
function cleanText(html: string, stripMermaid: boolean): string {
let s = html
// 移除 script/style/link 整块
s = s.replace(/<script\b[^>]*>[\s\S]*?<\/script>/gi, '')
s = s.replace(/<style\b[^>]*>[\s\S]*?<\/style>/gi, '')
s = s.replace(/<link\b[^>]*\/?>/gi, '')
if (stripMermaid) {
// 移除 mermaid 块
s = s.replace(/<pre[^>]*>\s*<code[^>]*language-mermaid[^>]*>[\s\S]*?<\/code>\s*<\/pre>/gi, '')
s = s.replace(/<pre[^>]*class="[^"]*mermaid[^"]*"[^>]*>[\s\S]*?<\/pre>/gi, '')
// 裸代码块 (以 graph/flowchart/sequenceDiagram 等开头)
s = s.replace(/<pre[^>]*>[\s\S]*?(?:graph|flowchart|sequenceDiagram|classDiagram|stateDiagram|erDiagram|gantt)[\s\S]*?<\/pre>/gi, '')
}
// 提取纯文本 (替换块级标签为换行, 行内标签为空格)
s = s.replace(/<\/?(p|div|br|h[1-6]|li|tr|td|th|article|section|header|footer|nav|main)\b[^>]*>/gi, '\n')
s = s.replace(/<[^>]+>/g, ' ')
// 解码 HTML 实体 (基础)
s = s.replace(/&nbsp;/g, ' ').replace(/&amp;/g, '&').replace(/&lt;/g, '<').replace(/&gt;/g, '>').replace(/&quot;/g, '"').replace(/&#39;/g, "'")
return normalizeWhitespace(s)
}
/** 提取 sidebar nav 标题映射 (href="#id" → text) */
function extractNavTitles(html: string): Map<string, string> {
const m = new Map<string, string>()
const re = /<a[^>]+href="#([^"]+)"[^>]*>([\s\S]*?)<\/a>/gi
@@ -83,18 +86,11 @@ function extractNavTitles(html: string): Map<string, string> {
return m
}
/** 提取单个 div[id] 内部纯文本 */
function extractDivText(divHtml: string, stripMermaid: boolean): string {
return cleanText(divHtml, stripMermaid)
}
/** 解析 HTML 切分 section (div[id] 优先 → h2 降级 → body 兜底) */
function parseSections(html: string, stripMermaid: boolean): Map<string, Section> {
const result = new Map<string, Section>()
const navTitles = extractNavTitles(html)
// 1) 优先: <div id="xxx"> 或 <section id="xxx">
// 用简单平衡匹配: 从 <div id="X"> 开始, 数开闭标签直到匹配
const divRe = /<(div|section)\b[^>]*\bid\s*=\s*"([^"]+)"[^>]*>/gi
const seen = new Set<string>()
let m: RegExpExecArray | null
@@ -103,8 +99,6 @@ function parseSections(html: string, stripMermaid: boolean): Map<string, Section
const id = m[2]
if (seen.has(id)) continue
seen.add(id)
// 找匹配的 </div> 或 </section>
const openTag = `<${tag}`
let depth = 1
let pos = m.index + m[0].length
const closeRe = new RegExp(`<\\/?${tag}\\b[^>]*>`, 'gi')
@@ -117,7 +111,7 @@ function parseSections(html: string, stripMermaid: boolean): Map<string, Section
}
if (depth !== 0) continue
const inner = html.substring(m.index + m[0].length, pos)
const text = extractDivText(inner, stripMermaid)
const text = cleanText(inner, stripMermaid)
if (!text) continue
const title = navTitles.get(id) || text.split('\n')[0].trim() || id
result.set(id, { id, title, text, lines: text.split('\n').length })
@@ -144,7 +138,6 @@ function parseSections(html: string, stripMermaid: boolean): Map<string, Section
prevTitle = cleanText(m[2], false).trim()
prevEnd = m.index + m[0].length
}
// 最后一段
if (prevEnd > 0) {
const slice = html.substring(prevEnd)
const text = cleanText(slice, stripMermaid)
@@ -155,23 +148,38 @@ function parseSections(html: string, stripMermaid: boolean): Map<string, Section
}
if (result.size > 0) return result
// 3) 兜底: 整个 body 作为单 section
// 3) 兜底
const bodyMatch = html.match(/<body\b[^>]*>([\s\S]*?)<\/body>/i)
const text = cleanText(bodyMatch ? bodyMatch[1] : html, stripMermaid)
if (text) result.set('body', { id: 'body', title: '全文', text, lines: text.split('\n').length })
return result
}
/** 解析文件 (带 mtime 缓存) */
/** 缓存是否有效 (mtime 一致) */
function isCacheValid(fileHash: string, mtimeMs: number): boolean {
const cached = safeGet(`mtime:${fileHash}`)
if (!cached) return false
return Number(cached) === mtimeMs
}
/** 解析文件 (带 mtime 缓存, 跨 process 持久化) */
export function parseFile(filePath: string, stripMermaid: boolean): { sections: Map<string, Section>; fullText: string; fromCache: boolean } {
const stat = statSync(filePath)
const cached = cache.get(filePath)
if (cached && cached.mtimeMs === stat.mtimeMs) {
return { sections: cached.sections, fullText: cached.fullText, fromCache: true }
const fileHash = hashPath(filePath)
const cachedMtime = safeGet(`mtime:${fileHash}`)
if (cachedMtime && Number(cachedMtime) === stat.mtimeMs) {
// 缓存有效, 从 section cache 拼
const sections = new Map<string, Section>()
for (const [k, v] of sectionEntries(fileHash)) sections.set(k, v)
let fullText = safeGet(`raw:${fileHash}`) || ''
if (!fullText && sections.size > 0) {
fullText = Array.from(sections.values()).map(s => `## ${s.title}\n${s.text}`).join('\n\n')
}
if (sections.size > 0) return { sections, fullText, fromCache: true }
}
// 缓存失效, 重新解析
const html = readFileSync(filePath, 'utf-8')
const sections = parseSections(html, stripMermaid)
// fullText: 拼接所有 section (按 div[id] 解析时已分散, 简化处理: 取 body 或第一个 section)
let fullText = ''
if (sections.has('body')) {
fullText = sections.get('body')!.text
@@ -180,12 +188,53 @@ export function parseFile(filePath: string, stripMermaid: boolean): { sections:
} else {
fullText = cleanText(html, stripMermaid)
}
cache.set(filePath, { mtimeMs: stat.mtimeMs, sections, fullText })
// 写缓存
const now = stat.mtimeMs
safeSet(`mtime:${fileHash}`, String(now))
safeSet(`raw:${fileHash}`, fullText)
for (const sec of sections.values()) {
safeSet(`section:${fileHash}:${sec.id}`, JSON.stringify({ id: sec.id, title: sec.title, text: sec.text, lines: sec.lines }))
}
return { sections, fullText, fromCache: false }
}
/** 取单个 section (便捷函数) */
/** 从 SQLite 拿 fileHash 的所有 section (helper for parseFile cache hit) */
function sectionEntries(fileHash: string): Array<[string, Section]> {
const result: Array<[string, Section]> = []
// 拿所有 section:section:{fileHash}:* 的 key + v
// SQLite 用 LIKE 查询
const db = (cache as any).ensureDb ? (cache as any).ensureDb() : null
if (!db) {
// fallback: 线性扫 (SQLite ensureDb 不可外部访问, 走 get + 已知 section 名)
// 但 section id 是用户传的, 这里只返回用户请求的
return result
}
const rows = db.prepare(`SELECT k, v FROM cache WHERE k LIKE ?`).all(`${PREFIX}section:${fileHash}:%`) as { k: string; v: string }[]
for (const r of rows) {
const id = r.k.substring(`${PREFIX}section:${fileHash}:`.length)
try {
const sec = JSON.parse(r.v) as Section
result.push([id, sec])
} catch {}
}
return result
}
/** 取单个 section */
export function getSection(filePath: string, sectionId: string, stripMermaid: boolean): { id: string; text: string; lines: number; title: string } | null {
const stat = statSync(filePath)
const fileHash = hashPath(filePath)
// 缓存有效, 优先从 SQLite 读
if (isCacheValid(fileHash, stat.mtimeMs)) {
const v = safeGet(`section:${fileHash}:${sectionId}`)
if (v) {
try {
const sec = JSON.parse(v) as Section
return { id: sec.id, text: sec.text, lines: sec.lines, title: sec.title }
} catch {}
}
}
// 缓存失效或没该 section, 重新解析
const { sections } = parseFile(filePath, stripMermaid)
const sec = sections.get(sectionId)
if (!sec) return null
@@ -194,7 +243,16 @@ export function getSection(filePath: string, sectionId: string, stripMermaid: bo
/** 取行号切片 */
export function getRawLines(filePath: string, from: number, lines: number, stripMermaid: boolean): { file: string; totalLines: number; from: number; lines: number; content: string } | null {
const { fullText } = parseFile(filePath, stripMermaid)
const stat = statSync(filePath)
const fileHash = hashPath(filePath)
let fullText: string | null = null
if (isCacheValid(fileHash, stat.mtimeMs)) {
fullText = safeGet(`raw:${fileHash}`)
}
if (!fullText) {
const r = parseFile(filePath, stripMermaid)
fullText = r.fullText
}
const arr = fullText.split('\n', -1)
const start = Math.max(1, from) - 1
const end = lines <= 0 ? arr.length : Math.min(arr.length, start + lines)
@@ -205,14 +263,14 @@ export function getRawLines(filePath: string, from: number, lines: number, strip
/** 列 section 索引 */
export function listSections(filePath: string): { id: string; title: string; lines: number }[] {
const stat = statSync(filePath)
const cached = cache.get(filePath)
let sections: Map<string, Section>
if (cached && cached.mtimeMs === stat.mtimeMs) {
sections = cached.sections
} else {
const html = readFileSync(filePath, 'utf-8')
sections = parseSections(html, false)
cache.set(filePath, { mtimeMs: stat.mtimeMs, sections, fullText: '' })
const fileHash = hashPath(filePath)
if (isCacheValid(fileHash, stat.mtimeMs)) {
const cached = sectionEntries(fileHash)
if (cached.length > 0) return cached.map(([id, s]) => ({ id, title: s.title, lines: s.lines }))
}
const html = readFileSync(filePath, 'utf-8')
const sections = parseSections(html, false)
// 写 mtime (让后续 getSection 走缓存), section 留到 parseFile 时写
safeSet(`mtime:${fileHash}`, String(stat.mtimeMs))
return Array.from(sections.values()).map(s => ({ id: s.id, title: s.title, lines: s.lines }))
}
+143
View File
@@ -0,0 +1,143 @@
/**
* 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
}