آموزش Django Signals از صفر تا صد؛ راهنمای کامل سیگنال‌ها در جنگو


آموزش Django Signals از صفر تا صد؛ راهنمای کامل سیگنال‌ها در جنگو #

django-signals-tutorial

اگر با فریم‌ورک Django کار می‌کنید، احتمالاً موقع توسعه پروژه‌های واقعی با موقعیت‌هایی روبه‌رو شده‌اید که می‌خواهید بعد از ذخیره یک کاربر، ساخت یک سفارش یا حذف یک رکورد، عملیات دیگری نیز به‌صورت خودکار انجام شود.

برای مثال، فرض کنید در حال ساخت یک فروشگاه اینترنتی با جنگو هستید. هر بار که کاربر جدیدی ثبت‌نام می‌کند، می‌خواهید به‌صورت خودکار یک پروفایل برای او ایجاد شود. آیا باید این منطق را در تمام Viewها و APIهای ثبت‌نام تکرار کنید؟

اینجاست که Django Signals می‌توانند به شما کمک کنند.

در این آموزش، یاد می‌گیرید سیگنال در جنگو چیست، چه کاربردی دارد، چگونه از post_save و pre_save استفاده کنید، چطور یک Signal اختصاصی بسازید و چه اشتباهاتی را هنگام استفاده از سیگنال‌ها باید کنار بگذارید.

Django Signals چیست؟ #

Django Signals مکانیزمی در جنگو برای اطلاع‌رسانی درباره رخدادهایی است که در بخش‌های مختلف برنامه اتفاق می‌افتند. با استفاده از این قابلیت، می‌توانید یک تابع را به رخدادی مشخص متصل کنید تا هنگام وقوع آن رخداد اجرا شود.

به این ترتیب، یک بخش از برنامه می‌تواند بدون فراخوانی مستقیم تابع بخش دیگر، از وقوع یک رویداد مطلع شود.

برای درک بهتر، یک فروشگاه اینترنتی را تصور کنید:

  • کاربر جدیدی در سایت ثبت‌نام می‌کند.
  • جنگو یک رکورد جدید در دیتابیس ذخیره می‌کند.
  • یک Signal مربوط به ذخیره مدل اجرا می‌شود.
  • تابعی که به این Signal متصل است، پروفایل کاربر را ایجاد می‌کند.

این فرایند می‌تواند بدون نوشتن منطق ایجاد پروفایل در تک‌تک Viewها انجام شود.

البته سیگنال‌ها همیشه بهترین راه‌حل نیستند. اگر دو بخش از کد متعلق به یک پروژه هستند و مستقیماً به هم وابستگی دارند، فراخوانی مستقیم یک تابع معمولاً ساده‌تر و قابل‌فهم‌تر است.

اجزای اصلی Django Signals #

برای کار با سیگنال‌ها باید با سه مفهوم اصلی آشنا شوید.

۱. Signal #

سیگنال نشان می‌دهد که یک رخداد اتفاق افتاده است؛ برای مثال، ذخیره‌شدن یک مدل یا حذف یک رکورد.

۲. Sender #

فرستنده، بخشی است که رخداد به آن مربوط می‌شود. در سیگنال‌های مدل، معمولاً خود کلاس مدل فرستنده است.

برای مثال، اگر بخواهیم فقط هنگام ذخیره مدل Article تابعی اجرا شود، می‌توانیم Article را به‌عنوان Sender تعیین کنیم.

۳. Receiver #

گیرنده تابعی است که هنگام ارسال سیگنال اجرا می‌شود. این تابع می‌تواند اطلاعات مربوط به رخداد را دریافت کند و عملیات موردنیاز را انجام دهد.

به‌طور خلاصه، جریان کار سیگنال در جنگو چنین است:

رخداد اتفاق می‌افتد ← سیگنال ارسال می‌شود ← تابع Receiver اجرا می‌شود.

انواع مهم Django Signals #

جنگو سیگنال‌های مختلفی دارد که هرکدام برای رخداد مشخصی استفاده می‌شوند. در جدول زیر، مهم‌ترین سیگنال‌ها را می‌بینید.

