Snail Job

切换亮色/暗黑模式

快速开始 ​

🌈 特别说明

本指南将帮助您快速上手 SnailJob，通过一个简单的案例演示系统的核心功能。

1. 服务端部署 ​

1.1 初始化数据库 ​

  1. 数据库脚本位置：doc/sql/snail_job_mysql.sql
  2. 注意：数据库脚本中包含建库语句，默认使用 snail_job 数据库

1.2 获取源码 ​

bash
# Gitee
git clone https://gitee.com/aizuda/snail-job.git

# GitHub
git clone https://github.com/aizuda/snail-job.git

1.3 构建项目 ​

bash
mvn clean package

1.4 配置服务端 ​

  1. 配置文件位置：snail-job-server/snail-job-server-starter/src/main/resources/application.yml
  2. 修改数据库配置：
yaml
spring:
  datasource:
    name: snail_job
    url: jdbc:mysql://localhost:3306/snail_job?useSSL=false&characterEncoding=utf8&useUnicode=true
    username: root
    password: root
    # 其他配置信息...

1.5 启动服务端 ​

bash
java -jar snail-job-server/snail-job-server-starter/target/snail-job-server-exec.jar

启动成功后，访问管理控制台：

  • 地址：http://localhost:8080/snail-job
  • 默认账号：admin
  • 默认密码：admin

1.6 配置命名空间 ​

创建命名空间 ​

项目启动后创建属于自己的命名空间，如果不创建使用默认的也是可以的

  1. 配置空间 【test_sj】
    • namespace: a1NSize1D5jP83Wj0B6Hre094f7kFeHB

创建命名空间

切换命名空间 ​

此时您看到的就是【test_sj】视角下的数据信息

切换命名空间

1.7 配置执行器组 ​

创建执行器组 【test_sj_group】

  • Token: SJ_t3GFbbDCpmznt9M9Pp62GYJecE6S9q9H
  • groupName: test_sj_group

创建执行器组

2. 客户端配置 ​

2.1 添加依赖 ​

默认您已经有一个 SpringBoot 项目

正式发布版 点击查看最新版本号

xml
<dependencies>
    <!-- 核心依赖 -->
    <dependency>
        <groupId>com.aizuda</groupId>
        <artifactId>snail-job-client-starter</artifactId>
        <version>{Latest Version}</version>
    </dependency>
    
    <!-- 重试模块(若不需要可以不引入) -->
    <dependency>
        <groupId>com.aizuda</groupId>
        <artifactId>snail-job-client-retry-core</artifactId>
        <version>{Latest Version}</version>
    </dependency>
    
    <!-- 定时任务(若不需要可以不引入) -->
    <dependency>
        <groupId>com.aizuda</groupId>
        <artifactId>snail-job-client-job-core</artifactId>
        <version>{Latest Version}</version>
    </dependency>
</dependencies>

2.2 启用 SnailJob ​

在 SpringBoot 启动类上添加 @EnableSnailJob 注解：

java
@SpringBootApplication
// 这里还有另一种写法 @EnableSnailJob("test_sj_group") 
// 注解优先级 > 配置文件优先级 建议直接配置到配置文件中
@EnableSnailJob 
public class SnailJobSpringbootApplication {
    public static void main(String[] args) {
        SpringApplication.run(SnailJobSpringbootApplication.class, args);
    }
}

2.3 配置客户端 ​

yaml
snail-job:
  # 任务调度服务器信息
  server:
    # 服务器IP地址（或域名）；集群时建议通过 nginx 做负载均衡
    host: 127.0.0.1
    # 服务器通讯端口（不是后台管理页面服务端口）
    port: 1788
  # 命名空间 【上面配置的空间的唯一标识】
  namespace: a1NSize1D5jP83Wj0B6Hre094f7kFeHB
  # 接入组名【上面配置的组名称】注意: 若通过注解配置了这里的配置不生效
  group: test_sj_group
  # 接入组 token 【上面配置的token信息】
  token: SJ_t3GFbbDCpmznt9M9Pp62GYJecE6S9q9H
  # 客户端绑定IP，必须服务器可以访问到；默认自动推断，在服务器无法调度客户端时需要手动配置
  host: 127.0.0.1
  # 客户端通讯端口，默认 1789
  port: 1789

# 实时日志配置
logging:
  config: classpath:logback-boot.xml

2.4 配置实时日志 ​

xml
<!-- Snail appender -->
<appender name="snailLogAppender" class="com.aizuda.snailjob.client.common.appender.SnailLogbackAppender"></appender>

<!-- 控制台输出日志级别 -->
<root level="info">  
    <!-- 其他配置 -->
    <appender-ref ref="snailLogAppender" />
</root>

2.5 启动客户端 ​

在控制台中点击"在线机器"即可看到当前的客户端已经注册到了机器列表中

在线客户端

特别说明

通过以上配置，SnailJob 的客户端与服务端都已经配置完成。下面我们将演示定时任务和重试任务的使用。

3. 功能演示 ​

3.1 定时任务示例 ​

编写执行器 ​

java
@Component
@JobExecutor(name = "testJob")
public class TestJob {
    public ExecuteResult jobExecute(JobArgs jobArgs) {
        SnailJobLog.REMOTE.info("哈哈，测试成功了");
        RequestAddJobDTO jobDTO = OpenApiBuilder.newBuilder()
                .broadcast()
                .jobParams("")
                .jobName("")
                .build();
        return ExecuteResult.success();
    }
}

配置任务 ​

任务名称：testJob

创建定时任务

执行结果 ​

任务日志

3.2 重试任务示例 ​

编写重试接口 ​

java
@RestController
public class RetryController {
    @Autowired
    private RetryService retryService;

    @GetMapping("/snail-job/retry")
    public void retry() {
        retryService.retry("test");
    }
}

@Component
public class RetryService {
    @Retryable(scene = "test_sj_retry", retryStrategy = RetryType.LOCAL_REMOTE)
    public void retry(String s) {
        double i = 1 / 0;
    }
}

触发重试 ​

bash
# 调用接口模拟重试触发场景
GET http://localhost:8081/snail-job/retry

查看重试数据 ​

重试任务