基于注解与静态代码分析的 Java 定时任务元数据提取及运维文档自动化实践

package com.chunli.job.doc.annotation;

import java.lang.annotation.Documented;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

@Target({ElementType.METHOD})
@Retention(RetentionPolicy.RUNTIME)
@Documented
public @interface JobDoc {

    /**
     * 任务中文名称
     */
    String title();

    /**
     * 业务负责人（可填写域账号/工号）
     */
    String owner();

    /**
     * 业务影响等级：P0 / P1 / P2 / P3
     */
    String level() default "P2";

    /**
     * 预计最大耗时（秒），用于监控阈值比对
     */
    int expectedTimeoutSeconds() default 60;

    /**
     * 涉及的核心库/表，方便 DBA 协同排查
     */
    String[] impactTables() default {};
}

@Component
public class OrderTimeoutCancelJob {

    /**
     * 扫描超时未支付的订单并执行关单回滚
     * 静态分析工具可自动提取此处 Javadoc 作为补充说明
     */
    @Scheduled(cron = "${biz.jobs.order-timeout.cron:0 0/10 * * * ?}")
    @JobDoc(
        title = "超时未支付订单自动关单",
        owner = "chunli",
        level = "P1",
        expectedTimeoutSeconds = 120,
        impactTables = {"t_order", "t_order_item", "t_sku_stock"}
    )
    public void executeOrderCancel() {
        // 业务逻辑...
    }
}

package com.chunli.job.doc.extractor;

import com.github.javaparser.StaticJavaParser;
import com.github.javaparser.ast.CompilationUnit;
import com.github.javaparser.ast.body.MethodDeclaration;
import com.github.javaparser.ast.expr.AnnotationExpr;
import com.github.javaparser.ast.expr.MemberValuePair;
import com.github.javaparser.ast.expr.NormalAnnotationExpr;

import java.io.File;
import java.io.IOException;
import java.nio.file.Files;
import java.nio.file.Path;
import java.util.ArrayList;
import java.util.List;
import java.util.stream.Stream;

public class JobMetadataParser {

    public List<JobMetadata> parseProject(Path sourceDir) throws IOException {
        List<JobMetadata> result = new ArrayList<>();

        try (Stream<Path> paths = Files.walk(sourceDir)) {
            paths.filter(p -> p.toString().endsWith(".java")).forEach(path -> {
                try {
                    CompilationUnit cu = StaticJavaParser.parse(path);
                    cu.findAll(MethodDeclaration.class).forEach(method -> {
                        // 检索是否存在 @JobDoc
                        method.getAnnotationByName("JobDoc").ifPresent(jobDocAnno -> {
                            JobMetadata meta = extractMetadata(cu, method, jobDocAnno);
                            result.add(meta);
                        });
                    });
                } catch (Exception e) {
                    System.err.println("解析文件失败: " + path + ", 原因: " + e.getMessage());
                }
            });
        }
        return result;
    }

    private JobMetadata extractMetadata(CompilationUnit cu, MethodDeclaration method, AnnotationExpr jobDocAnno) {
        JobMetadata meta = new JobMetadata();
        meta.setMethodName(method.getNameAsString());
        cu.getPrimaryTypeName().ifPresent(meta::setClassName);

        // 提取 Javadoc 说明
        method.getJavadocComment().ifPresent(doc -> meta.setDescription(doc.parse().toText().trim()));

        // 解析 @JobDoc 属性
        if (jobDocAnno.isNormalAnnotationExpr()) {
            NormalAnnotationExpr normal = jobDocAnno.asNormalAnnotationExpr();
            for (MemberValuePair pair : normal.getPairs()) {
                String key = pair.getNameAsString();
                String value = pair.getValue().toString().replace("\"", "");
                switch (key) {
                    case "title" -> meta.setTitle(value);
                    case "owner" -> meta.setOwner(value);
                    case "level" -> meta.setLevel(value);
                    case "expectedTimeoutSeconds" -> meta.setTimeout(Integer.parseInt(value));
                    case "impactTables" -> meta.setImpactTables(value);
                }
            }
        }

        // 解析调度规则（以 @Scheduled 为例）
        method.getAnnotationByName("Scheduled").ifPresent(sched -> {
            meta.setScheduleType("Spring @Scheduled");
            if (sched.isNormalAnnotationExpr()) {
                sched.asNormalAnnotationExpr().getPairs().stream()
                    .filter(p -> "cron".equals(p.getNameAsString()))
                    .findFirst()
                    .ifPresent(p -> meta.setCron(p.getValue().toString().replace("\"", "")));
            }
        });

        // 兼容 XXL-JOB 的 @XxlJob
        method.getAnnotationByName("XxlJob").ifPresent(xxl -> {
            meta.setScheduleType("XXL-JOB");
            meta.setCron("由 XXL-JOB 调度中心管理");
            // 可抽取 xxlJob 注册的 JobHandler 名称
            meta.setHandlerName(xxl.asSingleMemberAnnotationExpr().getMemberValue().toString().replace("\"", ""));
        });

        return meta;
    }
}

# 业务定时任务调度字典

| 任务名称 | 影响等级 | 负责人 | 调度类型 | Cron / Handler | 影响表 | 预计耗时 |
| :--- | :--- | :--- | :--- | :--- | :--- | :--- |
| 超时未支付订单自动关单 | P1 | chunli | Spring @Scheduled | `${biz.jobs.order-timeout.cron:...}` | `t_order, t_sku_stock` | 120s |

stages:
  - doc

generate_job_dictionary:
  stage: doc
  script:
    - mvn com.chunli.plugins:job-doc-maven-plugin:1.0.0:scan
    - curl -X POST -H "Content-Type: application/json" -d @target/job-metadata.json https://ops-gateway.internal/api/v1/jobs/sync
  only:
    - master
    - main