koa3-demo/_backup_old_files/db/docs/SiteConfigModel.md

数据库模型文档

SiteConfigModel

SiteConfigModel 是一个网站配置管理模型，提供了灵活的键值对配置存储和管理功能，支持单个配置项和批量配置操作。

主要特性

• ✅ 键值对配置存储
• ✅ 单个和批量配置操作
• ✅ 自动时间戳管理
• ✅ 配置项唯一性保证
• ✅ 灵活的配置值类型支持

数据库字段

字段名	类型	说明
id	integer	主键，自增
key	string(100)	配置项键名（必填，唯一，最大长度100）
value	text	配置项值（必填）
created_at	timestamp	创建时间
updated_at	timestamp	更新时间

基本用法

import { SiteConfigModel } from '../models/SiteConfigModel.js'

// 设置单个配置项
await SiteConfigModel.set("site_name", "我的网站")
await SiteConfigModel.set("site_description", "一个优秀的网站")
await SiteConfigModel.set("maintenance_mode", "false")

// 获取单个配置项
const siteName = await SiteConfigModel.get("site_name")
// 返回: "我的网站"

// 批量获取配置项
const configs = await SiteConfigModel.getMany([
    "site_name", 
    "site_description", 
    "maintenance_mode"
])
// 返回: { site_name: "我的网站", site_description: "一个优秀的网站", maintenance_mode: "false" }

// 获取所有配置
const allConfigs = await SiteConfigModel.getAll()
// 返回所有配置项的键值对对象

核心方法

单个配置操作

• get(key) - 获取指定key的配置值
• set(key, value) - 设置配置项（有则更新，无则插入）

批量配置操作

• getMany(keys) - 批量获取多个key的配置值
• getAll() - 获取所有配置项

配置管理策略

自动更新机制

// set方法会自动处理配置项的创建和更新
static async set(key, value) {
    const exists = await db("site_config").where({ key }).first()
    if (exists) {
        // 如果配置项存在，则更新
        await db("site_config").where({ key }).update({ 
            value, 
            updated_at: db.fn.now() 
        })
    } else {
        // 如果配置项不存在，则创建
        await db("site_config").insert({ key, value })
    }
}

批量获取优化

// 批量获取时使用 whereIn 优化查询性能
static async getMany(keys) {
    const rows = await db("site_config").whereIn("key", keys)
    const result = {}
    rows.forEach(row => {
        result[row.key] = row.value
    })
    return result
}

配置值类型支持

支持多种配置值类型：

字符串配置

await SiteConfigModel.set("site_name", "我的网站")
await SiteConfigModel.set("contact_email", "admin@example.com")

布尔值配置

await SiteConfigModel.set("maintenance_mode", "false")
await SiteConfigModel.set("debug_mode", "true")

数字配置

await SiteConfigModel.set("max_upload_size", "10485760") // 10MB
await SiteConfigModel.set("session_timeout", "3600") // 1小时

JSON配置

await SiteConfigModel.set("social_links", JSON.stringify({
    twitter: "https://twitter.com/example",
    facebook: "https://facebook.com/example"
}))

使用场景

网站基本信息配置

// 设置网站基本信息
await SiteConfigModel.set("site_name", "我的博客")
await SiteConfigModel.set("site_description", "分享技术和生活")
await SiteConfigModel.set("site_keywords", "技术,博客,编程")
await SiteConfigModel.set("site_author", "张三")

功能开关配置

// 功能开关
await SiteConfigModel.set("enable_comments", "true")
await SiteConfigModel.set("enable_registration", "false")
await SiteConfigModel.set("enable_analytics", "true")

系统配置

// 系统配置
await SiteConfigModel.set("max_login_attempts", "5")
await SiteConfigModel.set("password_min_length", "8")
await SiteConfigModel.set("session_timeout", "3600")

第三方服务配置

// 第三方服务配置
await SiteConfigModel.set("google_analytics_id", "GA-XXXXXXXXX")
await SiteConfigModel.set("recaptcha_site_key", "6LcXXXXXXXX")
await SiteConfigModel.set("smtp_host", "smtp.gmail.com")

配置获取和缓存

基础获取

// 获取网站名称
const siteName = await SiteConfigModel.get("site_name") || "默认网站名称"

// 获取维护模式状态
const isMaintenance = await SiteConfigModel.get("maintenance_mode") === "true"

批量获取优化

// 一次性获取多个配置项，减少数据库查询
const configs = await SiteConfigModel.getMany([
    "site_name",
    "site_description", 
    "maintenance_mode"
])

// 使用配置
if (configs.maintenance_mode === "true") {
    console.log("网站维护中")
} else {
    console.log(`欢迎访问 ${configs.site_name}`)
}

错误处理

所有方法都包含适当的错误处理：

try {
    const siteName = await SiteConfigModel.get("site_name")
    if (!siteName) {
        console.log("网站名称未配置，使用默认值")
        return "默认网站名称"
    }
    return siteName
} catch (error) {
    console.error("获取配置失败:", error.message)
    return "默认网站名称"
}

性能优化

• key 字段已添加唯一索引，提高查询性能
• 支持批量操作，减少数据库查询次数
• 建议在应用层实现配置缓存机制

迁移和种子

项目包含完整的数据库迁移和种子文件：

• 20250621013128_site_config.mjs - 创建site_config表
• 20250621013324_site_config_seed.mjs - 示例配置数据

运行迁移和种子

# 运行迁移
npx knex migrate:latest

# 运行种子
npx knex seed:run

扩展建议

可以考虑添加以下功能：

• 配置项分类管理
• 配置项验证规则
• 配置变更历史记录
• 配置导入/导出功能
• 配置项权限控制
• 配置项版本管理
• 配置项依赖关系
• 配置项加密存储

最佳实践

1. 配置项命名: 使用清晰的命名规范，如 feature_name 或 service_config
2. 配置值类型: 统一配置值的类型，如布尔值统一使用字符串 "true"/"false"
3. 配置分组: 使用前缀对配置项进行分组，如 email_, social_, system_
4. 默认值处理: 在应用层为配置项提供合理的默认值
5. 配置验证: 在设置配置项时验证值的有效性
6. 配置缓存: 实现配置缓存机制，减少数据库查询