Sequelize 中文文档及sequelize模块的一些说明

本文是对Sequelize 中文API文档系列文章的综合索引，及对sequelize模块和其内置对象的一些介绍，旨在帮助人们更好了解和使用Sequelize。

1. 文档索引
2. 官方文档对照
3. sequelize模块介绍
   • 3.1 顶级对象Sequelize
   • 3.2 Model对象的实例化
   • 3.3 Instance实例的创建

在操作关系型数据库时，我们一般都会选择一个ORM框架，以封装复杂的业务逻辑，用面向对象的方式来操作数据表，替代直接的SQL操作。Sequelize是一个用于Node.js 和 io.js的非常优秀的ORM框架, 支持PostgreSQL、MySQL、SQLite、MSSQL等多种关系型数据库。

1. 文档索引

Sequelize 中文API文档系列共包括9篇，为了方便阅读及查看本站将官方文档中，相关对象的使用介绍（Documentation）部分及对象的API部分整理到了一起。文档索引如下：

1. 快速入门、Sequelize类

   Sequelize类是引用sequlize模块后获取一个顶级对象，我们通过它来创建sequlize实例，也可以通过该对象来获取模内其它对象的引用，如：Utils工具类、Transaction事务类等。创建实例后，可以通过实例来创建或定义Model（模型）、执行查询、同步数据库结构等操作。

2. Model 的定义、使用与Model类的API

   Model相当于数据库中表，有时它也会被称为“模型”或“工厂”。Model不能通过构造函数创建，而只能通过sequlize.define方法来定义或通过sequlize.import导入。通过define定义一个Model，就相当于定义了一种模型与数据表之间的映射关系，通过模型可以实现对表记录的增、删、改、查等操作。

