TypeScript

Sequelize 提供了自己的 TypeScript 定义.

请注意, 仅支持 TypeScript >= 4.1. 我们对 TypeScript 的支持不遵循 SemVer. 我们将支持 TypeScript 版本至少一年, 之后它们可能会在 SemVer MINOR 版本中被删除.

由于 Sequelize 严重依赖于运行时属性分配, 因此 TypeScript 无法立即开箱即用.

为了使模型可用, 需要大量的手动类型声明.

安装

为了避免非 TS 用户的安装膨胀,你必须手动安装以下键入程序包:

  • @types/node (在 node 项目中这是通常是必须的)
  • @types/validator

使用

重要: 您必须在类属性类型上使用 declare 以确保 TypeScript 不会触发这些类属性. 参阅 公共类字段的注意事项

Sequelize Models 接受两种通用类型来定义模型的属性和创建属性是什么样的:

  1. import { Model, Optional } from 'sequelize';
  3. // We don't recommend doing this. Read on for the new way of declaring Model typings.
  5. type UserAttributes = {
  6.   id: number,
  7.   name: string,
  8.   // other attributes...
  9. };
  11. // we're telling the Model that 'id' is optional
  12. // when creating an instance of the model (such as using Model.create()).
  13. type UserCreationAttributes = Optional<UserAttributes, 'id'>;
  15. class User extends Model<UserAttributes, UserCreationAttributes> {
  16.   declare id: number;
  17.   declare string: number;
  18.   // other attributes...
  19. }

这个解决方案很冗长. Sequelize >=6.14.0 提供了新的实用程序类型, 将大大减少数量 必需的样板: InferAttributes 和 InferCreationAttributes. 他们将提取属性类型 直接来自模型:

  1. import { Model, InferAttributes, InferCreationAttributes, CreationOptional } from 'sequelize';
  3. // order of InferAttributes & InferCreationAttributes is important.
  4. class User extends Model<InferAttributes<User>, InferCreationAttributes<User>> {
  5.   // 'CreationOptional' is a special type that marks the field as optional
  6.   // when creating an instance of the model (such as using Model.create()).
  7.   declare id: CreationOptional<number>;
  8.   declare string: number;
  9.   // other attributes...
  10. }

关于 InferAttributes 和 InferCreationAttributes 工作需要了解的重要事项: 它们将选择类的所有声明属性，除了:

  • 静态字段和方法.
  • 方法（任何类型为函数的东西）.
  • 类型使用铭记类型 NonAttribute 的那些.
  • 像这样使用 AttributesOf 排除的那些: InferAttributes<User, { omit: 'properties' | 'to' | 'omit' }>.
  • 由 Model 超类声明的那些（但不是中间类！）. 如果您的属性之一与 Model 的属性之一同名, 请更改其名称. 无论如何, 这样做可能会导致问题.
  • Getter & setter 不会被自动排除. 将它们的 return / parameter 类型设置为 NonAttribute, 或将它们添加到 omit 以排除它们.

InferCreationAttributes 的工作方式与 AttributesOf 相同, 但有一个例外: 使用 CreationOptional 类型键入的属性将被标记为可选.

您只需要在类实例字段或 getter 上使用 CreationOptional 和 NonAttribute.

