接收器函数¶

首先，我们需要定义一个接收器函数。接收器可以是任何 Python 函数或方法

def my_callback(sender, **kwargs):
    print("Request finished!")

请注意，该函数采用 sender 参数以及通配符关键字参数 (**kwargs)；所有信号处理程序都必须采用这些参数。

稍后我们将了解发送者 ，但现在先了解 **kwargs 参数。所有信号都发送关键字参数，并且可以随时更改这些关键字参数。对于 request_finished，它被记录为不发送任何参数，这意味着我们可能倾向于将信号处理写为 my_callback(sender)。

这样做是错误的——事实上，如果你这样做，Django 将会抛出一个错误。这是因为在任何时间点，都可能向信号添加参数，而你的接收器必须能够处理这些新参数。

接收器也可以是异步函数，具有相同的签名，但使用 async def 声明

async def my_callback(sender, **kwargs):
    await asyncio.sleep(5)
    print("Request finished!")

信号可以同步或异步发送，接收器将自动适应正确的调用样式。有关更多信息，请参见 发送信号。

连接接收器函数¶

你可以通过两种方式将接收器连接到信号。你可以采取手动连接方式

from django.core.signals import request_finished

request_finished.connect(my_callback)

或者，你可以使用 receiver() 装饰器

receiver(signal, **kwargs)¶

参数	signal – 要将函数连接到的信号或信号列表。 kwargs – 要传递给 函数 的通配符关键字参数。

以下是使用装饰器进行连接的方法

from django.core.signals import request_finished
from django.dispatch import receiver


@receiver(request_finished)
def my_callback(sender, **kwargs):
    print("Request finished!")

现在，每当请求完成时，我们的 my_callback 函数都会被调用。

from django.apps import AppConfig
from django.core.signals import request_finished


class MyAppConfig(AppConfig):
    ...

    def ready(self):
        # Implicitly connect signal handlers decorated with @receiver.
        from . import signals

        # Explicitly connect a signal handler.
        request_finished.connect(signals.my_callback)

连接到特定发送者发送的信号¶

有些信号会被发送多次，但您只会对接收这些信号中的某个特定子集感兴趣。例如，考虑在模型保存之前发送的django.db.models.signals.pre_save信号。大多数情况下，您不需要知道任何模型何时保存——只需要知道一个特定模型何时保存。

在这些情况下，您可以注册仅接收特定发送者发送的信号。对于django.db.models.signals.pre_save，发送者将是正在保存的模型类，因此您可以指示您仅需要某些模型发送的信号

from django.db.models.signals import pre_save
from django.dispatch import receiver
from myapp.models import MyModel


@receiver(pre_save, sender=MyModel)
def my_handler(sender, **kwargs): ...

my_handler函数仅在保存MyModel实例时才会被调用。

不同的信号使用不同的对象作为其发送者；您需要查阅内置信号文档以了解每个特定信号的详细信息。

防止重复信号¶

在某些情况下，将接收器连接到信号的代码可能会运行多次。这会导致您的接收器函数被注册多次，从而在信号事件中被调用多次。例如，ready()方法可能会在测试期间执行多次。更普遍地说，这发生在您的项目导入您定义信号的模块的任何地方，因为信号注册会随着它的导入而运行多次。

如果此行为存在问题（例如，在使用信号在每次保存模型时发送电子邮件时），将唯一标识符作为 dispatch_uid 参数传递，以识别接收器函数。此标识符通常为字符串，尽管任何哈希对象都足够。最终结果是，对于每个唯一的 dispatch_uid 值，接收器函数只会绑定到信号一次

from django.core.signals import request_finished

request_finished.connect(my_callback, dispatch_uid="my_unique_identifier")

定义信号¶

class Signal¶

所有信号都是 django.dispatch.Signal 实例。

例如

import django.dispatch

pizza_done = django.dispatch.Signal()

这声明了一个 pizza_done 信号。

发送信号¶

在 Django 中有两种方法可以同步发送信号。

Signal.send(sender, **kwargs)¶

Signal.send_robust(sender, **kwargs)¶

信号也可以异步发送。

Signal.asend(sender, **kwargs)¶

Signal.asend_robust(sender, **kwargs)¶

若要发送信号，请调用 Signal.send()、Signal.send_robust()、await Signal.asend() 或 await Signal.asend_robust()。您必须提供 sender 参数（通常为类），并且可以提供任意数量的其他关键字参数。

例如，以下是发送我们的 pizza_done 信号的方式

class PizzaStore:
    ...

    def send_pizza(self, toppings, size):
        pizza_done.send(sender=self.__class__, toppings=toppings, size=size)
        ...

所有四种方法都会返回元组对列表 [(receiver, response), ...]，表示已调用的接收器函数列表及其响应值。

send() 与 send_robust() 的不同之处在于如何处理接收器函数引发的异常。 send() 不会捕获接收器引发的任何异常；它只是允许错误传播。因此，在出现错误的情况下，并非所有接收器都会收到信号通知。

send_robust() 会捕获源自 Python 的 Exception 类的所有错误，并确保所有接收器都会收到信号通知。如果发生错误，则错误实例将以引发错误的接收器的元组对形式返回。

调用 send_robust() 时，返回的错误的 __traceback__ 属性中存在回溯。

asend() 类似于 send()，但它是一个必须等待的协程

async def asend_pizza(self, toppings, size):
    await pizza_done.asend(sender=self.__class__, toppings=toppings, size=size)
    ...

无论是同步还是异步，接收器都会正确地适应是否使用 send() 或 asend()。通过 asend() 调用时，将使用 sync_to_async() 调用同步接收器。通过 sync() 调用时，将使用 async_to_sync() 调用异步接收器。类似于 中间件的情况，以这种方式调整接收器会产生少量性能开销。请注意，为了减少 send() 或 asend() 调用中同步/异步调用样式切换的次数，在调用接收器之前，会按它们是否是异步对它们进行分组。这意味着在同步接收器之前注册的异步接收器可能会在同步接收器之后执行。此外，异步接收器使用 asyncio.gather() 并发执行。

除了异步请求-响应周期中的信号外，所有内置信号都使用 Signal.send() 发送。