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

数据库模型文档

UserModel

UserModel 是一个用户管理模型，提供了基本的用户CRUD操作和查询方法。

主要特性

• ✅ 完整的CRUD操作
• ✅ 用户身份验证支持
• ✅ 用户名和邮箱唯一性验证
• ✅ 角色管理
• ✅ 时间戳自动管理

数据库字段

字段名	类型	说明
id	integer	主键，自增
username	string(100)	用户名（必填，最大长度100）
email	string(100)	邮箱（唯一）
password	string(100)	密码（必填）
role	string(100)	用户角色（必填）
phone	string(100)	电话号码
age	integer	年龄（无符号整数）
created_at	timestamp	创建时间
updated_at	timestamp	更新时间

基本用法

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

// 创建用户
const user = await UserModel.create({
    username: "zhangsan",
    email: "zhangsan@example.com",
    password: "hashedPassword",
    role: "user",
    phone: "13800138000",
    age: 25
})

// 查找所有用户
const allUsers = await UserModel.findAll()

// 根据ID查找用户
const user = await UserModel.findById(1)

// 根据用户名查找用户
const user = await UserModel.findByUsername("zhangsan")

// 根据邮箱查找用户
const user = await UserModel.findByEmail("zhangsan@example.com")

// 更新用户信息
await UserModel.update(1, {
    phone: "13900139000",
    age: 26
})

// 删除用户
await UserModel.delete(1)

查询方法

基础查询

• findAll() - 查找所有用户
• findById(id) - 根据ID查找用户
• findByUsername(username) - 根据用户名查找用户
• findByEmail(email) - 根据邮箱查找用户

数据操作

• create(data) - 创建新用户
• update(id, data) - 更新用户信息
• delete(id) - 删除用户

数据验证

必填字段

• username - 用户名不能为空
• password - 密码不能为空
• role - 角色不能为空

唯一性约束

• email - 邮箱必须唯一
• username - 建议在应用层实现唯一性验证

时间戳管理

系统自动管理以下时间戳：

• created_at - 创建时自动设置为当前时间
• updated_at - 每次更新时自动设置为当前时间

角色管理

支持用户角色字段，可用于权限控制：

// 常见角色示例
const roles = {
    admin: "管理员",
    user: "普通用户",
    moderator: "版主"
}

错误处理

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

try {
    const user = await UserModel.create({
        username: "", // 空用户名会抛出错误
        password: "password"
    })
} catch (error) {
    console.error("创建用户失败:", error.message)
}

性能优化

• 建议为 username 和 email 字段添加索引
• 支持分页查询（需要扩展实现）

迁移和种子

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

• 20250616065041_create_users_table.mjs - 创建users表
• 20250616071157_users_seed.mjs - 示例用户数据

运行迁移和种子

# 运行迁移
npx knex migrate:latest

# 运行种子
npx knex seed:run

安全注意事项

1. 密码安全: 在创建用户前，确保密码已经过哈希处理
2. 输入验证: 在应用层验证用户输入数据的有效性
3. 权限控制: 根据用户角色实现适当的访问控制
4. SQL注入防护: 使用Knex.js的参数化查询防止SQL注入

扩展建议

可以考虑添加以下功能：

• 用户状态管理（激活/禁用）
• 密码重置功能
• 用户头像管理
• 用户偏好设置
• 登录历史记录
• 用户组管理