对属性进行严格类型检查的最小 TypeScript 项目示例:

  1. import {
  2.   Association, DataTypes, HasManyAddAssociationMixin, HasManyCountAssociationsMixin,
  3.   HasManyCreateAssociationMixin, HasManyGetAssociationsMixin, HasManyHasAssociationMixin,
  4.   HasManySetAssociationsMixin, HasManyAddAssociationsMixin, HasManyHasAssociationsMixin,
  5.   HasManyRemoveAssociationMixin, HasManyRemoveAssociationsMixin, Model, ModelDefined, Optional,
  6.   Sequelize, InferAttributes, InferCreationAttributes, CreationOptional, NonAttribute
  7. } from 'sequelize';
  9. const sequelize = new Sequelize('mysql://root:asd123@localhost:3306/mydb');
  11. // 'projects' is excluded as it's not an attribute, it's an association.
  12. class User extends Model<InferAttributes<User, { omit: 'projects' }>, InferCreationAttributes<User, { omit: 'projects' }>> {
  13.   // id can be undefined during creation when using `autoIncrement`
  14.   declare id: CreationOptional<number>;
  15.   declare name: string;
  16.   declare preferredName: string | null; // for nullable fields
  18.   // timestamps!
  19.   // createdAt can be undefined during creation
  20.   declare createdAt: CreationOptional<Date>;
  21.   // updatedAt can be undefined during creation
  22.   declare updatedAt: CreationOptional<Date>;
  24.   // Since TS cannot determine model association at compile time
  25.   // we have to declare them here purely virtually
  26.   // these will not exist until `Model.init` was called.
  27.   declare getProjects: HasManyGetAssociationsMixin<Project>; // Note the null assertions!
  28.   declare addProject: HasManyAddAssociationMixin<Project, number>;
  29.   declare addProjects: HasManyAddAssociationsMixin<Project, number>;
  30.   declare setProjects: HasManySetAssociationsMixin<Project, number>;
  31.   declare removeProject: HasManyRemoveAssociationMixin<Project, number>;
  32.   declare removeProjects: HasManyRemoveAssociationsMixin<Project, number>;
  33.   declare hasProject: HasManyHasAssociationMixin<Project, number>;
  34.   declare hasProjects: HasManyHasAssociationsMixin<Project, number>;
  35.   declare countProjects: HasManyCountAssociationsMixin;
  36.   declare createProject: HasManyCreateAssociationMixin<Project, 'ownerId'>;
  38.   // You can also pre-declare possible inclusions, these will only be populated if you
  39.   // actively include a relation.
  40.   declare projects?: NonAttribute<Project[]>; // Note this is optional since it's only populated when explicitly requested in code
  42.   // getters that are not attributes should be tagged using NonAttribute
  43.   // to remove them from the model's Attribute Typings.
  44.   get fullName(): NonAttribute<string> {
  45.     return this.name;
  46.   }
  48.   declare static associations: {
  49.     projects: Association<User, Project>;
  50.   };
  51. }
  53. class Project extends Model<
  54.   InferAttributes<Project>,
  55.   InferCreationAttributes<Project>
  56. > {
  57.   // id can be undefined during creation when using `autoIncrement`
  58.   declare id: CreationOptional<number>;
  59.   declare ownerId: number;
  60.   declare name: string;
  62.   // `owner` is an eagerly-loaded association.
  63.   // We tag it as `NonAttribute`
  64.   declare owner?: NonAttribute<User>;
  66.   // createdAt can be undefined during creation
  67.   declare createdAt: CreationOptional<Date>;
  68.   // updatedAt can be undefined during creation
  69.   declare updatedAt: CreationOptional<Date>;
  70. }
  72. class Address extends Model<
  73.   InferAttributes<Address>,
  74.   InferCreationAttributes<Address>
  75. > {
  76.   declare userId: number;
  77.   declare address: string;
  79.   // createdAt can be undefined during creation
  80.   declare createdAt: CreationOptional<Date>;
  81.   // updatedAt can be undefined during creation
  82.   declare updatedAt: CreationOptional<Date>;
  83. }
  85. Project.init(
  86.   {
  87.     id: {
  88.       type: DataTypes.INTEGER.UNSIGNED,
  89.       autoIncrement: true,
  90.       primaryKey: true
  91.     },
  92.     ownerId: {
  93.       type: DataTypes.INTEGER.UNSIGNED,
  94.       allowNull: false
  95.     },
  96.     name: {
  97.       type: new DataTypes.STRING(128),
  98.       allowNull: false
  99.     },
  100.     createdAt: DataTypes.DATE,
  101.     updatedAt: DataTypes.DATE,
  102.   },
  103.   {
  104.     sequelize,
  105.     tableName: 'projects'
  106.   }
  107. );
  109. User.init(
  110.   {
  111.     id: {
  112.       type: DataTypes.INTEGER.UNSIGNED,
  113.       autoIncrement: true,
  114.       primaryKey: true
  115.     },
  116.     name: {
  117.       type: new DataTypes.STRING(128),
  118.       allowNull: false
  119.     },
  120.     preferredName: {
  121.       type: new DataTypes.STRING(128),
  122.       allowNull: true
  123.     },
  124.     createdAt: DataTypes.DATE,
  125.     updatedAt: DataTypes.DATE,
  126.   },
  127.   {
  128.     tableName: 'users',
  129.     sequelize // passing the `sequelize` instance is required
  130.   }
  131. );
  133. Address.init(
  134.   {
  135.     userId: {
  136.       type: DataTypes.INTEGER.UNSIGNED
  137.     },
  138.     address: {
  139.       type: new DataTypes.STRING(128),
  140.       allowNull: false
  141.     },
  142.     createdAt: DataTypes.DATE,
  143.     updatedAt: DataTypes.DATE,
  144.   },
  145.   {
  146.     tableName: 'address',
  147.     sequelize // passing the `sequelize` instance is required
  148.   }
  149. );
  151. // You can also define modules in a functional way
  152. interface NoteAttributes {
  153.   id: number;
  154.   title: string;
  155.   content: string;
  156. }
  158. // You can also set multiple attributes optional at once
  159. type NoteCreationAttributes = Optional<NoteAttributes, 'id' | 'title'>;
  161. // And with a functional approach defining a module looks like this
  162. const Note: ModelDefined<
  163.   NoteAttributes,
  164.   NoteCreationAttributes
  165. > = sequelize.define(
  166.   'Note',
  167.   {
  168.     id: {
  169.       type: DataTypes.INTEGER.UNSIGNED,
  170.       autoIncrement: true,
  171.       primaryKey: true
  172.     },
  173.     title: {
  174.       type: new DataTypes.STRING(64),
  175.       defaultValue: 'Unnamed Note'
  176.     },
  177.     content: {
  178.       type: new DataTypes.STRING(4096),
  179.       allowNull: false
  180.     }
  181.   },
  182.   {
  183.     tableName: 'notes'
  184.   }
  185. );
  187. // Here we associate which actually populates out pre-declared `association` static and other methods.
  188. User.hasMany(Project, {
  189.   sourceKey: 'id',
  190.   foreignKey: 'ownerId',
  191.   as: 'projects' // this determines the name in `associations`!
  192. });
  194. Address.belongsTo(User, { targetKey: 'id' });
  195. User.hasOne(Address, { sourceKey: 'id' });
  197. async function doStuffWithUser() {
  198.   const newUser = await User.create({
  199.     name: 'Johnny',
  200.     preferredName: 'John',
  201.   });
  202.   console.log(newUser.id, newUser.name, newUser.preferredName);
  204.   const project = await newUser.createProject({
  205.     name: 'first!'
  206.   });
  208.   const ourUser = await User.findByPk(1, {
  209.     include: [User.associations.projects],
  210.     rejectOnEmpty: true // Specifying true here removes `null` from the return type!
  211.   });
  213.   // Note the `!` null assertion since TS can't know if we included
  214.   // the model or not
  215.   console.log(ourUser.projects![0].name);
  216. }
  218. (async () => {
  219.   await sequelize.sync();
  220.   await doStuffWithUser();
  221. })();

