NcatBot 文档

外观

定时任务

约 856 字大约 3 分钟

2025-03-27

BasePlugin 提供了注册定时任务的功能.

注册定时任务

一般在 BasePlugin.on_load() 方法中时注册定时任务.

实际案例

函数原型和使用方法

通过 BasePlugin.add_scheduled_task 来注册定时任务，函数原型如下：

class BasePlugin:
    @final
    def add_scheduled_task(
        self,
        job_func: Callable,
        name: str,
        interval: Union[str, int, float],
        conditions: Optional[List[Callable[[], bool]]] = None,
        max_runs: Optional[int] = None,
        args: Optional[Tuple] = None,
        kwargs: Optional[Dict] = None,
        args_provider: Optional[Callable[[], Tuple]] = None,
        kwargs_provider: Optional[Callable[[], Dict[str, Any]]] = None,
    ) -> bool:
        """
        添加定时任务

        Args:
            job_func (Callable): 要执行的任务函数
            name (str): 任务唯一标识名称
            interval (Union[str, int, float]): 调度时间参数
            conditions (Optional[List[Callable]]): 执行条件列表
            max_runs (Optional[int]): 最大执行次数
            args (Optional[Tuple]): 静态位置参数
            kwargs (Optional[Dict]): 静态关键字参数
            args_provider (Optional[Callable]): 动态位置参数生成函数
            kwargs_provider (Optional[Callable]): 动态关键字参数生成函数

        Returns:
            bool: 是否添加成功

        Raises:
            ValueError: 当参数冲突或时间格式无效时
        """

注册不同类型的任务

通过 interval 参数来明确任务类型.

  • 一次性任务: 传入字符串格式为 YYYY-MM-DD HH:MM:SS 或 GitHub Action 格式 YYYY:MM:DD-HH:MM:SS. 在这个时间点执行一次.
  • 间隔任务: 传入字符串格式为 120s, 2h30m, 0.5d 或冒号分隔格式 00:15:30 (时:分:秒) 或自然语言格式 2天3小时5秒. 从当前开始, 经过指定时间间隔后执行一次.
  • 每日任务: 传入字符串格式为 HH:MM. 每天在这个时间点执行一次.

任务的时间精度有限, 大约有 5s 的误差.

任务回调函数

job_func 参数为任务回调函数, 该函数会在任务触发时执行. 会传入一些参数, 参数传入规则如下:

提示

args 参数必须写为元组, Python 语法中, (expr) 被解析为一个表达式, 而不是元组, (expr,) 才会被解析为元组.

  1. args 位置参数:

    • 通过 args 静态指定, 在 add_scheduled_task 中传入一个 args 元组可以静态指定参数.
    • 通过 args_provider 动态指定, 在 add_scheduled_task 中传入一个 args_provider 函数可以动态指定参数. 函数的返回值必须是元组, 会在任务触发时调用这个函数并生成 job_func 的位置参数.
    • 两者互斥

  2. kwargs 命名参数:

    • 通过 kwargs 静态指定, 在 add_scheduled_task 中传入一个 kwargs 字典可以静态指定参数.
    • 通过 kwargs_provider 动态指定, 在 add_scheduled_task 中传入一个 kwargs_provider 函数可以动态指定参数. 函数的返回值必须是字典, 会在任务触发时调用这个函数并生成 job_func 的命名参数.
    • 两者互斥

你也可以用 lambda 表达式之类的来实现函数传参.

最大执行次数

通过 max_runs 参数来指定任务的最大执行次数, 当任务执行次数超过这个值时, 任务会被移除.

一次性任务最大执行次数默认为 1, 禁用 max_runs 参数.

任务判定条件

conditions 参数为任务执行条件列表, 是一系列的函数, 每个函数都返回一个布尔值. 当所有函数都返回 True 时, 任务才会被执行.

版权归属：huan-yp

许可证：署名 4.0 国际 (CC-BY-4.0)

© 2025 NcatBot