@kne/fastify-sequelize NPM

fastify-sequelize

描述

Fastify与Sequelize的深度集成插件，支持自动模型加载和分布式ID生成

安装

npm i --save @kne/fastify-sequelize

概述

核心功能概述

ORM 集成
- 无缝集成 Sequelize ORM 到 Fastify 框架
- 支持多种数据库（SQLite/MySQL/PostgreSQL等）
自动化模型管理
- 自动扫描指定目录下的模型文件
- 支持动态添加模型
- 自动处理模型关联关系
分布式ID生成
- 内置雪花算法ID生成器
- 可配置的基准时间和实例ID

详细配置说明

数据库连接配置

参数	类型	必填	默认值	说明
dialect	string	是	'sqlite'	数据库类型
database	string	否	null	数据库名称
username	string	否	null	数据库用户名
password	string	否	null	数据库密码
host	string	否	'localhost'	数据库地址
port	number	否	数据库默认端口	连接端口

高级配置选项

{
  // 雪花ID生成配置
  snowflake: {
    instance_id: 1,             // 分布式ID实例编号（0-1023）
    custom_epoch: 1672531200000 // 基准时间戳(2024-01-01)
  },
  
  // 数据库同步配置
  syncOptions: {                
    force: false,               // 强制同步（会删除原有表结构）
    alter: true                 // 安全模式自动修改表结构
  },
  
  // 模型加载配置
  modelsPath: './models',       // 模型文件存放路径
  prefix: 't_',                 // 数据库表名前缀
  name: 'models'               // Fastify实例上的挂载名称
}

模型定义规范

基础模型示例

// models/user.js
module.exports = ({ DataTypes }) => ({
  name: 'User',
  model: {
    username: {
      type: DataTypes.STRING(32),
      allowNull: false,
      unique: true
    },
    age: {
      type: DataTypes.INTEGER,
      defaultValue: 18
    }
  },
  options: {
    timestamps: true  // 启用时间戳
  }
});

关联模型示例

// models/post.js
module.exports = ({ DataTypes }) => ({
  name: 'Post',
  model: {
    title: DataTypes.STRING,
    content: DataTypes.TEXT
  },
  associate(db) {
     db.Post.belongsTo(db.User, { 
      foreignKey: 'authorId',
      as: 'author'
    });
  }
});

最佳实践建议

开发环境配置

fastify.register(fastifySequelize, {
  db: {
    dialect: 'sqlite',
    storage: './dev.db'
  },
  syncOptions: {
    alter: true  // 开发时自动同步表结构
  }
});

生产环境配置

fastify.register(fastifySequelize, {
  db: {
    dialect: 'mysql',
    host: 'db.prod.com',
    database: 'prod_db',
    username: 'admin',
    password: 'securePassword123'
  },
  syncOptions: {
    alter: false  // 生产环境禁用自动修改
  }
});

迁移策略
- 开发阶段可使用 force: true 快速重置数据库
- 生产环境建议使用 Sequelize 迁移工具
- 重要变更应通过手动迁移脚本执行

注意：雪花ID的基准时间建议设置为项目启动日期，instance_id 在分布式环境中需要确保唯一

示例

示例代码

API

配置选项

配置项	类型	默认值	说明
`db.dialect`	string	`'sqlite'`	数据库类型 (mysql/postgres/sqlite等)
`db.username`	string	`null`	数据库用户名
`db.password`	string	`null`	数据库密码
`snowflake.instance_id`	number	`1`	雪花ID生成器实例ID
`snowflake.custom_epoch`	number	`2024-01-01时间戳`	雪花ID基准时间
`modelsPath`	string	`'./models'`	模型文件存放路径
`prefix`	string	`'t_'`	数据库表名前缀
`name`	string	`'models'`	在fastify实例上的挂载名称

实例属性/方法

属性/方法	类型	描述
`addModels`	Function	用于添加 Sequelize 模型的函数
`Sequelize`	Object	Sequelize 库的引用
`[config.name]`	Object	动态命名的模型集合，当 `config.modelsPath` 是目录时加载的模型
`instance`	Sequelize	Sequelize 实例的引用
`generateId`	Function	生成唯一 ID 的函数（使用 snowflake 算法）
`sync`	Async Function	同步所有模型到数据库的方法