使用非严格类型

Sequelize v5 的类型允许你定义模型而无需指定属性类型. 对于向后兼容以及在你觉得对属性进行严格检查是不值得的情况下, 这仍然是可行的.

  1. import { Sequelize, Model, DataTypes } from 'sequelize';
  3. const sequelize = new Sequelize('mysql://root:asd123@localhost:3306/mydb');
  5. class User extends Model {
  6.   declare id: number;
  7.   declare name: string;
  8.   declare preferredName: string | null;
  9. }
  11. User.init(
  12.   {
  13.     id: {
  14.       type: DataTypes.INTEGER.UNSIGNED,
  15.       autoIncrement: true,
  16.       primaryKey: true,
  17.     },
  18.     name: {
  19.       type: new DataTypes.STRING(128),
  20.       allowNull: false,
  21.     },
  22.     preferredName: {
  23.       type: new DataTypes.STRING(128),
  24.       allowNull: true,
  25.     },
  26.   },
  27.   {
  28.     tableName: 'users',
  29.     sequelize, // passing the `sequelize` instance is required
  30.   },
  31. );
  33. async function doStuffWithUserModel() {
  34.   const newUser = await User.create({
  35.     name: 'Johnny',
  36.     preferredName: 'John',
  37.   });
  38.   console.log(newUser.id, newUser.name, newUser.preferredName);
  40.   const foundUser = await User.findOne({ where: { name: 'Johnny' } });
  41.   if (foundUser === null) return;
  42.   console.log(foundUser.name);
  43. }

使用 sequelize.define

在 v5 之前的 Sequelize 版本中, 定义模型的默认方式涉及使用 sequelize.define. 仍然可以使用它来定义模型, 也可以使用接口在这些模型中添加类型.

  1. import { Sequelize, Model, DataTypes, Optional } from 'sequelize';
  3. const sequelize = new Sequelize('mysql://root:asd123@localhost:3306/mydb');
  5. // We recommend you declare an interface for the attributes, for stricter typechecking
  6. interface UserAttributes {
  7.   id: number;
  8.   name: string;
  9. }
  11. // Some fields are optional when calling UserModel.create() or UserModel.build()
  12. interface UserCreationAttributes extends Optional<UserAttributes, 'id'> {}
  14. // We need to declare an interface for our model that is basically what our class would be
  15. interface UserInstance
  16.   extends Model<UserAttributes, UserCreationAttributes>,
  17.     UserAttributes {}
  19. const UserModel = sequelize.define<UserInstance>('User', {
  20.   id: {
  21.     primaryKey: true,
  22.     type: DataTypes.INTEGER.UNSIGNED,
  23.   },
  24.   name: {
  25.     type: DataTypes.STRING,
  26.   }
  27. });
  29. async function doStuff() {
  30.   const instance = await UserModel.findByPk(1, {
  31.     rejectOnEmpty: true,
  32.   });
  33.   console.log(instance.id);
  34. }

