定时任务 v3.1.1+

定时任务是项目开发中常用的功能，可以按一定频率周期性地执行任务。根据当前主流的定时任务实现，我们在框架内集成了与 XXL-JOB 配套的任务处理器服务。 具体实现依赖于 DotXxlJob，我们做了一些扩展，使其与框架功能更加契合。

提示

任务的调度触发在 XXL-JOB 服务端进行，这里仅关注客户端（业务代码）相关的内容，其它内容请查看官方文档。

定时任务的使用主要包含添加配置与编写任务处理器两部分，下面分别介绍。

配置

名称	类型	说明
Enable new	bool	是否启用，默认 false
AdminAddresses	String	服务端地址，多个以分号隔开。
AppName	String	应用标识，应与服务端执行器 AppName 一致。
SpecialBindUrl	String	服务对外调用地址
SpecialBindPath new	String	服务绑定路径，默认为 /xxl-job。
AccessToken	String	安全令牌
LogRetentionDays	Number	本地日志保存天数，默认 30 天

提示

SpecialBindPath 决定了客户端在哪个 URL （前缀）上响应 XXL-JOB 调用，这样可以与默认请求处理管道分离，减少不必要的内部处理逻辑。

注意

SpecialBindUrl 必须包含 SpecialBindPath 指定的内容，这样服务端才能将请求发送到正确的路径上。如果 SpecialBindPath 使用默认值，那么 SpecialBindUrl 应该为 http://{本应用地址}/xxl-job。

注意

SpecialBindAddress、Port 配置已弃用，应始终使用 SpecialBindUrl。AutoRegistry 配置已弃用，客户端始终自动向服务端注册。

示例

要启用定时任务，只需要在配置文件添加配置即可。

// appsettings.json
{
  // 其它配置省略
  "xxlJob": {
    "Enable": true,
    "AdminAddresses": "http://localhost:9000/xxl-job-admin",
    "AppName": "xxljob-net-frm",
    "SpecialBindUrl": "http://192.168.1.205:5001/xxl-job",
    "SpecialBindPath": "/xxl-job",
    "AccessToken": "ac03972bc954",
    "LogRetentionDays": 60
  },
}

任务处理器

定时任务的具体内容由开发人员定义，这里称为任务处理器。它由服务端触发后执行。

任务处理器必须实现 IJobHandler、IDisposable 接口。也可以选择继承 AbstractJobHandler 类，它提供了空的 Dispose 实现，开发人员只需要实现 Execute 方法。

[XxlJobHandler("frm-example")]
public class ExampleJobHandler(IRoleService roleService) : AbstractJobHandler
{
    // 这里同样支持属性注入，根据需要使用
    // [Autowired]
    // public IRoleService roleService;

    public override Task<ReturnT> Execute(JobExecuteContext context)
    {
        context.JobLogger.Log("Hello, xxljob!");
        context.JobLogger.Log("job handler called, params: " + context.JobParameter);
        context.JobLogger.Log("roles count:" + roleService.Count(t => true));
        return Task.FromResult(ReturnT.Success("成功"));
    }
}

提示

JobLogger 会将日志记录在本地，并在服务端请求时返回日志内容。

XxlJobHandler

在上例中处理器类添加了 XxlJobHandler 特性，它主要有两个作用：

• 指定任务处理器名称。必须与服务端中的 JobHandler 名称一致。
• 将处理器注册到 IoC 服务容器。默认为 Scoped 类型。

高级

服务作用域

在任务处理器中通常会调用其它业务服务（Scoped 类型）完成特定功能。 为方便调用，处理器服务现在也调整为 Scoped 类型，开发人员不必再手动创建 ServiceScope。

提示

框架在解析处理器服务时会先创建一个单独的服务域，它不同于响应请求时的服务域。

属性注入

处理器中可以正常使用 Autowired注入依赖。

注意

我们更推荐在新项目中使用主构造函数注入。

异常

处理器中的异常现在可以记录到系统日志与控制台，与普通服务一致。

事务

处理器代码中可以正常开启事务，框架会在任务结束时提交或回滚事务。

当前操作人

在调用处理时，框架会将操作人的 id 与 empSn 都设置为 “xxljob”，操作人的 name 设置为任务处理器名称。

升级指南

如果项目中之前已单独集成过 XXL-JOB，可以按如下步骤升级。

1. 移除 DotXxlJob 依赖
2. 移除相关服务注册与中间件声明。
3. 修改 JobHandler 使用 XxlJobHandler 特性，删除创建 ServiceScope 等代码。
4. 移动 JobHandler 至 Service 项目。因为通常不会扫描注册 Api 项目中的服务。
5. 修改配置文件，添加 Enable 配置，修改 SpecialBindUrl 以 /xxl-job 结尾。

提示

您仍然可以保持原有的配置和代码不作升级，框架提供的功能不会产生任何冲突。