扩展模型

以下是在核心模型中添加新字段时需要考虑的任务列表。

1. 在模型类中添加字段

在模型中添加字段，并注意处理以下条件。

当添加GenericForeignKey字段时，还要在Meta下为其两个具体字段添加索引。例如：

class Meta:
    indexes = (
        models.Index(fields=('object_type', 'object_id')),
    )

2. 生成并运行数据库迁移

Django迁移用于表示对数据库模式的更改。在大多数情况下，Django可以自动生成这些迁移，但非常复杂的更改可能需要手动干预。始终记住在生成新迁移时指定一个简短但描述性的名称。

./manage.py makemigrations <app> -n <name> --no-header
./manage.py migrate

在可能的情况下，尝试将相关更改合并到单个迁移中。例如，如果要在应用程序内的不同模型中添加三个新字段，可以在单个迁移中表示这些更改。可以通过合并它们的operations列表来将新生成的迁移与现有迁移合并。

不要更改现有迁移

迁移只能在发布版本内合并。一旦发布了新版本，就不能更改其迁移（除非是为了纠正错误）。

3. 在`clean()`中添加验证逻辑

如果新字段引入了额外的验证要求（超出字段本身包含的内容），请在模型的clean()方法中实现它们。在适当的时候，记得在你的自定义验证之前或之后使用super()调用模型的原始方法：

class Foo(models.Model):

    def clean(self):
        super().clean()

        # 自定义验证放在这里
        if self.bar is None:
            raise ValidationError()

4. 更新相关的查询集

如果要添加关系字段（例如ForeignKey）并且打算在检索对象列表时包括数据，请确保适当使用prefetch_related()包含字段。这将优化视图并避免不必要的数据库查询。

5. 更新API序列化器

扩展模型的API序列化器，在<app>.api.serializers中包含新字段。在大多数情况下，不需要扩展嵌套序列化器，因为它产生模型的最小表示。

6. 添加字段到表单

根据需要扩展任何表单以包括新字段。这些表单位于每个应用程序的forms/目录下。常见的表单包括：

创建/编辑 - 操作单个对象
批量编辑 - 一次对多个对象执行更改
CSV导入 - 用于以CSV格式批量导入对象的表单
筛选器 - 显示用于筛选对象列表的选项（UI和API都包括）

7. 扩展对象过滤器集

如果新字段应该可筛选，请将其添加到模型的FilterSet中。如果字段应该可搜索，请记住在FilterSet的search()方法中查询它。

8. 添加列到对象表格

如果新字段将包含在对象列表视图中，请向模型的表格添加列。对于简单字段，将字段名称添加到Meta.fields将足够。更复杂的字段可能需要声明自定义列。还将字段名称添加到default_columns，如果该列应默认存在于表格中。

9. 更新SearchIndex

在适用的情况下，将新字段添加到模型的SearchIndex中，以包含在全局搜索中。

10. 更新UI模板

编辑对象的视图模板以显示新字段。还可能存在需要更新的自定义添加/编辑表单模板。

11. 创建/扩展测试用例

创建或扩展相关的测试用例，以验证新字段和任何相关的验证逻辑是否按预期工作。对于关系字段，这尤其重要。NetBox包含各种测试套件，包括：

API序列化器/视图测试
筛选测试
表单测试
模型测试
视图测试

要保持谨慎，确保适当地适应或扩展所有相关的测试套件，以测试任何新功能。

12. 更新模型文档

每个模型都有一个专门的文档页面，位于models/<app>/<model>.md。更新此文件以包括有关新字段的任何相关信息。