如果你对模型上非严格的属性检查命令感到满意，则可以通过定义 Instance 来扩展 Model 而无需泛型类型中的任何属性, 从而节省一些代码.

  1. import { Sequelize, Model, DataTypes } from 'sequelize';
  3. const sequelize = new Sequelize('mysql://root:asd123@localhost:3306/mydb');
  5. // We need to declare an interface for our model that is basically what our class would be
  6. interface UserInstance extends Model {
  7.   id: number;
  8.   name: string;
  9. }
  11. const UserModel = sequelize.define<UserInstance>('User', {
  12.   id: {
  13.     primaryKey: true,
  14.     type: DataTypes.INTEGER.UNSIGNED,
  15.   },
  16.   name: {
  17.     type: DataTypes.STRING,
  18.   },
  19. });
  21. async function doStuff() {
  22.   const instance = await UserModel.findByPk(1, {
  23.     rejectOnEmpty: true,
  24.   });
  25.   console.log(instance.id);
  26. }

实用程序类型

请求模型类

ModelStatic 旨在用于键入模型 class.

以下是请求模型类并返回该类中定义的主键列表的实用方法示例:

  1. import { ModelStatic, ModelAttributeColumnOptions, Model, InferAttributes, InferCreationAttributes, CreationOptional } from 'sequelize';
  3. /**
  4.  * Returns the list of attributes that are part of the model's primary key.
  5.  */
  6. export function getPrimaryKeyAttributes(model: ModelStatic<any>): ModelAttributeColumnOptions[] {
  7.   const attributes: ModelAttributeColumnOptions[] = [];
  9.   for (const attribute of Object.values(model.rawAttributes)) {
  10.     if (attribute.primaryKey) {
  11.       attributes.push(attribute);
  12.     }
  13.   }
  15.   return attributes;
  16. }
  18. class User extends Model<InferAttributes<User>, InferCreationAttributes<User>> {
  19.   id: CreationOptional<number>;
  20. }
  22. User.init({
  23.   id: {
  24.     type: DataTypes.INTEGER.UNSIGNED,
  25.     autoIncrement: true,
  26.     primaryKey: true
  27.   },
  28. }, { sequelize });
  30. const primaryAttributes = getPrimaryKeyAttributes(User);

获取模型的属性

如果您需要访问给定模型的属性列表, 你需要使用 Attributes<Model> 和 CreationAttributes<Model>.

它们将返回作为参数传递的模型的属性(和创建属性).

不要将它们与 InferAttributes 和 InferCreationAttributes 混淆. 这两种实用程序类型应该只被使用 在模型的定义中自动从模型的公共类字段创建属性列表. 它们仅适用于基于类的模型定义(使用 Model.init 时).

Attributes<Model> 和 CreationAttributes<Model> 将返回任何模型的属性列表, 无论它们是如何创建的(无论是 Model.init 还是 Sequelize#define).

这是一个请求模型类和属性名称的实用函数示例; 并返回相应的属性元数据.

  1. import {
  2.   ModelStatic,
  3.   ModelAttributeColumnOptions,
  4.   Model,
  5.   InferAttributes,
  6.   InferCreationAttributes,
  7.   CreationOptional,
  8.   Attributes
  9. } from 'sequelize';
  11. export function getAttributeMetadata<M extends Model>(model: ModelStatic<M>, attributeName: keyof Attributes<M>): ModelAttributeColumnOptions {
  12.   const attribute = model.rawAttributes[attributeName];
  13.   if (attribute == null) {
  14.     throw new Error(`Attribute ${attributeName} does not exist on model ${model.name}`);
  15.   }
  17.   return attribute;
  18. }
  20. class User extends Model<InferAttributes<User>, InferCreationAttributes<User>> {
  21.   id: CreationOptional<number>;
  22. }
  24. User.init({
  25.   id: {
  26.     type: DataTypes.INTEGER.UNSIGNED,
  27.     autoIncrement: true,
  28.     primaryKey: true
  29.   },
  30. }, { sequelize });
  32. const idAttributeMeta = getAttributeMetadata(User, 'id'); // works!
  34. // @ts-expect-error
  35. const nameAttributeMeta = getAttributeMetadata(User, 'name'); // fails because 'name' is not an attribute of User