Django模型上的审计字段更改

一个用于审计数据库模型字段更改的Django应用程序。

安装

pip install django-field-audit

文档

Django设置

要启用该应用程序，将其添加到您的Django INSTALLED_APPS 配置并运行迁移。设置示例

INSTALLED_APPS = [
    # ...
    "field_audit",
]

"审计链"（见下表中的 FIELD_AUDIT_AUDITORS）默认配置了默认审计器。如果需要为认证的Django请求进行 change_context 审计，请将应用程序中间件添加到您的Django MIDDLEWARE 配置中。例如

MIDDLEWARE = [
    # ...
    "field_audit.middleware.FieldAuditMiddleware",
]

可以将审计链更新为使用自定义审计器（field_audit.auditors.BaseAuditor 的子类）。如果不希望进行 change_context 审计，则可以清除审计链以避免额外的处理

FIELD_AUDIT_AUDITORS = []

自定义设置详情

模型审计

要开始审计Django模型，导入 field_audit.audit_fields 装饰器并装饰模型，指定哪些字段应审计更改。示例代码

# flight/models.py

from django.db import models
from field_audit import audit_fields


@audit_fields("tail_number", "make_model", "operated_by")
class Aircraft(models.Model):
    id = AutoField(primary_key=True)
    tail_number = models.CharField(max_length=32, unique=True)
    make_model = models.CharField(max_length=64)
    operated_by = models.CharField(max_length=64)

已审计的DB写入操作

默认情况下，审计Model和QuerySet方法，除了四个“特殊”的QuerySet方法外

审计特殊QuerySet写入

可以启用对上述表中标记为否的四个“特殊”QuerySet方法（执行数据库写入）的审计。这需要三个额外的使用细节

警告 启用这些QuerySet方法的审计可能会对性能产生重大影响，尤其是在大型数据集中，因为审计事件是在内存中构建并批量写入数据库的。

1. 通过调用具有@audit_fields(..., audit_special_queryset_writes=True)的审计装饰器来启用此功能。
2. 配置模型类，使其默认管理器是field_audit.models.AuditingManager的实例。
3. 所有对四个“特殊”QuerySet写入方法的调用都需要一个额外的audit_action关键字参数，其值可以是以下之一
   • field_audit.models.AuditAction.AUDIT
   • field_audit.models.AuditAction.IGNORE

重要注意事项

• 在模型类评估时，如果不将默认管理器设置为AuditingManager的实例（如上所述步骤2），则指定audit_special_queryset_writes=True（如上所述步骤1）将引发异常。
• 目前，QuerySet.delete()、QuerySet.update()和QuerySet.bulk_create()的“特殊”写入方法在调用时带有audit_action=AuditAction.AUDIT可以执行变更审计。QuerySet.bulk_update()目前尚未实现，如果使用该操作将引发NotImplementedError。实现此剩余方法仍然是未来的任务，请参阅下方的TODO。所有四种方法都支持audit_action=AuditAction.IGNORE的使用。
• 所有审计方法都使用事务来确保只有在成功创建和保存审计事件后，对已审计模型的更改才会提交到数据库。

现有记录的模型的自举事件

在审计已启用于具有现有数据的模型的情况下，为现有模型记录生成“自举”审计事件可能很有价值，以确保每个当前存在的模型实例至少有一个审计事件记录。为此操作提供了一个迁移实用程序。示例代码

# flight/migrations/0002_bootstrap_aircarft_auditing.py

from django.db import migrations, models
from field_audit.utils import run_bootstrap

from flight.models import Aircraft


class Migration(migrations.Migration):

    dependencies = [
        ('flight', '0001_initial'),
    ]

    operations = [
        run_bootstrap(Aircraft, ["tail_number", "make_model", "operated_by"])
    ]

通过管理命令自举事件

如果在迁移期间不适用自举，则有一个管理命令可以执行相同的操作。管理命令不接受自举记录的任意字段名，并使用模型上配置的现有audit_fields(...)装饰器上的字段。示例（类似于上述迁移操作）

manage.py bootstrap_field_audit_events init Aircraft

此外，如果需要迁移后的自举“补充”操作，管理命令也可以执行此操作。补充操作为任何没有“创建”或“自举”AuditEvent记录的现有模型记录创建自举审计事件。请注意，管理命令是目前唯一可以“补充”自举审计事件的方法。示例

manage.py bootstrap_field_audit_events top-up Aircraft

与SQLite一起使用

此应用程序使用Django的JSONField，这意味着如果您打算使用SQLite数据库，则需要SQLite JSON1扩展。如果您的系统Python sqlite3库没有附带此扩展启用，请参阅这篇文章以获取有关启用它的详细信息。

贡献

预期所有功能和错误贡献都应由测试覆盖。

开发人员设置

创建/激活python虚拟环境并安装所需的依赖项。

cd django-field-audit
mkvirtualenv django-field-audit  # or however you choose to setup your environment
pip install django pynose flake8 coverage

运行测试

注意：默认情况下，本地测试使用内存中的 SQLite 数据库。请确保您的本地 Python 的 sqlite3 库已启用 JSON1 扩展（见 使用 SQLite）。

• 测试

  nosetests
  

• 风格检查

  flake8 --config=setup.cfg
  

• 覆盖率

  coverage run -m nose
  coverage report -m
  

添加迁移

示例 manage.py 可用于创建新的迁移。

python example/manage.py makemigrations field_audit

上传到 PyPI

首先在 field_audit/__init__.py 文件中提高包版本。然后在 CHANGELOG.md 文件中创建变更日志条目。在合并这些更改后，您应该使用新版本标记主分支。然后，打包并上传生成的文件到 PyPI。

pip install -r pkg-requires.txt

python setup.py sdist bdist_wheel
twine upload dist/*

待办事项

• 实现剩余的“特殊”QuerySet 写操作审计
  • bulk_update()
• 使用 github.io 编写完整库文档。
• 切换到 pytest 以支持 Python 3.10。

待办事项列表

• 优化 instance.save(save_fields=[...]) [也许]。
• 支持在相同模型的不同时间添加新的审计字段（而不是引发 AlreadyAudited）[也许]。