نام سیگنال کاربرد
pre_save پیش از اجرای عملیات ذخیره مدل
post_save پس از اجرای عملیات ذخیره مدل
pre_delete پیش از حذف مدل
post_delete پس از حذف مدل
pre_init پیش از پایان مقداردهی اولیه نمونه مدل
post_init پس از پایان مقداردهی اولیه نمونه مدل
m2m_changed برای تغییرات رابطه Many-to-Many
post_migrate پس از اجرای عملیات مهاجرت دیتابیس

دو سیگنال pre_save و post_save از پرکاربردترین گزینه‌ها برای شروع یادگیری هستند.

تفاوت pre_save و post_save در جنگو چیست؟ #

تفاوت این دو سیگنال در زمان اجرا است.

  • pre_save: هنگام شروع فرایند ذخیره مدل اجرا می‌شود؛ یعنی قبل از انجام عملیات ذخیره مربوط به save().
  • post_save: پس از پایان اجرای متد save() اجرا می‌شود.

برای مثال، اگر بخواهید پیش از ذخیره یک مدل مقدار مشخصی را تنظیم کنید، می‌توانید pre_save را بررسی کنید. اگر بخواهید بعد از ایجاد یک رکورد، عملیات دیگری انجام دهید، post_save گزینه مناسبی است.

نکته مهم: اجرای post_save به این معنی نیست که تراکنش دیتابیس حتماً Commit شده است. اگر قرار است پس از ثبت قطعی تراکنش ایمیل ارسال کنید یا کاری خارج از دیتابیس انجام دهید، استفاده از transaction.on_commit() را هم در نظر بگیرید.

آموزش استفاده از post_save در Django #

در این بخش یک مثال عملی را بررسی می‌کنیم.

فرض کنید در پروژه خود مدلی با نام Article دارید و می‌خواهید هنگام ذخیره هر مقاله، تابعی اجرا شود.

ابتدا در فایل signals.py اپلیکیشن خود کد زیر را بنویسید:

python
from django.db.models.signals import post_save
from django.dispatch import receiver

from .models import Article


@receiver(post_save, sender=Article)
def article_saved(sender, instance, created, **kwargs):
    if created:
        print(f"مقاله جدید ایجاد شد: {instance.title}")
    else:
        print(f"مقاله به‌روزرسانی شد: {instance.title}")

در این مثال، هر بار که متد save() مدل Article اجرا شود، تابع article_saved فراخوانی می‌شود.

پارامترهای این تابع عبارت‌اند از:

  • sender: کلاس مدلی که سیگنال را ارسال کرده است.
  • instance: نمونه‌ای از مدلی که ذخیره شده است.
  • created: مشخص می‌کند آیا رکورد جدید ایجاد شده یا رکورد موجود به‌روزرسانی شده است.
  • kwargs: سایر آرگومان‌های ارسال‌شده همراه سیگنال.

شرط if created کمک می‌کند عملیات مربوط به ایجاد مقاله را از عملیات مربوط به ویرایش مقاله جدا کنید.

چگونه فایل signals.py را در جنگو فعال کنیم؟ #

صرفاً ساختن فایل signals.py کافی نیست. باید مطمئن شوید کدهای ثبت Receiver هنگام آماده‌شدن اپلیکیشن اجرا می‌شوند.

فرض کنید نام اپلیکیشن شما articles است. فایل articles/apps.py را به این شکل تنظیم کنید:

python
from django.apps import AppConfig


class ArticlesConfig(AppConfig):
    default_auto_field = "django.db.models.BigAutoField"
    name = "articles"

    def ready(self):
        from . import signals

سپس مطمئن شوید اپلیکیشن در INSTALLED_APPS در فایل settings.py ثبت شده است:

python
INSTALLED_APPS = [
    # سایر اپلیکیشن‌ها
    "articles.apps.ArticlesConfig",
]

اکنون Receiver هنگام آماده‌شدن اپلیکیشن ثبت می‌شود.

نکته: متد ready() ممکن است در بعضی شرایط، مانند اجرای تست‌ها، بیش از یک بار اجرا شود. برای همین باید از ثبت تکراری Receiverها جلوگیری کنید؛ استفاده درست از dispatch_uid در موارد لازم کمک‌کننده است.

مثال کاربردی: ساخت خودکار پروفایل کاربر با Django Signals #

