【原创】backbone1.1.0源码解析之Model

趁热打铁，将Backbone.Model的源代码注释也发出来。

Model是用来干嘛的？写过mvc的同学应该都知道，说白了就是model实例用来存储数据表中的一行数据（row）

Backbone利用model的attributes与数据库的字段一一对应，通过ajax获取数据后，在前端进行存储，又提供了一系列的方法，

在改变model实例的同时，完成关联视图view的更新，和服务器端数据的更新，从而达到mvc的效果。

下面就是Backbone.Model的源码注释了，如果错误了还望指出来，或者不清晰，可以给我留言

  // Backbone.Model
  // --------------

  // Backbone **Models** are the basic data object in the framework --
  // frequently representing a row in a table in a database on your server.
  // A discrete chunk of data and a bunch of useful, related methods for
  // performing computations and transformations on that data.

  // Create a new model with the specified attributes. A client id (`cid`)
  // is automatically generated and assigned for you.
  // Model构造器，大概在this对象上添加的属性
  // {
  //   cid : 'cxxx',
  //   attributes : {...},
  //   changed : {}
  // }
  // options可选参数（在进行model实例方法调用时还会见到更多的options参数）
  // {
  //   collection : true(false),
  //   parse : true(false),
  // }
  var Model = Backbone.Model = function(attributes, options) {
    var attrs = attributes || {};
    options || (options = {});
    // model对象唯一id
    this.cid = _.uniqueId('c');
    // model的属性集合
    this.attributes = {};
    // 指定model所属的collection
    if (options.collection) this.collection = options.collection;
    // 对attrs进行过滤，默认parse函数返回原attrs，继承时可以根据需要进行重写
    if (options.parse) attrs = this.parse(attrs, options) || {};
    // 将attrs中没有被设置的属性，设置默认值
    // 这里的defaults是自定义的，可以是{...}，也可以是返回{...}的函数
    attrs = _.defaults({}, attrs, _.result(this, 'defaults'));
    this.set(attrs, options);
    // 因为是构造函数，所以重置上述调用set操作带来的引起changed变化
    this.changed = {};
    // 执行初始化操作，用户可自定义
    this.initialize.apply(this, arguments);
  };

  // Attach all inheritable methods to the Model prototype.
  // Model实例公有方法（添加了事件机制）
  _.extend(Model.prototype, Events, {

    // A hash of attributes whose current and previous value differ.
    // 改变过的属性集合
    changed: null,

    // The value returned during the last failed validation.
    // 执行validate方法时，如果验证失败，那么失败的结果会放在该变量里
    validationError: null,

    // The default name for the JSON `id` attribute is `"id"`. MongoDB and
    // CouchDB users may want to set this to `"_id"`.
    // 自定义数据库返回的唯一键的名字
    idAttribute: 'id',

    // Initialize is an empty function by default. Override it with your own
    // initialization logic.
    // 一般会覆盖用于自定义初始化操作
    initialize: function(){},

    // Return a copy of the model's `attributes` object.
    toJSON: function(options) {
      return _.clone(this.attributes);
    },

    // Proxy `Backbone.sync` by default -- but override this if you need
    // custom syncing semantics for *this* particular model.
    // 调用Backbone.sync，可以通过改写Backbone.sync来实现自己的异步操作
    sync: function() {
      return Backbone.sync.apply(this, arguments);
    },

    // Get the value of an attribute.
    // 获取属性值
    get: function(attr) {
      return this.attributes[attr];
    },

    // Get the HTML-escaped value of an attribute.
    // 获取经过html-escaped过的属性值，主要事为了防止xss攻击
    escape: function(attr) {
      return _.escape(this.get(attr));
    },

    // Returns `true` if the attribute contains a value that is not null
    // or undefined.
    // 判断是否含有某个属性值
    has: function(attr) {
      return this.get(attr) != null;
    },

    // Set a hash of model attributes on the object, firing `"change"`. This is
    // the core primitive operation of a model, updating the data and notifying
    // anyone who needs to know about the change in state. The heart of the beast.
    // 设置属性值，触发对应属性的的change事件，触发对象的change事件
    set: function(key, val, options) {
      var attr, attrs, unset, changes, silent, changing, prev, current;
      if (key == null) return this;

      // Handle both `"key", value` and `{key: value}` -style arguments.
      // 处理属性集合，({key1: value1, key2: value2, ...}, [options])
      if (typeof key === 'object') {
        attrs = key;
        options = val;
      } else {
      // 处理(key1, value1, [options])
        (attrs = {})[key] = val;
      }

      options || (options = {});

      // Run validation.
      // 验证失败了，set也就失败了
      if (!this._validate(attrs, options)) return false;

      // Extract attributes and options.
      // unset 用于删除属性
      unset           = options.unset;
      // silent 用于控制是否触发对应属性的change事件
      silent          = options.silent;
      changes         = [];
      changing        = this._changing;
      this._changing  = true;

      // 这里判断其实是介于接下来的trigger change事件里面还可能在进行set操作
      // 而_previousAttributes和changed依附于this对象实现共享
      // 这里是考虑到用户自定义change回调时，循环迭代的问题
      if (!changing) {
        // 保存修改前的属性
        this._previousAttributes = _.clone(this.attributes);
        this.changed = {};
      }
      current = this.attributes, prev = this._previousAttributes;

      // Check for changes of `id`.
      // 设置id，这里的id是只数据库中的唯一键，不同于cid
      if (this.idAttribute in attrs) this.id = attrs[this.idAttribute];

      // For each `set` attribute, update or delete the current value.
      for (attr in attrs) {
        val = attrs[attr];
        // 与当前值就行比较，如果不一样，那么记录这个改变
        if (!_.isEqual(current[attr], val)) changes.push(attr);
        if (!_.isEqual(prev[attr], val)) {
          // 记录改变的属性
          this.changed[attr] = val;
        } else {
          // 如果在迭代中属性又还原不变了，那么删除掉
          delete this.changed[attr];
        }
        // 删除或者更新属性
        unset ? delete current[attr] : current[attr] = val;
      }

      // Trigger all relevant attribute changes.
      // 触发属性改变的事件，如：change:attr1
      if (!silent) {
        if (changes.length) this._pending = true;
        for (var i = 0, l = changes.length; i < l; i++) {
          this.trigger('change:' + changes[i], this, current[changes[i]], options);
        }
      }

      // You might be wondering why there's a `while` loop here. Changes can
      // be recursively nested within `"change"` events.
      // 这里返回this，是因为上面进行trigger change:attr1时，用户自定义函数可能会再次进行set操作
      // 而接下来的有些操作是针对对象本身的，只需要被执行一次
      if (changing) return this;
      if (!silent) {
        // 如果属性有改变，那么触发对象的change事件
        // 这里的循环同样是为了处理change事件的回调函数里面包含set操作而引发change事件
        // 因为上述的changing会进行return，那么通过this._pending来进行while判断，来执行多次对象的change事件回调
        // 这里依然是循环迭代的问题
        while (this._pending) {
          this._pending = false;
          this.trigger('change', this, options);
        }
      }
      // 恢复状态
      this._pending = false;
      this._changing = false;
      return this;
    },

    // Remove an attribute from the model, firing `"change"`. `unset` is a noop
    // if the attribute doesn't exist.
    // unset实质是利用set方法，只需将options.unset设置为true
    unset: function(attr, options) {
      return this.set(attr, void 0, _.extend({}, options, {unset: true}));
    },

    // Clear all attributes on the model, firing `"change"`.
    // 清除所有属性
    clear: function(options) {
      var attrs = {};
      for (var key in this.attributes) attrs[key] = void 0;
      return this.set(attrs, _.extend({}, options, {unset: true}));
    },

    // Determine if the model has changed since the last `"change"` event.
    // If you specify an attribute name, determine if that attribute has changed.
    hasChanged: function(attr) {
      // 如果attr为空，那么通过查看this.changed来判断对象是否改变（即是否有某一属性改变）
      if (attr == null) return !_.isEmpty(this.changed);
      // 返回是否某一个特定属性改变了
      return _.has(this.changed, attr);
    },

    // Return an object containing all the attributes that have changed, or
    // false if there are no changed attributes. Useful for determining what
    // parts of a view need to be updated and/or what attributes need to be
    // persisted to the server. Unset attributes will be set to undefined.
    // You can also pass an attributes object to diff against the model,
    // determining if there *would be* a change.
    // 返回changed属性列表，没有改变则返回false
    // 如果有传递diff，那么就进行attributes和diff的比较，筛选出属性值不一样的属性
    changedAttributes: function(diff) {
      if (!diff) return this.hasChanged() ? _.clone(this.changed) : false;
      var val, changed = false;
      // 还是考虑循环迭代的问题
      var old = this._changing ? this._previousAttributes : this.attributes;
      for (var attr in diff) {
        if (_.isEqual(old[attr], (val = diff[attr]))) continue;
        (changed || (changed = {}))[attr] = val;
      }
      return changed;
    },

    // Get the previous value of an attribute, recorded at the time the last
    // `"change"` event was fired.
    // 返回修改前的某个属性值
    previous: function(attr) {
      if (attr == null || !this._previousAttributes) return null;
      return this._previousAttributes[attr];
    },

    // Get all of the attributes of the model at the time of the previous
    // `"change"` event.
    // 返回修改前的属性集合
    previousAttributes: function() {
      return _.clone(this._previousAttributes);
    },

    // Fetch the model from the server. If the server's representation of the
    // model differs from its current attributes, they will be overridden,
    // triggering a `"change"` event.
    // 从服务器端获取数据，填充model
    fetch: function(options) {
      options = options ? _.clone(options) : {};
      if (options.parse === void 0) options.parse = true;
      var model = this;
      var success = options.success;
      // 回调success函数
      options.success = function(resp) {
        // 设置model的值（可能会验证失败），那么返回false
        if (!model.set(model.parse(resp, options), options)) return false;
        if (success) success(model, resp, options);
        model.trigger('sync', model, resp, options);
      };
      // 包装回调error函数
      wrapError(this, options);
      // 异步获取数据
      return this.sync('read', this, options);
    },

    // Set a hash of model attributes, and sync the model to the server.
    // If the server returns an attributes hash that differs, the model's
    // state will be `set` again.
    save: function(key, val, options) {
      var attrs, method, xhr, attributes = this.attributes;

      // Handle both `"key", value` and `{key: value}` -style arguments.
      // 上述所说的参数兼容
      if (key == null || typeof key === 'object') {
        attrs = key;
        options = val;
      } else {
        (attrs = {})[key] = val;
      }

      // 保存前要要做前端验证
      options = _.extend({validate: true}, options);

      // If we're not waiting and attributes exist, save acts as
      // `set(attr).save(null, opts)` with validation. Otherwise, check if
      // the model will be valid when the attributes, if any, are set.
      // options.wait为true用于等待服务器返回结果，再进行属性值的设置（进而view变化）
      // 为false的话，先进行数据验证，再设置属性值（改变view, 拥有更好的用户体验），再提交数据，
      //（这样的话等待服务器返回结果先还原attributes，进行属性值的set操作，包含验证）
      if (attrs && !options.wait) {
        if (!this.set(attrs, options)) return false;
      } else {
        if (!this._validate(attrs, options)) return false;
      }

      // Set temporary attributes if `{wait: true}`.
      // 因为接下来的Backbone.async中的再取数据时，会先取options.attrs的值，
      // 取不到就会执行model.toJson()来获得所有属性作为数据
      // 这里暂时改变this.attributes的值，不用set（因为set还要触发change等等）
      if (attrs && options.wait) {
        this.attributes = _.extend({}, attributes, attrs);
      }

      // After a successful server-side save, the client is (optionally)
      // updated with the server-side state.
      // 数据过滤
      if (options.parse === void 0) options.parse = true;
      var model = this;
      var success = options.success;
      options.success = function(resp) {
        // Ensure attributes are restored during synchronous saves.
        // 还原属性值
        model.attributes = attributes;
        var serverAttrs = model.parse(resp, options);
        // 用服务端的修正的数据覆盖并合并attrs
        if (options.wait) serverAttrs = _.extend(attrs || {}, serverAttrs);
        // 服务器端返回的数据更新attributes
        // 对于wait为true的情况，此时view才刚得以变化
        // 对于wait为false的情况，应该再此时再一次对view进行改变或者纠正，
        if (_.isObject(serverAttrs) && !model.set(serverAttrs, options)) {
          return false;
        }
        // 成功回调函数
        if (success) success(model, resp, options);
        model.trigger('sync', model, resp, options);
      };
      wrapError(this, options);

      // 新数据用create来创建
      // 否则用patch表示只提交改变的attrs，或者update表示提交所有的属性
      method = this.isNew() ? 'create' : (options.patch ? 'patch' : 'update');
      if (method === 'patch') options.attrs = attrs;
      xhr = this.sync(method, this, options);

      // Restore attributes.
      // 还原之前为了提交数据的临时改变
      if (attrs && options.wait) this.attributes = attributes;

      return xhr;
    },

    // Destroy this model on the server if it was already persisted.
    // Optimistically removes the model from its collection, if it has one.
    // If `wait: true` is passed, waits for the server to respond before removal.
    // 删除服务器端model数据
    destroy: function(options) {
      options = options ? _.clone(options) : {};
      var model = this;
      var success = options.success;

      var destroy = function() {
        model.trigger('destroy', model, model.collection, options);
      };

      options.success = function(resp) {
        // 等待服务器端返回或者新model，执行前端destory
        if (options.wait || model.isNew()) destroy();
        if (success) success(model, resp, options);
        // 不是新model执行远程请求成功的sync事件
        if (!model.isNew()) model.trigger('sync', model, resp, options);
      };

      // 新数据，服务器端不存在，那么只需要进行本地操作就行了
      if (this.isNew()) {
        options.success();
        return false;
      }
      wrapError(this, options);

      // 异步删除
      var xhr = this.sync('delete', this, options);
      // 不等待服务器返回结果，先前端删除
      if (!options.wait) destroy();
      return xhr;
    },

    // Default URL for the model's representation on the server -- if you're
    // using Backbone's restful methods, override this to change the endpoint
    // that will be called.
    // 返回当前model实例对应的url
    // 默认规则是：[collection.url]/[id]
    url: function() {
      var base = _.result(this, 'urlRoot') || _.result(this.collection, 'url') || urlError();
      if (this.isNew()) return base;
      return base + (base.charAt(base.length - 1) === '/' ? '' : '/') + encodeURIComponent(this.id);
    },

    // **parse** converts a response into the hash of attributes to be `set` on
    // the model. The default implementation is just to pass the response along.
    // 对数据进行解析过滤，用户可根据需求自定义
    parse: function(resp, options) {
      return resp;
    },

    // Create a new model with identical attributes to this one.
    // 克隆当前对象（即用相同attributes初始化）
    clone: function() {
      return new this.constructor(this.attributes);
    },

    // A model is new if it has never been saved to the server, and lacks an id.
    // 通过this.id来判断对象数据是否是从服务器取过来的，因为数据库的数据都是有唯一id的嘛
    isNew: function() {
      return this.id == null;
    },

    // Check if the model is currently in a valid state.
    // 检查当前的attributes是否合法，返回验证结果
    isValid: function(options) {
      return this._validate({}, _.extend(options || {}, { validate: true }));
    },

    // Run validation against the next complete set of model attributes,
    // returning `true` if all is well. Otherwise, fire an `"invalid"` event.
    // 对进行set或者save操作时，会对设置的属性数据进行验证
    _validate: function(attrs, options) {
      // 验证的条件
      // 1. options有设置validate参数为true
      // 2. 存在自定义的validate函数
      if (!options.validate || !this.validate) return true;
      // 将需要验证的attrs和对象原有的this.attributes属性合并到一个空对象上
      // 目的是，用户用validate时，可能需要参考一些已经设置好的属性值
      attrs = _.extend({}, this.attributes, attrs);
      // 验证函数验证失败返回错误信息，成功返回空值
      var error = this.validationError = this.validate(attrs, options) || null;
      if (!error) return true;
      // 验证失败，触发invalid事件
      this.trigger('invalid', this, error, _.extend(options, {validationError: error}));
      return false;
    }

  });

  // 添加几个用的underscore.js里的方法到model中，用于处理this.attributes，
  // 毕竟this.attributes是个对象也是个集合嘛，用underscore会很方便
  // Underscore methods that we want to implement on the Model.
  var modelMethods = ['keys', 'values', 'pairs', 'invert', 'pick', 'omit'];

  // Mix in each Underscore method as a proxy to `Model#attributes`.
  _.each(modelMethods, function(method) {
    Model.prototype[method] = function() {
      var args = slice.call(arguments);
      // 第一个参数时属性集合
      args.unshift(this.attributes);
      return _[method].apply(_, args);
    };
  });