Django 新增一条纪录背后发生的事 - 知乎

# django/db/models/base.py

def save(self, force_insert=False, force_update=False, using=None, update_fields=None):
    """
    force_insert, force_update 强制 save() 执行INSERT或UPDATE
    using 指定保存的数据库,setting.py中配置的DATABASES的key，默认是'default'
    这个函数主要是检查和处理字段的一些额外情况
    """

     # 检查外键关系的正确性并清除缓存
    for field in self._meta.concrete_fields:
        if field.is_relation and field.is_cached(self):
            obj = getattr(self, field.name, None)
            if obj and obj.pk is None:
                if not field.remote_field.multiple:
                    field.remote_field.delete_cached_value(obj)
                raise ValueError(
                    "save() prohibited to prevent data loss due to "
                    "unsaved related object '%s'." % field.name
                )
    
    using = using or router.db_for_write(self.__class__, instance=self)

    if force_insert and (force_update or update_fields):
        raise ValueError("Cannot force both insert and updating in model saving.")
 
    deferred_fields = self.get_deferred_fields()

    # 处理有指定更新的字段
    if update_fields is not None:
        if len(update_fields) == 0:
            return

        update_fields = frozenset(update_fields) # fronzenset 创建的是一个不可变集合
        field_names = set()

        for field in self._meta.fields:
            if not field.primary_key:
                field_names.add(field.name)

                if field.name != field.attname:
                    field_names.add(field.attname)

        non_model_fields = update_fields.difference(field_names)

        if non_model_fields:
            raise ValueError("The following fields do not exist in this "
                             "model or are m2m fields: %s"
                             % ', '.join(non_model_fields))

    # 这里不大明白什么情况会触发
    elif not force_insert and deferred_fields and using == self._state.db:
        field_names = set()
        for field in self._meta.concrete_fields:
            if not field.primary_key and not hasattr(field, 'through'):
                field_names.add(field.attname)
        loaded_fields = field_names.difference(deferred_fields)
        if loaded_fields:
            update_fields = frozenset(loaded_fields)

    # 保存动作进入下一个函数
    self.save_base(using=using, force_insert=force_insert,
                   force_update=force_update, update_fields=update_fields)

def save_base(self, raw=False, force_insert=False,
              force_update=False, using=None, update_fields=None):
    """
    这个函数的主要功能有
    1 跳过代理
    2 发出信号
    3 开启事务执行
    """

    # 再次检查参数正确性
    using = using or router.db_for_write(self.__class__, instance=self)
    assert not (force_insert and (force_update or update_fields))
    assert update_fields is None or len(update_fields) > 0

    cls = origin = self.__class__
    # 如果是代理model,则跳过代理
    if cls._meta.proxy:
        cls = cls._meta.concrete_model
    meta = cls._meta

    # 步骤1 发出保存前信号
    if not meta.auto_created:
        pre_save.send(
            sender=origin, instance=self, raw=raw, using=using,
            update_fields=update_fields,
        )

    # 在事务下执行
    with transaction.atomic(using=using, savepoint=False):
        if not raw:
            self._save_parents(cls, using, update_fields) 
        updated = self._save_table(raw, cls, force_insert, force_update, using, update_fields) # 执行函数，进入下一步

    # 保存状态
    self._state.db = using
    self._state.adding = False

    # 步骤5 发出保存完成的信号
    if not meta.auto_created:
        post_save.send(
            sender=origin, instance=self, created=(not updated),
            update_fields=update_fields, raw=raw, using=using,
        )

def _save_table(self, raw=False, cls=None, force_insert=False,
                force_update=False, using=None, update_fields=None):
    """
    这个函数主要的功能就是分配UPDATE或INSERT操作
    """
    meta = cls._meta
    
    non_pks = [f for f in meta.local_concrete_fields if not f.primary_key]
    if update_fields:
        non_pks = [f for f in non_pks
                   if f.name in update_fields or f.attname in update_fields]

    # 获取pk的值,如果是更新则pk值就可以获取到
    pk_val = self._get_pk_val(meta)
    if pk_val is None:
        pk_val = meta.pk.get_pk_value_on_save(self)
        setattr(self, meta.pk.attname, pk_val)
    pk_set = pk_val is not None
    if not pk_set and (force_update or update_fields):
        raise ValueError("Cannot force an update in save() with no primary key.")
    updated = False

    # 如果pk值有了尝试使用UPDATE，所以save()处理是更新还是插入纪录就靠这个pk值来判断
    if pk_set and not force_insert:
        base_qs = cls._base_manager.using(using)
        values = [(f, None, (getattr(self, f.attname) if raw else f.pre_save(self, False)))
                  for f in non_pks]
        forced_update = update_fields or force_update

        # _do_update() 更新操作
        updated = self._do_update(base_qs, using, pk_val, values, update_fields,
                                  forced_update)

        if force_update and not updated:
            raise DatabaseError("Forced update did not affect any rows.")
        if update_fields and not updated:
            raise DatabaseError("Save with update_fields did not affect any rows.")

    # 执行插入
    if not updated:
        if meta.order_with_respect_to:
            field = meta.order_with_respect_to
            filter_args = field.get_filter_kwargs_for_object(self)
            order_value = cls._base_manager.using(using).filter(**filter_args).count()
            self._order = order_value
        fields = meta.local_concrete_fields
        if not pk_set:
            fields = [f for f in fields if f is not meta.auto_field]
        update_pk = meta.auto_field and not pk_set

        # _do_insert() 插入操作, 返回一个新建的pk值
        result = self._do_insert(cls._base_manager, using, fields, update_pk, raw)

        # 设置这个新新生成的pk值，用于判断
        if update_pk:
            setattr(self, meta.pk.attname, result)

    return updated

