@alanwang-merit/meritdata-platform-skill-package 1.0.0

package/skills/meritdata-dev-docs-file-finder/references/dev-docs/.bak//345/272/224/347/224/250/345/274/200/345/217/221/345/271/263/345/217/260-/345/237/272/347/241/200/345/271/263/345/217/260-/344/275/277/347/224/250/346/224/273/347/225/245/357/274/210/345/215/201/357/274/211/357/274/232/345/256/232/346/227/266/350/260/203/345/272/246/344/273/273/345/212/241.md

@@ -0,0 +1,392 @@
+---
+title: 微服务使用攻略（五）：定时调度任务
+date: 2025.05.27
+categories:
+  - 开发攻略
+  - 6.13.2
+---
+
+# 微服务使用攻略（十）：定时调度任务
+
+## 使用背景
+
+​		很多的业务场景需要我们在某一个特定的时刻去做某件任务，比如特定时间对数据统计，数据同步，对账，导出业务数据。使用分布式调度任务, 整体操作都在页面中，可视化效果好。之前我们用的单体调度，系统中一个集群中只有一个节点运行调度进程，该节点执行所有调度任务，但是一旦出现故障，则所有的都进行不下去，扩展性比较低，因此，我们引入了分布式调度。
+
+## 更新记录
+
+| 版本   | 时间       | 更新内容     |
+| ------ | ---------- | ------------ |
+| 6.13.2 | 2025-05-27 | 定时调度任务 |
+
+## 1.调度相关应用包
+
+| 应用/依赖包       | 备注                 |
+| ----------------- | -------------------- |
+| cloud-system-job  | 调度任务服务端       |
+| cloud-starter-job | 调度任务客户端依赖包 |
+
+## 2.配置项相关
+
+调度任务配置为 nacos 中的 common-cloud-system-job.properties 文件
+
+```properties
+#job执行器可以使用的端口,用于创建客户端netty服务 默认从8000,65535端口轮询，填一个值，端口作为起始端口
+meritdata.cloud.job.executor.port=8000,9000
+#job config 日志清理天数
+meritdata.cloud.job.logretentiondays=-1
+#i18n (default empty as chinese, "en" as english)
+meritdata.cloud.job.i18n=
+#系统日志文件路径
+meritdata.cloud.job.executor.port=
+```
+
+## 3.调度功能使用
+
+完成系统环境搭建
+启动完后可访问 job 管理页面 ,8080 端口为前端应用 nginx 的启动端口
+http://ip地址:8080/portal
+
+### 3.1. 调度任务客户端注册
+
+新建一个 project-business-sso 执行器客户端样例服务，参考《微服务使用攻略（一）：系统环境搭建》后端工程创建，添加依赖包至客户端应用的 pom.xml 的 dependencies 节点
+
+```xml
+<dependency>
+    <groupId>com.meritdata.cloud</groupId>
+    <artifactId>cloud-starter-job</artifactId>
+    <version>${meritdata-cloud.version}</version>
+</dependency>
+```
+
+同时需要在工程下的bootstrap.properties中找到spring.profiles.include并添加cloud-system-job，如下图：
+
+![image](/imgs/定时调度任务/2-4.png)
+
+
+
+执行器客户端服务启动完后，访问执行器管理页面可在页面发现该客户端已注册
+
+![image](/imgs/定时调度任务/1-1.png)
+
+### 3.2. 客户端应用内新增调度任务
+
+```java
+import com.xxl.job.core.biz.model.ReturnT;
+import com.xxl.job.core.handler.IJobHandler;
+import com.xxl.job.core.handler.annotation.JobHandler;
+import com.xxl.job.core.log.XxlJobLogger;
+import org.springframework.stereotype.Component;
+/**
+ 任务 Handler 示例（Bean 模式）
+ 开发步骤：
+ 1、继承"IJobHandler"：“com.xxl.job.core.handler.IJobHandler”；
+ 2、注册到 Spring 容器：添加“@Component”注解，被 Spring 容器扫描为 Bean 实例；
+ 3、注册到执行器工厂：添加“@JobHandler(value="自定义 jobhandler 名称")”注解，注解 value 值对应的是调度中心新建任务的 JobHandler 属性的值。
+ 4、执行日志：需要通过 "XxlJobLogger.log" 打印执行日志；
+*/
+@Component(value="demoJobHandler")
+@JobHandler(value="demoJobHandler")
+public class HelloWorldJob extends IJobHandler {
+    @Override
+    public ReturnT<String> execute(String param) throws Exception {
+    System.out.println("demoJobHandler");
+    XxlJobLogger.log("demoJobHandler");
+    return SUCCESS;
+    }
+}
+
+```
+
+### 3.3. 调度任务管理页面新增调度任务
+
+新增中的 JobHandler 值为@JobHandler 注解的 Value 值，参考样例如下图：
+
+- 调度任务管理界面如下：
+  ![image](/imgs/定时调度任务/1-2.png)
+  
+- 调度任务维护界面如下：
+  ![image](/imgs/定时调度任务/1-2-1.png)
+  
+- 新增调度任务
+
+  - 执行器：服务名称
+
+  - 路由策略：执行器集群部署时提供的路由策略
+
+    - 第一个：固定选择第一个机器
+    - 最后一个： 固定选择最后一个机器
+    - 轮询：负载均衡+故障转移（根据jobId和路由地址数量求余，进行轮询，超过24小时，清零，从头开始）
+    - 随机：随机选择一个在线机器
+    - 一致性hash：主要解决集群增加或者减少节点
+    - 最不经常使用：
+    - 最近最久未使用：
+    - 故障转移：按照顺序依次进行心跳检测，第一个心跳检测成功的机器选为目标执行器并发起调度
+    - 忙碌转移：广播出发对应机器中所有机器执行一次任务，同时系统自动传递分片参数；可以根据分片参数开发分片任务
+
+  - cron表达式：是一个字符串，字符串以5或6个空格隔开，分为6或7个域，每一个域代表一个含义  
+  参见附录1 cron表达式
+
+
+
+  - JobHandler：这里填的是后端编写的调度任务JobHandler中注解名称
+
+  - 阻塞处理策略：
+
+    - 单机串行：以队列的形式，顺序执行
+    - 丢弃后续调度：如果有运行的调度任务，则新加入的直接返回失败。
+    - 覆盖之前调度：如果有运行的调度任务，则停止现有的调度任务，执行最新的调度任务。
+
+  - 子任务ID
+
+  - 任务超时时间
+
+  - 失败重试次数
+
+  - 负责人
+
+  - 报警邮件
+
+  - 任务参数
+
+## 4. 调度任务 API 接口
+
+平台提供调度任务接口供维护调度任务数据，接口详情访问 http://ip:8080/gateway/swagger-ui.html
+
+![image](/imgs/定时调度任务/1-3.png)
+
+## 5. 对外调度任务 API 接口
+
+```java
+/**
+* 获取任务信息
+*/
+@RequestMapping(value = "/jobinfo/get", method = RequestMethod.POST)
+ReturnT<CloudJobInfo> getJob(@RequestParam(name = "id") int id);
+
+/**
+* 获取任务信息列表
+*/
+ @RequestMapping(value = "/jobinfo/pageList", method = RequestMethod.POST)
+ Map<String, Object>  pageList(@RequestParam(name = "param") Map param);
+
+/**
+* 执行调度任务
+*/
+@RequestMapping(value = "/jobinfo/trigger", method = RequestMethod.POST)
+ReturnT<String> triggerJob(@RequestParam(name = "id") int id,
+                               @RequestParam(name = "executorParam", required = false) String executorParam);
+
+/**
+* 启动调度任务
+*@Param id 任务Id
+*/
+ @RequestMapping(value = "/jobinfo/start", method = RequestMethod.POST)
+ ReturnT<String> startJob(@RequestParam(name = "id") int id);
+
+/**
+* 停止调度任务
+*@Param id 任务Id
+*/
+@RequestMapping(value = "/jobinfo/stop", method = RequestMethod.POST)
+ReturnT<String> stopJob(@RequestParam(name = "id") int id);
+
+/**
+* 新增调度任务
+*/
+@RequestMapping(value = "/jobinfo/add", method = RequestMethod.POST)
+ReturnT<String> add(@SpringQueryMap CloudJobInfo jobInfo);
+
+/**
+* 更新调度任务
+*/
+@RequestMapping(value = "/jobinfo/update", method = RequestMethod.POST)
+ReturnT<String> update(@SpringQueryMap CloudJobInfo jobInfo);
+
+/**
+* 删除调度任务
+*@Param id 任务Id
+*/
+ @RequestMapping(value = "/jobinfo/remove", method = RequestMethod.POST)
+ ReturnT<String> remove(@RequestParam(name = "id") int id);
+
+/**
+* 根据应用名获取执行器
+*@Param appName 应用名
+*/
+@RequestMapping(value = "/jobgroup/getByAppName", method = RequestMethod.POST)
+CloudJobGroup getByAppName(@RequestParam(name = "appName") String appName);
+
+/**
+* 根据执行器名称获取job信息
+*/
+@RequestMapping(value = "/jobinfo/getHandler", method = RequestMethod.POST)
+ReturnT<CloudJobInfo> getHandler(@RequestParam(name = "handlerName") String handlerName);
+```
+
+```java
+import com.meritdata.cloud.job.api.IJobApi;
+import com.meritdata.cloud.job.model.CloudJobInfo;
+import com.xxl.job.core.biz.model.ReturnT;
+import com.xxl.job.core.handler.IJobHandler;
+import com.xxl.job.core.handler.annotation.JobHandler;
+
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.stereotype.Component;
+
+import java.util.HashMap;
+import java.util.Map;
+
+/**
+ 任务 Handler 示例（Bean 模式）
+ 开发步骤：
+ 1、继承"IJobHandler"：“com.xxl.job.core.handler.IJobHandler”；
+ 2、注册到 Spring 容器：添加“@Component”注解，被 Spring 容器扫描为 Bean 实例；
+ 3、注册到执行器工厂：添加“@JobHandler(value="自定义 jobhandler 名称")”注解，注解 value 值对应的是调度中心新建任务的 JobHandler 属性的值。
+ 4、执行日志：需要通过 "XxlJobLogger.log" 打印执行日志；
+ */
+@Component(value="demoJobHandler")
+@JobHandler(value="demoJobHandler")
+public class HelloWorldJob extends IJobHandler {
+
+    @Autowired
+    IJobApi webServerJobService;
+
+    /**
+    *   调用新增: param(1.动作，2.执行器Id，3.调度任务名称，4.路由策略，
+    *   5.运行模式，6.cron表达式，7.jobHandler名称，8.阻塞处理策略，9.负责人，10.任务周期类型，11.任务类型) 
+    *   create,1,测试新增,FIRST,BEAN,0 1/1 * * * ?,
+    *   helloWorldHandler,SERIAL_EXECUTION,张三
+    *
+    *   调用更新param（1.动作，2.Id，3.执行器Id，4.调度任务名称，5.路由策略，
+    *   6.运行模式，7.cron表达式，8.jobHandler名称，9.阻塞处理策略，10.负责人，11.任务周期类型，12.任务类型）
+    *   update,22,1,测试新增,FIRST,BEAN,0 1/1 * * * ?,
+    *   helloWorldHandler,SERIAL_EXECUTION,张三
+    *
+    *   调用启动任务param(1.动作，2.Id) start,22
+    *
+    *   调用停止任务param(1.动作，2.Id) stop,22
+    *
+    *   调用执行任务param(1.动作，2.Id) trigger,22
+    *
+    *   调用删除任务param(1.动作，2.Id) delete,22
+    *
+    */
+    @Override
+    public ReturnT<String> execute(String param) throws Exception {
+        String [] paramArr = param.split(",");
+        String type = paramArr[0];
+        Map map = new HashMap<>();
+        CloudJobInfo cloudJobInfo = new CloudJobInfo();
+        switch (type){
+            case "create" :
+
+                cloudJobInfo.setJobGroup(Integer.parseInt(paramArr[1]));
+                cloudJobInfo.setJobDesc(paramArr[2]);
+                cloudJobInfo.setExecutorRouteStrategy(paramArr[3]);
+                cloudJobInfo.setGlueType(paramArr[4]);
+                cloudJobInfo.setJobCron(paramArr[5]);
+
+                cloudJobInfo.setExecutorHandler(paramArr[6]);
+                cloudJobInfo.setExecutorBlockStrategy(paramArr[7]);
+                cloudJobInfo.setAuthor(paramArr[8]);
+                //任务的周期类型：{"7:年任务", "6:季度任务", "5:月任务", "4:周任务", "3:天任务", "2:小时任务", "1:分钟任务", "0:秒任务"}
+                cloudJobInfo.setPeroid(paramArr[9]);
+                //任务创建的产品类型
+                cloudJobInfo.setType(paramArr[10]);
+                webServerJobService.add(cloudJobInfo);
+                break;
+            case "update" :
+                cloudJobInfo.setId(Integer.parseInt(paramArr[1]));
+                cloudJobInfo.setJobGroup(Integer.parseInt(paramArr[2]));
+                cloudJobInfo.setJobDesc(paramArr[3]);
+                cloudJobInfo.setExecutorRouteStrategy(paramArr[4]);
+                cloudJobInfo.setGlueType(paramArr[5]);
+                cloudJobInfo.setJobCron(paramArr[6]);
+
+                cloudJobInfo.setExecutorHandler(paramArr[7]);
+                cloudJobInfo.setExecutorBlockStrategy(paramArr[8]);
+                cloudJobInfo.setAuthor(paramArr[9]);
+                //任务的周期类型：{"7:年任务", "6:季度任务", "5:月任务", "4:周任务", "3:天任务", "2:小时任务", "1:分钟任务", "0:秒任务"}
+                cloudJobInfo.setPeroid(paramArr[10]);
+                //任务创建的产品类型
+                cloudJobInfo.setType(paramArr[11]);
+                webServerJobService.update(cloudJobInfo);
+                break;
+            case "start" :
+                map.put("id",paramArr[1]);
+                webServerJobService.startJob(Integer.parseInt(paramArr[1]));
+                break;
+            case "stop" :
+                map.put("id",paramArr[1]);
+                webServerJobService.stopJob(Integer.parseInt(paramArr[1]));
+                break;
+            case "trigger":
+                map.put("id",paramArr[1]);
+                webServerJobService.triggerJob(Integer.parseInt(paramArr[1]),"");
+                break;
+            case "delete":
+                map.put("id",paramArr[1]);
+                webServerJobService.remove(Integer.parseInt(paramArr[1]));
+                break;
+            default:
+        }
+        return SUCCESS;
+    }
+}
+```
+
+
+
+# 附录 A. https 方式的执行器注册
+
+- 获取执行器微服务中的服务名，参考样例如下图：
+  ![image](/imgs/定时调度任务/2-3.png)
+
+- 在 nacos 中，新增配置文件 common.properties，参考样例如下图：
+
+  ```shell
+  #前端工程部署的ip和端口号 如果前端工程也是集群模式 此处配置为系统的入口的ip和端口号 单机默认和后端的服务器一致
+  meritdata.cloud.web-server=http://${meritdata.cloud.server.ip}:8080
+  #调用gateway的ip和端口号 用于服务之间的互相调用（跳过nginx）
+  meritdata.cloud.web-server-gateway=http://${meritdata.cloud.server.ip}:8081
+  ```
+
+  ![image](/imgs/定时调度任务/2-2.png)
+
+- 修改执行器微服务中的配置文件，参考样例如下图：
+  ![image](/imgs/定时调度任务/2-1.png)
+
+- 重启执行器微服务
+
+
+# 附录 1. cron表达式
+  - 结构：从左到右： 秒  分  时  日  月  周   年
+
+  - 各字段含义：
+
+      | 字段               | 允许值                         | 允许特殊字符                                     |
+      | ------------------ | ------------------------------ | ------------------------------------------------ |
+      | 秒（second）       | 0~59的整数                     | ,    -    *    /   四个字符                      |
+      | 分（minute）       | 0~59的整数                     | ,    -    *    /   四个字符                      |
+      | 时（hour）         | 0~59的整数                     | ,    -    *    /   四个字符                      |
+      | 日（dayOfMonth）   | 1~31的整数（需要考虑月的天数） | ,    -    *    /    ?    L    W    C   八个字符  |
+      | 月（month）        | 1~12的整数                     | ,    -    *    /   四个字符                      |
+      | 周（weekOfMonth）  | 1~7的整数  或者 SUN~SAT(1=SUN) | ,    -    *    /    ?    L    C    #    八个字符 |
+      | 年（year）可以不填 | 1970~2099                      | ,    -    *    /   四个字符                      |
+
+  - 特殊字符含义：
+      - *: 表示匹配该域的任意值，加入在minute域中使用，表示每分钟都会触发事件。
+      - ?: 智能用在dayOfMonth和dayOfWeek两个域。它也匹配域的任意值，但实际不会。因为dayOfMonth和dayOfWeek会互相影响。例如想在每月的20日触发调度任务，不管20日是星期几，则只能用如下写法：13 13 15 20 * ?,其中最后一位只能用? ,而不能使用*，如果使用*表示不管在星期几都会触发，并不是我们想要的效果。
+      - -: 表示范围，例如在minute域中使用5-20，表示从5分钟到20分钟，每分钟执行一次。
+      - /: 表示起始时间开始触发，然后每隔固定时间触发一次。例如在minute域中使用5/20，则意味着每5分钟触发一次，而25，45等分钟分别触发一次。
+      - ,: 表示列举出枚举值，例如：在minute域中使用5,20 则表示在5和20分钟各触发一次。
+      - L: 表示最后，只能出现在dayOfMonth和dayOfWeek域。如果在dayOfWeek域使用5L,意味着在最后一个的星期四触发。
+      - W: 表示有效工作日（周一到周五），只能出现在dayOfMonth域，系统将在离指定日期的最近的有效工作日触发。例如：在dayOfMonth使用5W，如果5日是星期六，则将在最近的工作日：星期五，即4日触发。如果5日是星期天，则在6日（周一）触发。如果5日在星期一到星期五中的某一天，则就在5日触发。另外一点，W的最近寻找不会跨月。
+      - LW: 这两个字符可以连用，表示在某个月的最后一个工作日，即最后一个星期五。
+      - #: 用于确定每个月第几个星期几，只能出现在dayOfMonth，例如在4#2，表示某月的第二个星期三。
+  - 常用表达式：
+
+      - 0  0  2  1   * ？ *  每月1日 凌晨2点 执行
+      - 0 15 10 ？* MON-FRI  周一到周五 10点15分  执行
+      - 0  0  10,14,16  * * ? 每天10点 14点  16点 执行
+      - 0 0/5 14,18  *  *  ?  每天下午2点到2点55，下午6点到6点55 每五分钟执行一次