@llryiop/avatar-boot-cli 1.0.1 → 1.0.2

package/templates/.claude/skills/avatar-boot-starter-job/README.md

@@ -0,0 +1,437 @@
+---
+name: avatar-boot-starter-job
+description: 当使用 avatar-boot-starter-job 模块时使用此技能 - 为 Spring Boot 3.5.3 应用提供基于 XXL-Job 2.4.0 的分布式任务调度能力，包含自动配置、监控指标、AOP 拦截。
+---
+
+Avatar Boot 的 XXL-Job 分布式任务调度集成模块，提供开箱即用的任务调度能力和完善的监控指标。
+
+## 功能特性
+
+- ✅ **零代码配置** - 基于 Spring Boot 自动配置机制，自动装配 XXL-Job 执行器
+- ✅ **原生配置兼容** - 使用 XXL-Job 原生配置属性（xxl.job.*），无需学习新配置
+- ✅ **条件装配** - 支持通过 `enabled` 开关控制是否启用
+- ✅ **AOP 监控** - 自动拦截 @XxlJob 方法，记录执行指标
+- ✅ **Micrometer 集成** - 内置任务执行和执行器状态监控指标
+- ✅ **优雅日志** - 清晰的启动和执行日志，便于问题排查
+- ✅ **完全兼容** - 100% 兼容 XXL-Job 原生注解和功能
+
+## 快速开始
+
+### 1. 添加依赖
+
+在项目的 `pom.xml` 中添加依赖：
+
+```xml
+<dependency>
+    <groupId>com.iflytek.avatar.boot</groupId>
+    <artifactId>avatar-boot-starter-job</artifactId>
+</dependency>
+```
+
+### 2. 配置文件
+
+在 `application.yml` 中添加配置：
+
+```yaml
+xxl:
+  job:
+    enabled: true  # 是否启用（默认 true）
+    admin:
+      addresses: http://localhost:8080/xxl-job-admin  # 调度中心地址
+    executor:
+      appname: your-app-name  # 执行器名称（必填）
+      port: 9999  # 执行器端口（默认 9999）
+      logpath: logs/xxl-job  # 日志路径（默认 logs/xxl-job）
+      logretentiondays: 30  # 日志保留天数（默认 30）
+    access-token: your-token  # 访问令牌（可选）
+```
+
+### 3. 编写任务处理器
+
+使用 `@XxlJob` 注解标记任务方法：
+
+```java
+package com.example.job;
+
+import com.xxl.job.core.context.XxlJobHelper;
+import com.xxl.job.core.handler.annotation.XxlJob;
+import lombok.extern.slf4j.Slf4j;
+import org.springframework.stereotype.Component;
+
+@Slf4j
+@Component
+public class SampleJobHandler {
+
+    /**
+     * 简单任务示例
+     */
+    @XxlJob("demoJobHandler")
+    public void demoJobHandler() {
+        log.info("XXL-JOB, Hello World.");
+    }
+
+    /**
+     * 带参数的任务示例
+     */
+    @XxlJob("paramJobHandler")
+    public void paramJobHandler() {
+        String param = XxlJobHelper.getJobParam();
+        log.info("XXL-JOB, 接收参数: {}", param);
+    }
+
+    /**
+     * 分片任务示例
+     */
+    @XxlJob("shardingJobHandler")
+    public void shardingJobHandler() {
+        int shardIndex = XxlJobHelper.getShardIndex();
+        int shardTotal = XxlJobHelper.getShardTotal();
+        log.info("分片参数：当前分片序号 = {}, 总分片数 = {}", shardIndex, shardTotal);
+    }
+}
+```
+
+**重要说明：**
+- 任务处理器类必须被 Spring 管理（添加 `@Component` 注解）
+- `@XxlJob` 注解的值必须与调度中心配置的 JobHandler 名称一致
+- 监控指标会自动记录所有 @XxlJob 方法的执行情况
+
+### 4. 在调度中心配置任务
+
+1. 登录 XXL-Job 调度中心
+2. 执行器管理 -> 新增执行器（AppName 与配置文件中的 `appname` 一致）
+3. 任务管理 -> 新增任务
+    - JobHandler: `demoJobHandler`（与 @XxlJob 注解的值一致）
+    - 调度类型: CRON
+    - Cron: `0 0/1 * * * ?`（每分钟执行一次）
+
+## 配置说明
+
+### 必填配置
+
+| 配置项 | 说明 | 示例 |
+|--------|------|------|
+| `xxl.job.admin.addresses` | 调度中心地址 | `http://localhost:8080/xxl-job-admin` |
+| `xxl.job.executor.appname` | 执行器名称 | `my-app-executor` |
+
+### 可选配置
+
+| 配置项 | 说明 | 默认值 |
+|--------|------|--------|
+| `xxl.job.enabled` | 是否启用 XXL-Job | `true` |
+| `xxl.job.executor.port` | 执行器端口 | `9999` |
+| `xxl.job.executor.ip` | 执行器 IP（为空自动获取） | 空 |
+| `xxl.job.executor.address` | 执行器注册地址（优先使用） | 空 |
+| `xxl.job.executor.logpath` | 日志路径 | `logs/xxl-job` |
+| `xxl.job.executor.logretentiondays` | 日志保留天数 | `30` |
+| `xxl.job.access-token` | 访问令牌 | 空 |
+
+### 监控配置
+
+| 配置项 | 说明 | 默认值 |
+|--------|------|--------|
+| `xxl.job.metrics.enabled` | 是否启用所有监控指标 | `true` |
+| `xxl.job.metrics.execution-enabled` | 是否启用任务执行监控 | `true` |
+| `xxl.job.metrics.executor-enabled` | 是否启用执行器状态监控 | `true` |
+
+## 功能详解
+
+### 1. 自动配置机制
+
+模块使用 Spring Boot 自动配置机制，满足以下条件时自动装配：
+
+- Classpath 中存在 `XxlJobSpringExecutor` 类
+- 配置 `xxl.job.enabled=true`（默认为 true）
+- 未手动定义 `XxlJobSpringExecutor` Bean
+
+**启动日志：**
+```
+>>>>>>>>>>> XXL-Job 执行器配置初始化
+>>>>>>>>>>> XXL-Job 执行器配置完成: appname=my-app, adminAddresses=http://localhost:8080/xxl-job-admin
+```
+
+### 2. AOP 监控拦截
+
+使用 AspectJ 自动拦截所有 `@XxlJob` 注解的方法：
+
+- **执行前**：记录开始时间，增加活跃任务计数
+- **执行后**：记录执行时长、成功/失败状态
+- **异常时**：记录异常信息和执行时长
+- **最终**：减少活跃任务计数
+
+**日志输出：**
+```
+DEBUG: Job [demoJobHandler] executed successfully in 125ms
+ERROR: Job [failedJobHandler] failed after 50ms
+```
+
+### 3. 任务执行结果回调
+
+```java
+@XxlJob("callbackJobHandler")
+public void callbackJobHandler() {
+    try {
+        // 业务逻辑
+        XxlJobHelper.handleSuccess("任务执行成功");
+    } catch (Exception e) {
+        XxlJobHelper.handleFail("任务执行失败: " + e.getMessage());
+    }
+}
+```
+
+### 4. 任务日志输出
+
+```java
+@XxlJob("logJobHandler")
+public void logJobHandler() {
+    XxlJobHelper.log("这是一条任务日志");
+    XxlJobHelper.log("支持多行日志输出");
+}
+```
+
+## 监控指标
+
+本 Starter 内置了基于 Micrometer 的监控指标采集功能，可与 Prometheus、Grafana 等监控系统集成。
+
+### 启用监控
+
+监控功能默认启用，如需禁用可通过配置：
+
+```yaml
+xxl:
+  job:
+    metrics:
+      enabled: false  # 禁用所有监控指标
+      execution-enabled: true  # 仅启用任务执行监控（默认 true）
+      executor-enabled: true  # 仅启用执行器状态监控（默认 true）
+```
+
+### 可用指标
+
+#### 1. 任务执行指标
+
+| 指标名称 | 类型 | 标签 | 说明 |
+|---------|------|------|------|
+| `xxl.job.execution.count` | Counter | `job_handler`, `status` | 任务执行次数（status: success/failure） |
+| `xxl.job.execution.time` | Timer | `job_handler`, `status` | 任务执行耗时（毫秒） |
+| `xxl.job.execution.active` | Gauge | 无 | 当前正在执行的任务数 |
+
+#### 2. 执行器状态指标
+
+| 指标名称 | 类型 | 标签 | 说明 |
+|---------|------|------|------|
+| `xxl.job.executor.registered` | Gauge | `app_name` | 执行器注册状态（1=已注册，0=未注册） |
+| `xxl.job.executor.handlers.total` | Gauge | `app_name` | 已注册的 JobHandler 总数 |
+
+### Prometheus 查询示例
+
+```promql
+# 查询任务执行成功率
+sum(rate(xxl_job_execution_count_total{status="success"}[5m]))
+/
+sum(rate(xxl_job_execution_count_total[5m])) * 100
+
+# 查询任务平均执行时间（秒）
+rate(xxl_job_execution_time_seconds_sum[5m])
+/
+rate(xxl_job_execution_time_seconds_count[5m])
+
+# 查询特定任务的失败次数
+sum(xxl_job_execution_count_total{job_handler="demoJobHandler", status="failure"})
+
+# 查询当前活跃任务数
+xxl_job_execution_active
+
+# 查询执行器注册状态
+xxl_job_executor_registered{app_name="your-app-name"}
+
+# 查询已注册的 JobHandler 数量
+xxl_job_executor_handlers_total{app_name="your-app-name"}
+```
+
+### Grafana 面板配置
+
+推荐创建以下监控面板：
+
+#### 1. 任务执行概览
+- **总执行次数**：`sum(increase(xxl_job_execution_count_total[1h]))`
+- **成功率**：`sum(rate(xxl_job_execution_count_total{status="success"}[5m])) / sum(rate(xxl_job_execution_count_total[5m])) * 100`
+- **平均耗时**：`rate(xxl_job_execution_time_seconds_sum[5m]) / rate(xxl_job_execution_time_seconds_count[5m])`
+
+#### 2. 任务执行趋势
+- **执行次数趋势**：`rate(xxl_job_execution_count_total[5m])`（按 job_handler 分组）
+- **失败次数趋势**：`rate(xxl_job_execution_count_total{status="failure"}[5m])`
+
+#### 3. 执行器状态
+- **注册状态**：`xxl_job_executor_registered`
+- **Handler 数量**：`xxl_job_executor_handlers_total`
+- **活跃任务数**：`xxl_job_execution_active`
+
+#### 4. 性能分析
+- **P95 耗时**：`histogram_quantile(0.95, rate(xxl_job_execution_time_seconds_bucket[5m]))`
+- **P99 耗时**：`histogram_quantile(0.99, rate(xxl_job_execution_time_seconds_bucket[5m]))`
+
+### 集成 Prometheus
+
+在 `application.yml` 中启用 Prometheus 端点：
+
+```yaml
+management:
+  endpoints:
+    web:
+      exposure:
+        include: prometheus,health,info
+  metrics:
+    export:
+      prometheus:
+        enabled: true
+```
+
+访问 `http://localhost:8080/actuator/prometheus` 查看指标数据。
+
+## 使用场景
+
+### 场景 1：开发环境禁用任务调度
+
+```yaml
+# application-dev.yml
+xxl:
+  job:
+    enabled: false  # 开发环境禁用
+```
+
+### 场景 2：多环境配置
+
+```yaml
+# application-prod.yml
+xxl:
+  job:
+    enabled: true
+    admin:
+      addresses: http://prod-xxl-job:8080/xxl-job-admin
+    executor:
+      appname: prod-app-executor
+      port: 9999
+    access-token: ${XXL_JOB_TOKEN}  # 从环境变量读取
+```
+
+### 场景 3：只监控特定任务
+
+```yaml
+xxl:
+  job:
+    metrics:
+      execution-enabled: true  # 启用任务执行监控
+      executor-enabled: false  # 禁用执行器状态监控
+```
+
+## 高级用法
+
+### 1. 自定义执行器配置
+
+```yaml
+xxl:
+  job:
+    executor:
+      ip: 192.168.1.100  # 指定执行器 IP
+      address: http://192.168.1.100:9999  # 指定注册地址（优先级最高）
+      logpath: /data/logs/xxl-job  # 使用绝对路径
+```
+
+### 2. 多调度中心配置
+
+```yaml
+xxl:
+  job:
+    admin:
+      addresses: http://admin1:8080/xxl-job-admin,http://admin2:8080/xxl-job-admin
+```
+
+### 3. 禁用监控指标
+
+```yaml
+xxl:
+  job:
+    metrics:
+      enabled: false  # 完全禁用监控
+```
+
+## 常见问题
+
+### 1. 执行器无法注册到调度中心
+
+**原因**：网络不通或配置错误
+
+**解决**：
+- 检查 `xxl.job.admin.addresses` 是否正确
+- 检查调度中心是否启动
+- 检查执行器端口是否被占用
+- 查看启动日志中的错误信息
+
+### 2. 任务无法触发
+
+**原因**：JobHandler 名称不匹配
+
+**解决**：
+- 确保 `@XxlJob` 注解的值与调度中心配置的 JobHandler 一致
+- 确保任务处理器类被 Spring 管理（添加 `@Component` 注解）
+- 检查执行器是否成功注册
+
+### 3. 日志无法查看
+
+**原因**：日志路径权限不足
+
+**解决**：
+- 检查 `xxl.job.executor.logpath` 路径是否有写权限
+- 使用绝对路径或确保相对路径可写
+- 检查磁盘空间是否充足
+
+### 4. 监控指标不显示
+
+**原因**：Actuator 端点未暴露或监控被禁用
+
+**解决**：
+- 确保 `xxl.job.metrics.enabled=true`
+- 检查 Actuator 配置是否正确
+- 访问 `/actuator/prometheus` 验证指标是否存在
+
+### 5. 任务执行时间不准确
+
+**原因**：AOP 拦截可能包含框架开销
+
+**解决**：
+- 监控指标记录的是方法执行时间（包含 AOP 开销）
+- 如需精确业务逻辑耗时，在方法内部单独计时
+- AOP 开销通常在 1-5ms 范围内
+
+## 架构说明
+
+### 核心组件
+
+- **XxlJobAutoConfiguration**：自动配置类，创建 XxlJobSpringExecutor Bean
+- **XxlJobProperties**：配置属性类，映射 xxl.job.* 配置
+- **XxlJobMetricsAspect**：AOP 切面，拦截 @XxlJob 方法记录指标
+- **JobMetricsRecorder**：指标记录器，封装 Micrometer API
+- **ExecutorMetricsCollector**：执行器状态收集器，定期更新执行器指标
+
+### 自动配置条件
+
+```java
+@ConditionalOnClass(XxlJobSpringExecutor.class)  // 类路径存在 XXL-Job
+@ConditionalOnProperty(prefix = "xxl.job", name = "enabled",
+                       havingValue = "true", matchIfMissing = true)  // 配置启用
+@ConditionalOnMissingBean  // 未手动定义 Bean
+```
+
+## 依赖版本
+
+- XXL-Job: 2.4.0
+- Spring Boot: 3.5.3
+- Micrometer: 由 Spring Boot BOM 管理
+- Java: 21
+
+## 参考文档
+
+- [XXL-Job 官方文档](https://www.xuxueli.com/xxl-job/)
+- [XXL-Job GitHub](https://github.com/xuxueli/xxl-job)
+- [Micrometer 文档](https://micrometer.io/docs)