def _do_insert(self, manager, using, fields, update_pk, raw):
    """
    调用model的管理器执行INSERT
    """
    return manager._insert([self], fields=fields, return_id=update_pk,
                       using=using, raw=raw)

# django/db/models/query.py

def _insert(self, objs, fields, return_id=False, raw=False, using=None):
    """
    管理器单独新建一个InserQuery实例,通过查询集去转化
    """
    self._for_write = True
    if using is None:
        using = self.db
    query = sql.InsertQuery(self.model)
    query.insert_values(fields, objs, raw=raw)
    return query.get_compiler(using=using).execute_sql(return_id)

class InsertQuery(Query):
    compiler = 'SQLInsertCompiler'

    def get_compiler(self, using=None, connection=None):
        """
        这个函数的主要功能就是找出对应数据库（比如mysql）中SQLInsertCompiler的实现
        """
        if using is None and connection is None:
            raise ValueError("Need either using or connection")
        if using:
            connection = connections[using]
        return connection.ops.compiler(self.compiler)(self, connection, using)

# django/db/models/sql/compiler.py 
class SQLInsertCompiler(SQLCompiler):

    def execute_sql(self, return_id=False):
    """
    这个函数主要就是执行sql，返回最后生成的pk值
    """
        assert not (
            return_id and len(self.query.objs) != 1 and
            not self.connection.features.can_return_ids_from_bulk_insert
        )
        self.return_id = return_id

        # 字段是怎么变成sql语句的，最后就是在这个as_sql()中
        with self.connection.cursor() as cursor:
            for sql, params in self.as_sql():
                # 步骤4 执行SQL
                cursor.execute(sql, params)

            if not (return_id and cursor):
                return
            if self.connection.features.can_return_ids_from_bulk_insert and len(self.query.objs) > 1:
                return self.connection.ops.fetch_returned_insert_ids(cursor)
            if self.connection.features.can_return_id_from_insert:
                assert len(self.query.objs) == 1
                return self.connection.ops.fetch_returned_insert_id(cursor)
            return self.connection.ops.last_insert_id(
                cursor, self.query.get_meta().db_table, self.query.get_meta().pk.column
            )

def as_sql(self):
    """
    这个函数主要就是执行步骤3准备数据库数据，生成SQL和值
    """
    qn = self.connection.ops.quote_name 
    # 根据不同的数据库做不同的处理比如mysql:
    # >>> name = "green"
    # >>> qn(name)
    #>>> "`green`"

    opts = self.query.get_meta()
    result = ['INSERT INTO %s' % qn(opts.db_table)]

    has_fields = bool(self.query.fields)
    fields = self.query.fields if has_fields else [opts.pk]
    # 加入字段名称
    result.append('(%s)' % ', '.join(qn(f.column) for f in fields))

    if has_fields:
        # self.pre_save_val(field, obj) 实际调用的是field.pre_save(obj, add=True)
        # 将转化交给field自己去处理
        # prepare_value() 对需要特殊转化的字段进行处理如DatetimeField
        value_rows = [
            [self.prepare_value(field, self.pre_save_val(field, obj)) for field in fields]
            for obj in self.query.objs
        ]
    else:
        # An empty object.
        value_rows = [[self.connection.ops.pk_default_value()] for _ in self.query.objs]
        fields = [None]

    # 数据库能否支持批量插入
    can_bulk = (not self.return_id and self.connection.features.has_bulk_insert)

    # 生成字段和值对应的sql
    placeholder_rows, param_rows = self.assemble_as_sql(fields, value_rows)

    # 下面就是根据不同的数据库能接受不同形式的SQL的处理，最终返回拼装好的SQL和值  
    if self.return_id and self.connection.features.can_return_id_from_insert:
        if self.connection.features.can_return_ids_from_bulk_insert:
            result.append(self.connection.ops.bulk_insert_sql(fields, placeholder_rows))
            params = param_rows
        else:
            result.append("VALUES (%s)" % ", ".join(placeholder_rows[0]))
            params = [param_rows[0]]
        col = "%s.%s" % (qn(opts.db_table), qn(opts.pk.column))
        r_fmt, r_params = self.connection.ops.return_insert_id()
        if r_fmt:
            result.append(r_fmt % col)
            params += [r_params]
        return [(" ".join(result), tuple(chain.from_iterable(params)))]

    if can_bulk:
        result.append(self.connection.ops.bulk_insert_sql(fields, placeholder_rows))
        return [(" ".join(result), tuple(p for ps in param_rows for p in ps))]
    else:
        return [
            (" ".join(result + ["VALUES (%s)" % ", ".join(p)]), vals)
            for p, vals in zip(placeholder_rows, param_rows)
        ]