Scopes - 作用域

作用域用于帮助你重用代码. 你可以定义常用查询,并指定诸如 where, include, limit 等参数.

本指南涉及模型作用域. 你可能也对关联作用域指南感兴趣,它们相似但又不同.

定义

作用域在模型定义中定义,可以是查找器对象,也可以是返回查找器对象的函数 - 默认作用域除外,该作用域只能是一个对象：

  1. class Project extends Model {}
  2. Project.init({
  3.   // 属性
  4. }, {
  5.   defaultScope: {
  6.     where: {
  7.       active: true
  8.     }
  9.   },
  10.   scopes: {
  11.     deleted: {
  12.       where: {
  13.         deleted: true
  14.       }
  15.     },
  16.     activeUsers: {
  17.       include: [
  18.         { model: User, where: { active: true } }
  19.       ]
  20.     },
  21.     random() {
  22.       return {
  23.         where: {
  24.           someNumber: Math.random()
  25.         }
  26.       }
  27.     },
  28.     accessLevel(value) {
  29.       return {
  30.         where: {
  31.           accessLevel: {
  32.             [Op.gte]: value
  33.           }
  34.         }
  35.       }
  36.     }
  37.     sequelize,
  38.     modelName: 'project'
  39.   }
  40. });

你也可以在定义模型后通过调用 YourModel.addScope 添加作用域. 这对于具有包含的作用域特别有用,其中在定义另一个模型时可能未定义包含中的模型.

始终应用默认作用域. 这意味着,使用上面的模型定义,Project.findAll() 将创建以下查询：

  1. SELECT * FROM projects WHERE active = true

可以通过调用 .unscoped(), .scope(null), 或调用另一个作用域来删除默认作用域：

  1. await Project.scope('deleted').findAll(); // 删除默认作用域
  1. SELECT * FROM projects WHERE deleted = true

也可以在作用域定义中包括作用域模型. 这样可以避免重复 include, attributes 或 where 定义. 使用上面的示例,并在包含的用户模型上调用 active 作用域(而不是直接在该包含对象中指定条件)：

  1. // 上例中定义的 `activeUsers` 作用域也可以通过以下方式定义：
  2. Project.addScope('activeUsers', {
  3.   include: [
  4.     { model: User.scope('active') }
  5.   ]
  6. });

使用

通过在模型定义上调用 .scope,并传递一个或多个作用域的名称来应用作用域..scope 返回具有所有常规方法的功能齐全的模型实例：.findAll, .update, .count, .destroy 等.你可以保存此模型实例并在以后重用：

  1. const DeletedProjects = Project.scope('deleted');
  2. await DeletedProjects.findAll();
  4. // 以上相当于:
  5. await Project.findAll({
  6.   where: {
  7.     deleted: true
  8.   }
  9. });

作用域适用于 .find, .findAll, .count, .update, .increment 和 .destroy.

作用域可以通过两种方式调用. 如果作用域不带任何参数,则可以正常调用它. 如果作用域接受参数,则传递一个对象：

  1. await Project.scope('random', { method: ['accessLevel', 19] }).findAll();

生成 SQL:

  1. SELECT * FROM projects WHERE someNumber = 42 AND accessLevel >= 19

合并

通过将作用域数组传递给 .scope 或将作用域作为连续参数传递,可以同时应用多个作用域.

  1. // 这两个是等效的
  2. await Project.scope('deleted', 'activeUsers').findAll();
  3. await Project.scope(['deleted', 'activeUsers']).findAll();

生成 SQL:

  1. SELECT * FROM projects
  2. INNER JOIN users ON projects.userId = users.id
  3. WHERE projects.deleted = true
  4. AND users.active = true

如果要在默认作用域之外应用另一个作用域,请将关键字 defaultScope 传递给.scope：

  1. await Project.scope('defaultScope', 'deleted').findAll();

生成 SQL:

  1. SELECT * FROM projects WHERE active = true AND deleted = true

调用多个合并作用域时,后续合并作用域中的键将覆盖先前合并作用域中的键(类似于 Object.assign),除了将合并的 where 和 include 之外. 考虑两个作用域：

  1. YourMode.addScope('scope1', {
  2.   where: {
  3.     firstName: 'bob',
  4.     age: {
  5.       [Op.gt]: 20
  6.     }
  7.   },
  8.   limit: 2
  9. });
  10. YourMode.addScope('scope2', {
  11.   where: {
  12.     age: {
  13.       [Op.gt]: 30
  14.     }
  15.   },
  16.   limit: 10
  17. });

