Sequelize 项目中的 TypeScript 集成指南-优快云博客

本文链接：https://blog.youkuaiyun.com/gitblog_00783/article/details/148755711

Sequelize 项目中的 TypeScript 集成指南

sequelize-docs-Zh-CN 项目地址: https://gitcode.com/gh_mirrors/se/sequelize-docs-Zh-CN

前言

在现代 Node.js 应用开发中，TypeScript 已经成为提升代码质量和开发效率的重要工具。Sequelize 作为流行的 ORM 框架，提供了完善的 TypeScript 支持。本文将深入探讨如何在 Sequelize 项目中高效使用 TypeScript。

TypeScript 版本要求

Sequelize 要求使用 TypeScript 4.5 或更高版本。需要注意的是，Sequelize 对 TypeScript 的支持策略不遵循 SemVer 版本规范，通常会支持某个 TypeScript 版本至少一年时间。

安装准备

在开始之前，需要确保项目中已安装必要的类型定义：

npm install @types/node --save-dev

这是因为 Sequelize 避免包含 Node.js 的类型定义，以防止与不同 Node 版本产生冲突。

模型定义最佳实践

基础类型定义方式

传统上，我们可以通过显式定义属性类型来创建模型：

import { Model, Optional } from '@sequelize/core';

type UserAttributes = {
  id: number;
  name: string;
  // 其他属性...
};

type UserCreationAttributes = Optional<UserAttributes, 'id'>;

class User extends Model<UserAttributes, UserCreationAttributes> {
  declare id: number;
  declare name: string;
  // 其他属性...
}

这种方式虽然可行，但存在明显的样板代码过多的问题。

改进的类型推断方式

Sequelize 6.14.0 及以上版本提供了更优雅的解决方案：

import { Model, InferAttributes, InferCreationAttributes, CreationOptional } from '@sequelize/core';

class User extends Model<InferAttributes<User>, InferCreationAttributes<User>> {
  declare id: CreationOptional<number>;
  declare name: string;
  // 其他属性...
}

这种方式通过 InferAttributes 和 InferCreationAttributes 自动从模型类中推断属性类型，大大减少了样板代码。

类型推断的工作原理

InferAttributes 会从模型类中提取所有声明属性，但会排除以下内容：

静态字段和方法
任何类型为函数的属性（方法）
使用 NonAttribute 类型标记的属性
显式指定要忽略的属性
Model 超类中声明的属性
Getter 和 setter（除非特别处理）

InferCreationAttributes 的行为类似，但会将使用 CreationOptional 标记的属性视为可选。

模型初始化注意事项

使用 Model.init 时，需要注意一些特殊情况：

关联关系的处理

定义关联关系时，外键属性会自动配置，无需在 init 中重复声明：

class Project extends Model<InferAttributes<Project>, InferCreationAttributes<Project>> {
  declare id: number;
  declare userId: ForeignKey<number>;
}

Project.belongsTo(User);

Project.init({
  id: {
    type: DataTypes.INTEGER,
    primaryKey: true,
    autoIncrement: true,
  },
}, { sequelize });

时间戳字段的处理

Sequelize 自动管理的时间戳字段（createdAt、updatedAt、deletedAt）仍需在 init 中声明以避免类型错误：

User.init({
  id: { /* 配置 */ },
  createdAt: DataTypes.DATE,
  updatedAt: DataTypes.DATE,
}, { sequelize });

实用类型详解

ModelStatic 类型

ModelStatic 用于类型化模型类本身。例如，创建一个获取主键属性的工具函数：

function getPrimaryKeyAttributes(model: ModelStatic<any>): ModelAttributeColumnOptions[] {
  return Object.values(model.rawAttributes).filter(attr => attr.primaryKey);
}

Attributes 和 CreationAttributes

这两个实用类型用于获取任何模型的属性列表，无论模型是如何创建的：

function getAttributeMetadata<M extends Model>(
  model: ModelStatic<M>, 
  attributeName: keyof Attributes<M>
): ModelAttributeColumnOptions {
  return model.rawAttributes[attributeName];
}