3. 模型（表）之间的关系/关联

   模型（Model）之间存在各种各样的关系，如：一对一(One-To-One ）、一对多（One-To-Many）等。模型间的关系本质上是对其代表的数据库中表之间的关系描述，通过这些关系可以实现数据库中表之间主/外键约束的创建。查询时也可以基于这些关系，生成在数据库中执行的连接查询或复合查询SQL语句。

4. 查询与原始查询

   Sequelize中有两种查询：使用Model（模型）中的方法查询和使用sequelize.query()进行基于SQL语句的原始查询。

5. 实例的使用、Instance类介绍

   Instance类表示数据库中的一行记录，该类不能直接实例化，而应该由Model对象创建。Instance实例有两种，由Model.build方法创建的非持久化实例，和由Model.create方法创建的持久化实例。应该注意，Instance翻译后也叫做“实例”，但它在Sequelize 中是一个类，它的实例应该叫做“实例”类的实例。

6. 事务的使用与Transaction类

   Transaction是Sequelize中用于实现事务功能的子类，通过调用Sequelize.transaction()方法可以创建一个该类的实例。在Sequelize中，支持自动提交/回滚，也可以支持用户手动提交/回滚

7. Scopes 作用域的使用

   Scopes - 作用域，表示一个限制范围，它最终会生成SQL查询中的where子句。它在模型定义方法sequelize.define的option参数，或通过Model.scope()方法指定。

8. 钩子函数的使用、Hooks相关API

   Hooks（钩子）是指会在模型生命周期的特殊时刻被调用的函数，如：模型实例被创建前会调用beforeCreate函数，而在模型实例创建后又会调用afterCreate函数。通过这些钩子函数，使用我们具有在生命周期的特殊时刻访问或操作模型数据的能力。

9. 数据类型类 DataTypes 及其API

   在使用sequelize.define方法定义模型时，我们一般会为模型属性（列）指定类型type，它表示数据类型，Sequelize会按指定的类型在数据库中创建字段。这些类型被定义到了sequelize模块的DataTypes类中，它是一个静态类可以直接引用其属性或方法。

10. Migrations 数据迁移与QueryInterface对象

    Sequelize 2.0.0引入了一个新的CLI（命令行工具），其基于gulp并结合sequelize-cli和gulp-sequelize，CLI用于支持数据迁移和项目引导。通过迁移，可以将现有数据库迁移到另一个状态，反之亦然：这些迁移文件会被保存在迁移文件中，迁移文件描述了怎样到达新状态以及如何恢复更改以返回到迁移前的旧状态。

2. 官方文档对照

在Sequelize官方文档中，其对Sequelize模块的介绍主要分为：Documentation、API两部分。Documentation介绍模块、模块内置对象等的使用方法；API介绍Sequelize及其内置对象的API。Sequelize 中文API文档中包含了大多数对象使用介绍及对象API的翻译，但对于不常使用的，如Errors等对象未做翻译，需要时请自己查看官方文档。官文档与Sequelize 中文API文档对照关系如下：

• Documentation
  • Getting Started - 快速入门
  • Working with table schemas - 未翻译
    • Models
    • Definition - Model定义描述
    • Usage - Model模型的使用
  • Querying - Model查询
  • Scopes - Scopes 作用域的使用
  • Instances - 实例的创建与使用
  • Relations / Associations - 关系/关联的使用
  • Hooks - 钩子函数的使用
  • Transactions - 事务的使用
  • Working with legacy tables - 未翻译
  • Raw queries - 原始查询
  • Migrations - Migrations 数据迁移与QueryInterface对象
• API
  • Sequelize - Sequelize类
  • Model - Model类的API
  • Instance - Instance类的API
    • Associations
    • Overview - 关联关系综合介绍
    • BelongsTo (1:1) - 属于关系
    • HasOne (1:1) - 拥有一个关系
    • HasMany (1:m) - 一对多个关系
    • BelongsToMany (n:m) - 多对多关系
  • Hooks - Hooks类的API
  • Transaction - Transaction类
  • Datatypes - 数据类型类 DataTypes 及其API
  • Deferrable - 未翻译
  • Errors - 未翻译

3. sequelize模块介绍

sequelize模块中包含一个顶级对象Sequelize，我们可以通过它来创建sequlize实例，或获取其它子对象的引用。sequelize模块中主要子对象有，Model模型对象、Instance实例对象、Transaction事务对象等。 我们还可以通过sequelize模块，使用其内部使用Validator验证对象、Utils工具及Promise等子对象。

3.1 顶级对象Sequelize

通过require('sequelize')引用模块后，我们会获得一个对Sequelize主类的访问权限：

var Sequelize = require('sequelize');

创建数据库访问实例

Sequelize同时也是一个构造函数，我们可以通过这个构造函数创建到指定数据库的访问实例－sequelize：

var sequelize = new Sequelize('database', 'username', 'password');

子对象访问

sequelize中有子对象有Model、Instance等模块定义的，ORM相关的子对象，也有Validator、Utils等sequelize模块所依赖的模块，这些类都有可以通过项级对象Sequelize或sequelize实例对象访问，但Model、Instance对象确不能直接进行实例化。

这些对象在sequelize中的添加形式如下：

Sequelize.prototype.Model = Sequelize.Model = Model;
Sequelize.prototype.Instance = Sequelize.Instance = Instance;

Sequelize.prototype.Utils = Sequelize.Utils = Utils;
Sequelize.prototype.Validator = Sequelize.Validator = require('validator');

3.2 Model对象的实例化

如上面所有，我们可以通过Sequelize.Model或sequelize.Model来访问Model对象，但确不能直接通过new来实例化。只能通过sequelize实例的sequlize.define方法定义或通过sequlize.import导入来创建Model实例：

// 通过 define 来实例化Model
var User = sequelize.define('user', {
  username: Sequelize.STRING,
  birthday: Sequelize.DATE
});

// 通过 import 来实例化Model
// 这个文件定义于 /path/to/models/project.js
module.exports = function(sequelize, DataTypes) {
  return sequelize.define("project", {
    name: DataTypes.STRING,
    description: DataTypes.TEXT
  })
}

var Project = sequelize.import(__dirname + "/path/to/models/project")

3.3 Instance实例的创建

Instance表示数据表中的一行，该对象同样不能直接实例化。它会在Model实例进行find或create等操作时自动创建，并在回调函数中返回。Instance实例有两种：持久化实例、百持久化实例。我们可以像下面这样创建一个非持久化实列：

// 定义模型
var Task = sequelize.define('task', {
  title: Sequelize.STRING,
  rating: { type: Sequelize.STRING, defaultValue: 3 }
})
 
// build 构建一个 Instance 实例
var task = Task.build({title: 'very important task'})

创建Instance实例后，就可以通过该实例对这条记录进行修改保存等操作：

task.save().then(function() {
  // 保存后的回调
})

或者可以通过Model.create方法创建一个持久化实例：

Task.create({ title: 'foo', description: 'bar', deadline: new Date() }).then(function(task) {
  // task 是一个持久化实例
})