koa3-demo/_backup_old_files/db/docs

数据库文档总览

本文档提供了整个数据库系统的概览，包括所有模型、表结构和关系。

数据库概览

这是一个基于 Koa3 和 Knex.js 构建的现代化 Web 应用数据库系统，使用 SQLite 作为数据库引擎。

技术栈

• 数据库: SQLite3
• ORM: Knex.js
• 迁移工具: Knex Migrations
• 种子数据: Knex Seeds
• 数据库驱动: sqlite3

数据模型总览

1. UserModel - 用户管理

• 表名: users
• 功能: 用户账户管理、身份验证、角色控制
• 主要字段: id, username, email, password, role, phone, age
• 文档: UserModel.md

2. ArticleModel - 文章管理

• 表名: articles
• 功能: 文章CRUD、状态管理、SEO优化、标签分类
• 主要字段: id, title, content, author, category, tags, status, slug
• 文档: ArticleModel.md

3. BookmarkModel - 书签管理

• 表名: bookmarks
• 功能: 用户书签管理、URL去重、用户隔离
• 主要字段: id, user_id, title, url, description
• 文档: BookmarkModel.md

4. SiteConfigModel - 网站配置

• 表名: site_config
• 功能: 键值对配置存储、系统设置管理
• 主要字段: id, key, value
• 文档: SiteConfigModel.md

数据库表结构

表关系图

users (用户表)
├── id (主键)
├── username
├── email
├── password
├── role
├── phone
├── age
├── created_at
└── updated_at

articles (文章表)
├── id (主键)
├── title
├── content
├── author
├── category
├── tags
├── status
├── slug
├── published_at
├── view_count
├── featured_image
├── excerpt
├── reading_time
├── meta_title
├── meta_description
├── keywords
├── description
├── created_at
└── updated_at

bookmarks (书签表)
├── id (主键)
├── user_id (外键 -> users.id)
├── title
├── url
├── description
├── created_at
└── updated_at

site_config (网站配置表)
├── id (主键)
├── key (唯一)
├── value
├── created_at
└── updated_at

外键关系

• bookmarks.user_id → users.id (CASCADE 删除)
• 其他表之间暂无直接外键关系

数据库迁移文件

迁移文件	描述	创建时间
20250616065041_create_users_table.mjs	创建用户表	2025-06-16
20250621013128_site_config.mjs	创建网站配置表	2025-06-21
20250830014825_create_articles_table.mjs	创建文章表	2025-08-30
20250830015422_create_bookmarks_table.mjs	创建书签表	2025-08-30
20250830020000_add_article_fields.mjs	添加文章额外字段	2025-08-30

种子数据文件

种子文件	描述	创建时间
20250616071157_users_seed.mjs	用户示例数据	2025-06-16
20250621013324_site_config_seed.mjs	网站配置示例数据	2025-06-21
20250830020000_articles_seed.mjs	文章示例数据	2025-08-30

快速开始

1. 安装依赖

npm install
# 或
bun install

2. 运行数据库迁移

# 运行所有迁移
npx knex migrate:latest

# 回滚迁移
npx knex migrate:rollback

# 查看迁移状态
npx knex migrate:status

3. 运行种子数据

# 运行所有种子
npx knex seed:run

# 运行特定种子
npx knex seed:run --specific=20250616071157_users_seed.mjs

4. 数据库连接

# 查看数据库配置
cat knexfile.mjs

# 连接数据库
npx knex --knexfile knexfile.mjs

开发指南

创建新的迁移文件

npx knex migrate:make create_new_table

创建新的种子文件

npx knex seed:make new_seed_data

创建新的模型

1. 在 src/db/models/ 目录下创建新的模型文件
2. 在 src/db/docs/ 目录下创建对应的文档
3. 更新本文档的模型总览部分

最佳实践

1. 模型设计原则

• 每个模型对应一个数据库表
• 使用静态方法提供数据操作接口
• 实现适当的错误处理和验证
• 支持软删除和审计字段

2. 迁移管理

• 迁移文件一旦提交到版本控制，不要修改
• 使用描述性的迁移文件名
• 在迁移文件中添加适当的注释
• 测试迁移的回滚功能

3. 种子数据

• 种子数据应该包含测试和开发所需的最小数据集
• 避免在生产环境中运行种子
• 种子数据应该是幂等的（可重复运行）

4. 性能优化

• 为常用查询字段添加索引
• 使用批量操作减少数据库查询
• 实现适当的缓存机制
• 监控查询性能

故障排除

常见问题

1. 迁移失败

   • 检查数据库连接配置
   • 确保数据库文件存在且有写入权限
   • 查看迁移文件语法是否正确

2. 种子数据失败

   • 检查表结构是否与种子数据匹配
   • 确保外键关系正确
   • 查看是否有唯一性约束冲突

3. 模型查询错误

   • 检查表名和字段名是否正确
   • 确保数据库连接正常
   • 查看SQL查询日志

调试技巧

# 启用SQL查询日志
DEBUG=knex:query node your-app.js

# 查看数据库结构
npx knex --knexfile knexfile.mjs
.tables
.schema users

贡献指南

1. 遵循现有的代码风格和命名规范
2. 为新功能添加适当的测试
3. 更新相关文档
4. 提交前运行迁移和种子测试

许可证

本项目采用 MIT 许可证。