حالا یک مثال واقعی‌تر را بررسی می‌کنیم. فرض کنید اپلیکیشن accounts را در یک پروژه جنگو توسعه می‌دهید و می‌خواهید پس از ایجاد هر کاربر، یک پروفایل برای او ساخته شود.

مرحله اول: ساخت مدل Profile #

در فایل accounts/models.py کد زیر را قرار دهید:

python
from django.conf import settings
from django.db import models


class Profile(models.Model):
    user = models.OneToOneField(
        settings.AUTH_USER_MODEL,
        on_delete=models.CASCADE,
        related_name="profile",
    )
    bio = models.TextField(blank=True)

    def __str__(self):
        return f"Profile of {self.user}"

در اینجا از settings.AUTH_USER_MODEL استفاده کرده‌ایم تا رابطه به مدل کاربر تنظیم‌شده در پروژه متصل شود؛ بنابراین کد به مدل پیش‌فرض کاربر وابسته نیست.

رابطه OneToOneField تضمین می‌کند که هر کاربر حداکثر یک پروفایل مرتبط داشته باشد.

مرحله دوم: ساخت فایل signals.py #

در مسیر accounts/signals.py کد زیر را قرار دهید:

python
from django.conf import settings
from django.db.models.signals import post_save
from django.dispatch import receiver

from .models import Profile


@receiver(
    post_save,
    sender=settings.AUTH_USER_MODEL,
    dispatch_uid="accounts.create_user_profile",
)
def create_user_profile(sender, instance, created, raw=False, **kwargs):
    if raw or not created:
        return

    Profile.objects.get_or_create(user=instance)

بیایید بخش‌های مهم این کد را بررسی کنیم.

شرط created: پروفایل فقط در زمان ایجاد کاربر بررسی می‌شود، نه هر بار که اطلاعات کاربر تغییر کند.

شرط raw: هنگام بارگذاری بعضی Fixtureها، جنگو ممکن است سیگنال را با raw=True ارسال کند. در این وضعیت، بهتر است به وضعیت سایر رکوردهای دیتابیس وابسته نشویم.

متد get_or_create(): ابتدا بررسی می‌کند آیا پروفایل مرتبط وجود دارد یا خیر و فقط در صورت نبودن آن، رکورد جدید می‌سازد.

پارامتر dispatch_uid: شناسه‌ای برای شناسایی این Receiver در زمان اتصال به سیگنال است و از اتصال تکراری همان شناسه جلوگیری می‌کند.

مرحله سوم: ثبت سیگنال در AppConfig #

فایل accounts/apps.py را به شکل زیر تنظیم کنید:

python
from django.apps import AppConfig


class AccountsConfig(AppConfig):
    default_auto_field = "django.db.models.BigAutoField"
    name = "accounts"

    def ready(self):
        from . import signals

سپس در settings.py بنویسید:

python
INSTALLED_APPS = [
    # سایر اپلیکیشن‌ها
    "accounts.apps.AccountsConfig",
]

اکنون در صورت فعال بودن این اپلیکیشن و ایجاد کاربر از مسیری که سیگنال‌های مدل را اجرا می‌کند، تابع create_user_profile فراخوانی خواهد شد.

مرحله چهارم: اجرای Migration #

اگر مدل Profile را به‌تازگی ساخته‌اید، دستورات زیر را اجرا کنید:

bash
python manage.py makemigrations accounts
python manage.py migrate

در این مثال، هر بار یک کاربر جدید ایجاد شود، Receiver تلاش می‌کند پروفایل مرتبط با او را نیز ایجاد کند.

توجه کنید که اگر پروژه شما از قبل در View، Serializer یا سیگنال دیگری پروفایل کاربر را ایجاد می‌کند، ابتدا آن منطق را بررسی کنید تا منطق‌های تکراری و ناسازگار نداشته باشید.

آیا Django Signals روی تمام تغییرات دیتابیس اجرا می‌شود؟ #

خیر؛ این یکی از مهم‌ترین نکاتی است که هنگام استفاده از سیگنال‌ها باید بدانید.

سیگنال‌های مدل مانند post_save معمولاً از مسیر متد save() مدل ارسال می‌شوند. بنابراین نباید فرض کنید هر تغییری در دیتابیس الزاماً یک post_save ایجاد می‌کند.

