Django Feature 是一个按项目既有风格为 Django/DRF 构建新功能的技能。其出发点是:客户项目评审中最常见的问题不是缺陷,而是“我们这里不这么做”,因此应先复制项目风格,而不是自创写法。
用途
用于在已有 Django/DRF 代码库中新增一个完整功能切片,典型包括模型、迁移、序列化器、视图、URL、权限、admin 和测试。也适用于新增类似 CRUD 资源的场景。
主要能力与使用方式
第一步是学习项目风格,不应跳过。先阅读仓库地图中“我们这里怎么做 X”部分(如存在),再打开与目标最接近的现有功能,记录其视图类型(ModelViewSet、GenericAPIView、APIView 或函数视图,Router 还是显式 path)、逻辑所在位置(services.py、selectors.py、模型方法或序列化器)、权限类与 get_queryset 按用户/组织/租户收窄的方式、序列化器是否区分读写、字段是否显式列出、分页与过滤(django-filter)及排序默认值、模型约定(基类如 TimeStampedModel、UUID 主键、related_name 风格、Meta.ordering、str)、admin 注册方式、测试位置与工具(pytest-django 或 TestCase、factory_boy 工厂、conftest.py 中的 API 客户端 fixture)、URL 命名(kebab 或 snake case、basename)。随后用 4 至 6 条要点向开发者说明将参照哪个现有功能、复制哪些模式;若新旧两种模式并存,应询问当前采用哪一种。
第二步是规划文件清单,写代码前先列出所有将创建或修改的文件,例如 models.py 增加模型、生成迁移、services.py 增加服务函数、serializers.py 增加序列化器、views.py 增加视图集、urls.py 注册路由、admin.py 注册模型、tests 下新增测试文件。如果模型或端点与其他仓库共享,应停止直接修改,转而通过 safe-change 或 cross-repo-change 流程处理。
第三步是逐切片、测试先行地构建,每个切片以测试通过结束:模型与迁移阶段执行 makemigrations,并对照 django-migrations 规则检查迁移文件和 SQL(sqlmigrate),显式声明 on_delete、related_name,为将用于过滤或排序的字段添加索引;写路径先写失败的 API 测试(成功路径、权限拒绝、校验错误),再实现序列化器、服务和视图直至通过;读路径先写列表与详情测试,包括“用户不能看到其他组织的数据行”,再实现视图 get_queryset 的范围收窄,并为列表端点添加查询数守卫(django_assert_max_num_queries),当场用 select_related/prefetch_related 修复 N+1;若在范围内,更新与删除按同样方式实现;最后处理 admin、URL 和文档(项目使用 drf-spectacular 时添加 OpenAPI 注解)。测试遵循 test-writer 约定。
第四步是交付前检查:执行 makemigrations --check --dry-run 确认无遗漏迁移、manage.py check、项目配置的 linter/formatter(ruff、black、isort、flake8、mypy 等)、应用测试套件,若整体测试较快再跑全量;随后建议进入 code-quality 与 pr-description 环节。
限制与规则
接受输入的序列化器不得使用 fields = "all",应显式列出字段,并将服务端设置的字段标记为 read_only_fields;视图中每个查询集都必须按请求用户可见范围收窄,API 视图中不得出现未收窄的 Model.objects.all();每个新视图显式声明 permission_classes,即使与默认一致;视图中不放业务逻辑,按项目模式放置,若没有模式则放入 services.py 函数;涉及外部世界的副作用(邮件、任务、webhook)应放入 transaction.on_commit。