使用 .scope('scope1', 'scope2') 将产生以下 WHERE 子句：

  1. WHERE firstName = 'bob' AND age > 30 LIMIT 10

注意 limit 和 age 如何被 scope2 覆盖,而保留 firstName.limit, offset, order, paranoid, lock 和 raw 字段被覆盖,而 where 则被浅合并(这意味着相同的键将被覆盖).包含的合并策略将在后面讨论.

注意,多个应用作用域的 attributes 键以始终保留 attributes.exclude 的方式合并. 这允许合并多个合并作用域,并且永远不会泄漏最终合并作用域中的敏感字段.

当将查找对象直接传递给作用域模型上的 findAll(和类似的查找器)时,适用相同的合并逻辑：

  1. Project.scope('deleted').findAll({
  2.   where: {
  3.     firstName: 'john'
  4.   }
  5. })

生成的 where 子句：

  1. WHERE deleted = true AND firstName = 'john'

在这里, deleted 作用域与查找器合并. 如果我们将 where: { firstName: 'john', deleted: false } 传递给查找器,则 deleted 作用域将被覆盖.

合并 Include

Include 将基于所包含的模型进行递归合并. 这是 v5 上添加的功能非常强大的合并,并通过示例更好地理解.

考虑模型 Foo, Bar, Baz 和 Qux,它们具有一对多关联,如下所示：

  1. const Foo = sequelize.define('Foo', { name: Sequelize.STRING });
  2. const Bar = sequelize.define('Bar', { name: Sequelize.STRING });
  3. const Baz = sequelize.define('Baz', { name: Sequelize.STRING });
  4. const Qux = sequelize.define('Qux', { name: Sequelize.STRING });
  5. Foo.hasMany(Bar, { foreignKey: 'fooId' });
  6. Bar.hasMany(Baz, { foreignKey: 'barId' });
  7. Baz.hasMany(Qux, { foreignKey: 'bazId' });

现在,考虑在 Foo 上定义的以下四个作用域:

  1. Foo.addScope('includeEverything', {
  2.   include: {
  3.     model: Bar,
  4.     include: [{
  5.       model: Baz,
  6.       include: Qux
  7.     }]
  8.   }
  9. });
  11. Foo.addScope('limitedBars', {
  12.   include: [{
  13.     model: Bar,
  14.     limit: 2
  15.   }]
  16. });
  18. Foo.addScope('limitedBazs', {
  19.   include: [{
  20.     model: Bar,
  21.     include: [{
  22.       model: Baz,
  23.       limit: 2
  24.     }]
  25.   }]
  26. });
  28. Foo.addScope('excludeBazName', {
  29.   include: [{
  30.     model: Bar,
  31.     include: [{
  32.       model: Baz,
  33.       attributes: {
  34.         exclude: ['name']
  35.       }
  36.     }]
  37.   }]
  38. });

这四个作用域可以很容易地进行深度合并,例如,通过调用 Foo.scope('includeEverything', 'limitedBars', 'limitedBazs', 'excludeBazName').findAll(),这完全等同于调用以下代码：

  1. await Foo.findAll({
  2.   include: {
  3.     model: Bar,
  4.     limit: 2,
  5.     include: [{
  6.       model: Baz,
  7.       limit: 2,
  8.       attributes: {
  9.         exclude: ['name']
  10.       },
  11.       include: Qux
  12.     }]
  13.   }
  14. });
  16. // 以上等同于：
  17. await Foo.scope([
  18.   'includeEverything',
  19.   'limitedBars',
  20.   'limitedBazs',
  21.   'excludeBazName'
  22. ]).findAll();

观察如何将四个作用域合并为一个. 作用域的 include 根据所包含的模型进行合并. 如果一个作用域包含模型 A,另一个作用域包含模型 B,则合并结果将同时包含模型 A 和 B.另一方面,如果两个作用域都包含相同的模型 A,但具有不同的参数(例如嵌套包含或其他属性) ,这些将被递归合并,如上所示.

上面说明的合并以完全相同的方式工作,而不管应用于作用域的顺序如何. 如果某个选项由两个不同的作用域设置,则顺序只会有所不同 - 上面的示例不是这种情况,因为每个作用域执行的操作都不相同.

这种合并策略还可以与传递给 .findAll, .findOne 等的参数完全相同.