برای مثال:

python
Article.objects.filter(
    published=False
).update(published=True)

این کد از QuerySet.update() استفاده می‌کند و متد save() را برای تک‌تک نمونه‌های مدل فراخوانی نمی‌کند؛ بنابراین سیگنال‌های معمول pre_save و post_save برای این به‌روزرسانی اجرا نمی‌شوند.

همچنین عملیات‌هایی مانند bulk_create() مسیر معمول save() را برای هر نمونه اجرا نمی‌کنند و سیگنال‌های استاندارد ذخیره مدل را به شکل معمول ارسال نمی‌کنند.

اگر منطق برنامه شما به اجرای حتمی یک عملیات جانبی وابسته است، این تفاوت می‌تواند باعث ایجاد خطاهای پنهان شود.

اشتباهات رایج در استفاده از Django Signals #

۱. استفاده از سیگنال برای تمام منطق‌های برنامه #

سیگنال‌ها ابزار مناسبی برای جداکردن بعضی عملیات جانبی هستند، اما استفاده بیش‌ازحد از آن‌ها می‌تواند فهمیدن مسیر اجرای برنامه را دشوار کند.

اگر دو تابع متعلق به یک بخش مشخص از پروژه هستند، یک فراخوانی مستقیم معمولاً ساده‌تر است.

۲. ایجاد حلقه بی‌نهایت در post_save #

فرض کنید در داخل یک Receiver، مجدداً متد save() را روی همان نمونه فراخوانی کنید. این کار ممکن است دوباره همان سیگنال را اجرا کند و به فراخوانی‌های تکراری منجر شود.

قبل از تغییر یک مدل از داخل Receiver، مسیر اجرای کد را بررسی کنید. تا حد ممکن از تغییرات غیرضروری مدل در سیگنال خودداری کنید.

۳. فراموش‌کردن ثبت سیگنال #

اگر فایل signals.py ساخته شده باشد اما جایی Import نشود، Receiver ثبت نمی‌شود و تابع شما اجرا نخواهد شد.

ثبت Receiverها در متد ready() کلاس AppConfig یکی از روش‌های رایج برای حل این مسئله است.

۴. وابستگی به رفتار سیگنال در عملیات Bulk #

همان‌طور که دیدیم، QuerySet.update() و bulk_create() مانند فراخوانی معمول save() رفتار نمی‌کنند.

اگر عملیات شما باید در تمام مسیرهای نوشتن داده اجرا شود، بهتر است یک لایه سرویس مشخص طراحی کنید یا منطق را در مسیری قرار دهید که تمام عملیات مربوطه از آن عبور کنند.

۵. انجام عملیات طولانی داخل Receiver #

ارسال ایمیل، تماس با API خارجی یا اجرای کارهای زمان‌بر داخل Receiver می‌تواند باعث افزایش زمان درخواست شود.

برای عملیات پس از Commit شدن تراکنش می‌توانید از transaction.on_commit() استفاده کنید. برای کارهای طولانی نیز بسته به نیاز پروژه، استفاده از صف وظایف مانند Celery را بررسی کنید.

تفاوت Django Signals با Override کردن متد save() #

گاهی برای اجرای کد قبل یا بعد از ذخیره مدل، لازم نیست سراغ سیگنال بروید.

برای مثال، می‌توانید متد save() یک مدل را Override کنید:

python
class Article(models.Model):
    title = models.CharField(max_length=200)

    def save(self, *args, **kwargs):
        # منطق موردنیاز پیش از ذخیره
        super().save(*args, **kwargs)
        # منطق موردنیاز پس از ذخیره

این مثال صرفاً یک الگوی ساده است؛ منطق واقعی باید متناسب با نیاز پروژه پیاده‌سازی شود.

تفاوت اصلی این است که Override کردن save()، رفتار خود مدل را تغییر می‌دهد؛ اما Signal اجازه می‌دهد یک تابع جداگانه به رخداد ذخیره متصل شود.

