koa3-demo

当前支持功能：

• 路由
• 日志
• 权限
• 数据库
• 缓存
• 界面
• 定时任务
• htmx
• 环境变量验证

快速开始

1. 环境配置

复制环境变量模板文件：

cp .env.example .env

编辑 .env 文件，设置必需的环境变量：

• SESSION_SECRET: 会话密钥（至少32个字符）
• JWT_SECRET: JWT密钥（至少32个字符）

2. 安装依赖

bun install

3. 初始化数据库

bun run dev:init

4. 启动开发服务器

bun run dev

环境变量说明

项目启动时会自动验证环境变量配置，确保应用安全性：

必需环境变量

• SESSION_SECRET: 会话密钥，支持多密钥轮换（逗号分隔）
• JWT_SECRET: JWT令牌密钥（最少32字符）

可选环境变量

• NODE_ENV: 运行环境 (development/production/test)
• PORT: 服务器端口 (默认: 3000)
• LOG_DIR: 日志目录 (默认: logs)
• HTTPS_ENABLE: 是否启用HTTPS (默认: off)

详细配置请参考 .env.example 文件。

数据库查询缓存（QueryBuilder 扩展）

为 Knex QueryBuilder 增加了内存级缓存能力，支持 TTL、自定义 key、只读/只写、按前缀失效与全局工具访问。默认 key 为查询的 toString()，也可通过 cacheAs() 指定。

可用方法：

• cache(ttlMs?): 读取缓存，不存在则执行 SQL 并写入缓存；可选 TTL（毫秒）。
• cacheAs(customKey): 为当前查询设置自定义缓存 key（链式，返回 builder）。
• cacheSet(value, ttlMs?): 手动写入当前查询 key 的缓存，返回写入的值。
• cacheGet(): 仅从缓存读取当前查询 key 的值（不命中则返回 undefined，不会执行 SQL）。
• cacheInvalidate(): 使当前查询 key 的缓存失效（删除）。
• cacheInvalidateByPrefix(prefix): 按前缀批量失效。

全局工具（命名导出 DbQueryCache，便于在查询构建器之外操作缓存）：

• get/set/has/delete/clear/clearByPrefix/stats()

示例：

import db, { DbQueryCache } from "./src/db/index.js"

// 1) 简单缓存 5 秒
const u1 = await db("users").where({ id: 1 }).first().cache(5000)

// 2) 自定义 key + 只读命中
const key = "users:count:active"
const count = await db("users").where({ active: 1 }).count({ c: "*" }).cacheAs(key).cache(10000)
const cachedOnly = db("users").where({ active: 1 }).cacheAs(key).cacheGet() // 命中则返回值，不命中为 undefined

// 3) 手动写入/覆盖缓存 15 秒
db("users").where({ active: 1 }).cacheAs(key).cacheSet([{ c: 123 }], 15000)

// 4) 单点或前缀失效
db("users").where({ active: 1 }).cacheAs(key).cacheInvalidate()
db.queryBuilder().cacheInvalidateByPrefix("users:")

// 5) 全局操作
DbQueryCache.clearByPrefix("users:")
const stats = DbQueryCache.stats() // { size, valid, expired }

注意：

• 该实现为进程内内存缓存，适合单实例与读多写少场景；多实例下需用外部缓存（如 Redis）替换/扩展。
• TTL 为可选，未设置则永久有效，直到被失效或进程重启。
• 自定义 key 建议使用明确的命名空间前缀（如 users:、site:），以便使用前缀批量失效。

📚 项目文档

• 环境变量配置指南 - 详细的环境配置说明
• 项目规范检查报告 - 完整的规范评估和改进记录
• 改进任务跟踪 - 项目改进任务的执行状态

🔧 开发和部署

测试环境变量配置

bun run test:env

生产环境部署

# 使用Docker
docker-compose up -d

# 或直接构建
docker build -t koa3-demo .
docker run -p 3000:3000 koa3-demo