django

Django 开发模式

适用于 Django 项目的约定。关于应用架构和模块组织，请参阅 python 技能——这些模式适用于所有 Python 项目。

Celery 任务模式

任务函数以 _task 结尾，并调用不带后缀的服务函数。 这样可以保持导入简洁——无需使用别名即可执行 from myapp.services import execute_report。

from myapp.services import execute_report, fail_report

@celery_app.task(bind=True)
def execute_report_task(self, report_id: int) -> None:
    """Execute report generation asynchronously."""
    try:
        execute_report(report_id)
    except Exception as exc:
        if self.request.retries >= self.max_retries:
            fail_report(report_id=report_id, error_message=str(exc))
        raise

从入口点（api.py、admin.py）调度任务，而不是从服务函数中调度。这样可以避免循环导入，并让任务调度在调用处清晰可见。将业务逻辑放在服务函数中，以便所有入口点都能复用；任务只调用服务函数。

调度辅助函数

如果多个入口点需要创建待处理记录并调度任务，请在 tasks.py 中提取一个 schedule_* 函数。这是“tasks.py 中不写逻辑”这一规则的唯一例外：该函数的唯一职责是将记录创建与任务调度结合起来。

# tasks.py
def schedule_refresh_all(user: User) -> RefreshOperation:
    """Create the pending record and schedule the task."""
    operation = create_pending_refresh_operation(user)
    refresh_all_task.delay(operation.id)
    return operation

入口点调用 schedule_refresh_all()，而不是重复编写先创建、再调用 delay 的模式。

跨应用信号

当一个应用需要响应另一个应用中的事件时，请使用自定义 Django 信号，而不是直接导入或模型信号（post_save 等）。

• 在发送信号的应用的 signals.py 中定义信号。
• 从服务函数中发送信号，而不是从 Model.save() 中发送。这样可以控制信号何时触发以及携带哪些数据。
• 在接收信号的应用的 signals.py 中定义接收器，并通过 AppConfig.ready() 注册。

# emitting app: accounts/signals.py
from django.dispatch import Signal
websites_updated = Signal()

# emitting app: accounts/services.py
websites_updated.send(sender=refresh_all, user=user, added=added)

# listening app: filtering/signals.py
from django.dispatch import receiver
from accounts.signals import websites_updated

@receiver(websites_updated)
def on_websites_updated(sender, user, added, **kwargs):
    ...

# listening app: filtering/apps.py
class FilteringConfig(AppConfig):
    def ready(self) -> None:
        import_module("filtering.signals")

依赖关系保持单向：接收信号的应用可以从发送信号的应用导入，反之则不行。

组件参考

如需了解特定 Django 组件的详细模式，请按需加载以下参考资料：

• 模型规范 — 基类、EnumField、SchemaField、Meta
• 迁移 — 架构和数据迁移顺序、 历史模型、可逆性和迁移测试
• 视图 — Django 视图函数、URL 配置
• 管理后台 — list_display、search、filters、@admin.display
• 服务提供者模式 — 通过 registry + factory 集成外部服务

验证

编写 Django 代码后，请检查参考资料中的规则，这些规则最容易被忽略：

• 管理后台操作通过服务函数执行变更
• 不为 admin.py 编写测试——值得测试的逻辑应先移至 services.py
• 替换持久化字段时，须包含保留现有值的数据迁移；如果数据丢失对用户可见，还须包含迁移测试