معیار Django Signals Override کردن save()
محل قرارگیری منطق معمولاً در تابع Receiver جداگانه داخل کلاس مدل
خوانایی جریان اجرا ممکن است دشوارتر شود معمولاً مستقیم‌تر است
مناسب برای عملیات جانبی و اتصال بخش‌های مستقل رفتار مرتبط با ذخیره همان مدل
اجرا در QuerySet.update() خیر، به شکل معمول خیر، به شکل معمول

نکته این است که هیچ‌کدام به‌صورت جادویی تمام عملیات دیتابیس را پوشش نمی‌دهند. باید بدانید کد شما دقیقاً از کدام مسیر اجرا می‌شود.

چه زمانی از Django Signals استفاده کنیم؟ #

پیش از اضافه‌کردن سیگنال به پروژه، مشخص کنید آیا واقعاً به یک سازوکار رویدادمحور نیاز دارید یا یک فراخوانی مستقیم کافی است.

موارد زیر می‌توانند کاربردهای مناسبی باشند:

  • ایجاد یک رکورد جانبی پس از ایجاد رکورد اصلی
  • ثبت رخدادهای مشخص برای بررسی و گزارش‌گیری
  • اتصال عملیات جانبی به رخدادهای یک اپلیکیشن مستقل
  • اجرای بعضی وظایف پس از پایان موفق تراکنش دیتابیس

در مقابل، برای منطق اصلی کسب‌وکار که باید ترتیب اجرا و نتیجه آن کاملاً روشن باشد، فراخوانی مستقیم تابع یا استفاده از یک لایه سرویس اغلب انتخاب قابل‌نگهداری‌تری است.

سؤالات متداول درباره Django Signals #

Django Signals چیست؟ #

Django Signals سیستمی برای اطلاع‌رسانی درباره رخدادهای مختلف در جنگو است. با استفاده از آن می‌توانید توابعی را به رخدادهایی مانند ذخیره یا حذف مدل متصل کنید.

تفاوت post_save و pre_save چیست؟ #

pre_save پیش از اجرای عملیات ذخیره مدل اجرا می‌شود؛ در حالی که post_save پس از پایان اجرای متد save() فراخوانی می‌شود.

فایل signals.py را کجا قرار دهیم؟ #

معمولاً فایل signals.py را داخل پوشه اپلیکیشن مربوطه قرار می‌دهند؛ برای مثال، accounts/signals.py. سپس Receiverها را در متد ready() اپلیکیشن ثبت می‌کنند.

آیا post_save بعد از هر تغییر دیتابیس اجرا می‌شود؟ #

خیر. برای مثال، QuerySet.update() متد save() را برای هر نمونه اجرا نمی‌کند؛ بنابراین نباید انتظار داشت سیگنال‌های استاندارد ذخیره مدل اجرا شوند.

آیا Django Signals جایگزین View یا Serializer هستند؟ #

خیر. سیگنال‌ها برای واکنش به رخدادها طراحی شده‌اند و جایگزین ساختارهای دیگر برنامه نیستند. بهتر است هر ابزار را متناسب با وظیفه‌اش به کار ببرید.

آیا استفاده از Django Signals توصیه می‌شود؟ #

بله، در موقعیت‌های مناسب. بااین‌حال، استفاده بیش‌ازحد از آن‌ها می‌تواند اشکال‌زدایی و نگهداری پروژه را دشوارتر کند. انتخاب بین Signal، تابع مستقیم و لایه سرویس باید بر اساس ساختار پروژه انجام شود.

جمع‌بندی #

در این آموزش یاد گرفتیم که Django Signals چگونه کار می‌کنند، چه تفاوتی میان pre_save و post_save وجود دارد و چطور می‌توانیم پس از ایجاد کاربر، یک پروفایل مرتبط بسازیم.

همچنین بررسی کردیم که سیگنال‌ها در همه مسیرهای تغییر دیتابیس اجرا نمی‌شوند و استفاده بیش‌ازحد از آن‌ها می‌تواند نگهداری پروژه را دشوار کند.

اگر تازه یادگیری جنگو را شروع کرده‌اید، پیشنهاد می‌کنیم ابتدا با post_save و pre_save کار کنید، سپس نحوه ثبت Receiverها و محدودیت‌های سیگنال‌ها را در پروژه‌های واقعی بررسی کنید.

منابع برای مطالعه بیشتر #

این پست چطور بود؟

پست‌های مرتبط