在 Node.js/TypeScript 项目中使用…

适用于使用 Sequelize 连接 PostgreSQL、MySQL、MariaDB、SQLite 或 SQL Server，并需要模型关联、查询优化、事务、钩子、校验和迁移的 Node.js/TypeScript 项目。

适用场景

解决思路

1. 使用 promise-based Sequelize ORM；用 Model 和 DataTypes 声明 schema，并利用 associations、transactions、hooks；生产环境所有 schema 变更都用 migrations。
2. 创建 Sequelize 实例时可使用 Connection URI：new Sequelize(process.env.DATABASE_URL!, { dialect: 'postgres', logging: process.env.NODE_ENV === 'development' ? console.log : false, pool: { max: 10, min: 0, acquire: 30000, idle: 10000 } })。
3. 创建 Sequelize 实例时也可使用单独参数：new Sequelize({ dialect: 'postgres', host: process.env.DB_HOST, port: parseInt(process.env.DB_PORT || '5432'), username: process.env.DB_USERNAME, password: process.env.DB_PASSWORD, database: process.env.DB_NAME, logging: false })。
4. 用 async function testConnection() 调用 await sequelize.authenticate()；成功打印 Connection established successfully.，失败捕获并打印 Unable to connect to the database。
5. 用 TypeScript class 继承 Model，使用 InferAttributes 和 InferCreationAttributes，declare 字段，CreationOptional 标记可创建时省略字段；通过 User.init({...}, { sequelize, tableName: 'users', modelName: 'User', underscored: true }) 初始化并导出。
6. 在 init 中为 id 设置 DataTypes.INTEGER、autoIncrement、primaryKey；email 设置 DataTypes.STRING(255)、allowNull: false、unique: true、validate.isEmail；name 设置 allowNull: true；isActive 设置 defaultValue: true；createdAt/updatedAt 使用 DataTypes.DATE。
7. 按需选择 DataTypes：STRING(255)、TEXT、TEXT('tiny')、INTEGER、BIGINT、FLOAT、DOUBLE、DECIMAL(10,2)、BOOLEAN、DATE、DATEONLY、TIME、BLOB、JSON、JSONB、UUID、UUIDV4、ENUM('active','inactive','pending')、ARRAY(DataTypes.STRING)（仅 PostgreSQL）。
8. 一对一关联：User.hasOne(Profile, { foreignKey: 'userId', as: 'profile' }) 且 Profile.belongsTo(User, { foreignKey: 'userId', as: 'user' })；在类中声明可选关联字段。
9. 一对多关联：User.hasMany(Post, { foreignKey: 'authorId', as: 'posts' }) 且 Post.belongsTo(User, { foreignKey: 'authorId', as: 'author' })。
10. 多对多关联：Post.belongsToMany(Tag, { through: 'PostTags', foreignKey: 'postId', otherKey: 'tagId', as: 'tags' }) 且 Tag.belongsToMany(Post, { through: 'PostTags', foreignKey: 'tagId', otherKey: 'postId', as: 'posts' })。
11. 基本查询：User.findAll()；带条件 User.findAll({ where: { isActive: true } })；User.findOne({ where: { email: 'user@example.com' } })；User.findByPk(1)；User.findOrCreate({ where: { email: 'user@example.com' }, defaults: { name: 'New User' } })。
12. 高级查询导入 Op；用 Op.and 和 Op.or 组合条件；用 Op.like 做 LIKE，如 { email: { [Op.like]: '%@example.com' } }；用 Op.in；用 Op.gt、Op.gte、Op.lt、Op.lte、Op.ne 做比较。
13. Eager Loading：查询时使用 include: [{ model: Post, as: 'posts' }]；可嵌套 include 加载 Post 下的 Tag；可对 include 加 where 条件并用 required: false 生成 LEFT JOIN，以包含无关联记录。
14. 分页和排序：用 findAndCountAll 获取 count 和 rows；设置 order: [['createdAt','DESC'],['name','ASC']]、limit: pageSize、offset: (page - 1) * pageSize；totalPages = Math.ceil(count / pageSize)。
15. 聚合：User.count({ where: { isActive: true } })；Order.sum('amount', { where: { status: 'completed' } })；Product.max('price') 和 Product.min('price')；用 findAll 的 attributes 包含 sequelize.fn('COUNT', sequelize.col('id')) 等，并 group: ['status']。
16. 创建：User.create({ email: 'user@example.com', name: 'John Doe' })；bulkCreate([...], { validate: true })；带关联创建时传嵌套对象并用 include: [{ model: Profile, as: 'profile' }]。
17. 更新：findByPk 后修改字段并 await user.save()；或 await user.update({ name: 'Jane Doe', isActive: false })；批量更新 User.update({ isActive: false }, { where: { lastLoginAt: { [Op.lt]: new Date('2024-01-01') } } })。
18. 删除：findByPk 后 await user.destroy()；批量 User.destroy({ where: { isActive: false } })；模型设置 paranoid: true 时 destroy 为软删除并设置 deletedAt；用 user.restore() 恢复软删除记录。
19. 事务：推荐 managed transaction：sequelize.transaction(async (t) => {...})，其中每个操作传 { transaction: t } 并返回结果；也可用 unmanaged：const t = await sequelize.transaction(); try { ... await t.commit(); } catch (error) { await t.rollback(); throw error; }。
20. Hooks：可在 User.init 的 options.hooks 中定义 beforeValidate 规范化 email（toLowerCase().trim()）、beforeCreate 用 bcrypt.hash 哈希密码、afterCreate 发送欢迎邮件、beforeDestroy 清理关联数据；也可用 User.addHook('beforeSave', 'hashPassword', async (user) => { if (user.changed('password')) ... }) 单独添加。
21. Hook 访问事务：User.addHook('beforeCreate', async (user, options) => { if (options.transaction) { await AuditLog.create({...}, { transaction: options.transaction }); } })。
22. 校验：在字段 validate 中配置 isEmail 与自定义 msg、notEmpty、min/max（如 age min 0 max 150）、len [3,30]、isAlphanumeric；也可用 async 自定义 validator 查询唯一性并在冲突时 throw new Error('Username already taken')。
23. 迁移命令：用 npx sequelize-cli migration:generate --name create-users 生成；npx sequelize-cli db:migrate 运行；npx sequelize-cli db:migrate:undo 回滚最后一条；npx sequelize-cli db:migrate:undo:all 回滚所有。
24. 迁移文件：在 migrations/20240101000000-create-users.js 导出 { async up(queryInterface, Sequelize), async down(queryInterface) }；up 中用 queryInterface.createTable('users', {...}) 定义列（id autoIncrement primaryKey；email STRING(255) allowNull false unique；name；is_active BOOLEAN defaultValue true；created_at/updated_at DATE allowNull false defaultValue Sequelize.literal('CURRENT_TIMESTAMP')），并用 queryInterface.addIndex('users', ['email'])；down 用 queryInterface.dropTable('users')。
25. 避免 N+1：不要 findAll 后循环 user.getPosts() 逐条查询；改用 include: [{ model: Post, as: 'posts' }] 一次加载。
26. 生产环境配置 migrationStorageTableName: 'sequelize_migrations'、seederStorageTableName: 'sequelize_seeds'，并始终用 migrations。
27. 为关联使用 alias 提升清晰度：User.hasMany(Post, { as: 'posts', foreignKey: 'authorId' })；查询时 include 也用 as: 'posts'。
28. 批量操作始终传 validate: true，例如 User.bulkCreate(users, { validate: true })。
29. 用事务保证数据完整性：sequelize.transaction(async (t) => { const order = await Order.create({...}, { transaction: t }); await OrderItem.bulkCreate(items, { transaction: t }); await Inventory.decrement('quantity', {...}, { transaction: t }); })。
30. 用 scope 封装常用查询：User.addScope('active', { where: { isActive: true } }); User.addScope('withPosts', { include: [{ model: Post, as: 'posts' }] }); 然后 User.scope('active').findAll() 或 User.scope(['active','withPosts']).findAll()。

适用边界 · 注意事项

• 不使用 Node.js/TypeScript，或不想引入 ORM 的项目。
• 需要大量数据库特定高级 SQL、极致性能调优，或原生 SQL 更合适的场景。
• 不使用 Sequelize 支持的关系型数据库，或无法安装/维护 Sequelize 与 sequelize-cli 的环境。