Integrate Spring jobs with SchedulerX - SchedulerX - Centro de documentación de Alibaba Cloud

El programador integrado de Spring ofrece una forma práctica de ejecutar tareas programadas en Java, pero presenta limitaciones en entornos empresariales. Al integrar sus trabajos de Spring con SchedulerX, los complementa con funciones de nivel empresarial como monitoreo, programación avanzada y alta disponibilidad.

Requisitos previos

Tiene instalada la versión 1.8.13 o posterior del agente de SchedulerX.
Su aplicación de Spring Boot está conectada a SchedulerX. Para obtener más información, consulte Connect a Spring Boot application to SchedulerX.

Procedimiento

Paso 1: Agregar la dependencia

En una aplicación de Spring Boot, agregue la dependencia de SchedulerX al archivo pom.xml.

Utilice la versión más reciente del agente para schedulerx2.version. Para obtener más información, consulte Agent Release Notes.

<dependency>
  <groupId>com.aliyun.schedulerx</groupId>
  <artifactId>schedulerx2-spring-boot-starter</artifactId>
  <version>${schedulerx2.version}</version>
  <!-- If you use Logback, you must exclude Log4j and Log4j2. -->
  <exclusions>
    <exclusion>
      <groupId>org.apache.logging.log4j</groupId>
      <artifactId>log4j-api</artifactId>
    </exclusion>
    <exclusion>
      <groupId>org.apache.logging.log4j</groupId>
      <artifactId>log4j-core</artifactId>
    </exclusion>
    <exclusion>
      <groupId>log4j</groupId>
      <artifactId>log4j</artifactId>
    </exclusion>
  </exclusions>
</dependency>

Independientemente de si es la primera vez que usa trabajos de Spring o si ya cuenta con algunos, debe conservar la anotación @EnableScheduling en su clase principal para habilitar la programación.

@SpringBootApplication
@EnableScheduling /** Enable Spring scheduled jobs. */
public class SchedulerXWorkerApplication {
    public static void main(String[] args) {
        SpringApplication.run(SchedulerXWorkerApplication.class, args);
    }
}
/** A native Spring scheduled job class. */
@Service
public class SpringScheduledProcessor {
    @Scheduled(cron = "0/2 * * * * ?")
    public void hello() {
        logger.info(DateUtil.now() + " hello world. start");
        logger.info(DateUtil.now() + " hello world. end");
    }
}

De forma predeterminada, después de agregar la dependencia, SchedulerX no gestiona los trabajos de Spring existentes. El contenedor de Spring sigue programando estos trabajos y su ejecución no se ve afectada.

Paso 2: Agregar parámetros de configuración

Para permitir que SchedulerX gestione sus trabajos de Spring, agregue la siguiente configuración al archivo application.properties.

# 1. Application access configuration
spring.schedulerx2.endpoint=${endpoint}
spring.schedulerx2.namespace=${namespace}
spring.schedulerx2.groupId=${groupId}
spring.schedulerx2.appKey=${appKey}

# 2. Enable SchedulerX to manage Spring jobs
spring.schedulerx2.task.scheduling.scheduler=schedulerx

# 3. Optional: Enable automatic synchronization for existing Spring jobs
#spring.schedulerx2.task.scheduling.sync=true
#spring.schedulerx2.regionId=Specify the region ID for job synchronization.
#spring.schedulerx2.aliyunAccessKey=XXXXXXXXX
#spring.schedulerx2.aliyunSecretKey=XXXXXXXXX

A continuación se describen los parámetros:

Configuración de acceso a la aplicación: Inicie sesión en la consola de SchedulerX. En el panel de navegación izquierdo, haga clic en Application Management. Busque su aplicación y, en la columna Actions, haga clic en Access Configuration para obtener sus credenciales. Si es la primera vez que establece la conexión, debe crear un grupo de aplicaciones.
Configuración de sincronización automática: Si tiene una gran cantidad de trabajos de Spring existentes, habilite la sincronización automática para evitar crear las tareas manualmente, tal como se describe en Step 3. Para consultar la lista de identificadores de región, vea Endpoints.

Importante

Para mantener la coherencia con las reglas de ejecución de trabajos nativos de Spring en un entorno de clúster, los trabajos que se sincronizan automáticamente con la plataforma de SchedulerX utilizan de forma predeterminada el modo de ejecución Broadcast run. Esto significa que cada máquina del clúster ejecuta el trabajo a la hora programada. Si su negocio requiere que solo una máquina del clúster ejecute el trabajo, edite el modo de ejecución del trabajo a Stand-alone operation en la consola. Para obtener más información sobre los parámetros, consulte Step 3.

Paso 3 (opcional): Crear una tarea manualmente

Nota

Si habilitó la sincronización automática en Step 2, omita este paso.

Inicie sesión en la consola de SchedulerX.
En el panel de navegación izquierdo, haga clic en task management.

En la página task management, haga clic en Create Task. Seleccione SpringSchedule como tipo de tarea y configure el nombre de la clase y del método.

Parámetro	Descripción
Name	Un nombre único para identificar la tarea.
Description	Una descripción opcional que le ayuda a buscar y gestionar la tarea.
Application ID	El grupo de aplicaciones al que pertenece la tarea. Seleccione una opción de la lista desplegable.
Job Type	El tipo de procesador de la tarea. Valores válidos: Java, Shell, Python, Go, HTTP, Node.js, SpringSchedule, XXL-JOB y DataWorks. Si selecciona Shell, Python o Go, aparece un editor de script. Para este tutorial, seleccione SpringSchedule.
Spring Schedule Configuration	El nombre de clase totalmente calificado y el nombre del método de la tarea.
Execution Mode	Especifica cómo se ejecuta la tarea en varias instancias. Se admiten los siguientes modos: Stand-alone operation: Ejecuta la tarea en una instancia seleccionada de forma aleatoria. Broadcast run: Ejecuta la tarea en todas las instancias de forma simultánea. Nota La configuración avanzada cambia según el modo de ejecución seleccionado.
Priority	Si varias tareas de la misma aplicación están listas para ejecutarse en la misma instancia, la tarea con mayor prioridad se ejecuta primero. SchedulerX utiliza una cola de prioridad apropiativa para garantizar que las tareas de alta prioridad se ejecuten antes, incluso entre distintas instancias. Para obtener más información, consulte Application-level Throttling with a Priority Queue.
Job Parameters	Una cadena personalizada que se puede recuperar del contexto del trabajo durante la ejecución.

Configure la programación.

Nota

La programación configurada en la consola anula la especificada en la anotación @Scheduled de su código. Sin embargo, debe conservar dicha anotación en el código.

En la siguiente tabla se describen los parámetros basados en tiempo.

Parámetro	Descripción
Time Type	none: La tarea no se programa y normalmente la activa un flujo de trabajo. cron: La tarea se programa mediante una expresión cron. api: La tarea se activa mediante una llamada a la API. fixed_rate: La tarea se activa con una frecuencia fija. second_delay: La tarea se activa tras un retraso fijo en segundos. one_time: La tarea se ejecuta una sola vez.
Cron Expression (solo para el tipo de tiempo cron)	Introduzca una expresión cron estándar. También puede utilizar la herramienta integrada para generar y validar la expresión.
Fixed frequency (solo para el tipo de tiempo fixed_rate)	Introduzca el intervalo en segundos. El valor debe ser mayor o igual a 60. Por ejemplo, un valor de 200 significa que la tarea se ejecuta cada 200 segundos.
Fixed delay (solo para el tipo de tiempo second_delay)	Introduzca el retraso en segundos. El valor debe estar entre 1 y 60. Por ejemplo, un valor de 5 significa que la tarea se activa 5 segundos después de la hora programada.

En la siguiente tabla se describen los parámetros de configuración avanzada.

Parámetro	Descripción
Data Timestamp Offset	El desfase entre la marca de tiempo de los datos y la hora programada. Este valor se puede recuperar del contexto del trabajo durante la ejecución.
Time Zone	Seleccione una zona horaria según los requisitos de su negocio. Se admiten tanto zonas horarias regionales como la zona horaria estándar GMT.
Calendar	Puede seleccionar un calendario, como uno de días laborables o días financieros, para restringir la ejecución de la tarea a días específicos.

Establezca las reglas de alerta y los canales de notificación. Para obtener más información, consulte Manage Notification Contacts.

Una vez completados estos pasos, SchedulerX gestiona sus trabajos de Spring y proporciona capacidades de nivel empresarial, como monitoreo visual, consultas de registros, seguimiento de ejecución y alertas.

Paso 4: Comprobar la integración

Inicie su aplicación de Spring. Una vez iniciada, inicie sesión en la consola de SchedulerX y haga clic en Application Management en el panel de navegación izquierdo. Compruebe que las instancias de su aplicación aparezcan en la lista.

En la columna Instances, confirme que el número sea mayor que 0. También puede hacer clic en View Instances en la columna Actions para ver los detalles de las instancias conectadas.

En el panel de navegación izquierdo, haga clic en task management. Busque la tarea correspondiente a su aplicación y haga clic en Run Once en la columna Actions. Una ejecución exitosa confirma la integración.

Preguntas frecuentes

¿Por qué el temporizador original de Spring sigue ejecutándose después de que SchedulerX toma el control?

Si en su aplicación se especifica un programador personalizado, SchedulerX lo sobrescribe. Este conflicto suele ocurrir cuando una clase implementa org.springframework.scheduling.annotation.SchedulingConfigurer y llama al método setScheduler de ScheduledTaskRegistrar, lo cual sobrescribe el programador predeterminado.

Para resolver este problema, siga estos pasos:

Busque en su proyecto cualquier clase que implemente SchedulingConfigurer.
Compruebe si se llama al método setScheduler de ScheduledTaskRegistrar.
Si alguna de estas condiciones se cumple, comente el código del programador personalizado.

¿Cómo obtengo el contexto del trabajo en un trabajo de Spring?

Llame a ContainerFactory.getContainerPool().getContext() para obtener el JobContext actual:

// Get the SchedulerX job context inside a @Scheduled method
JobContext jobContext = ContainerFactory.getContainerPool().getContext();

¿Un trabajo de Spring puede devolver un resultado de procesamiento?

Esta función requiere una versión del agente de SchedulerX posterior a la 1.10.11. Las versiones 1.10.11 y anteriores no son compatibles con los valores devueltos por los trabajos de Spring.

Los resultados de procesamiento se devuelven según los métodos de programación especificados. Los trabajos de Spring admiten dos tipos de retorno:

Tipo de retorno	Caso de uso
`ProcessResult`	Devuelve un estado de éxito o error junto con un mensaje de resultado.
`String`	Devuelve únicamente un mensaje de resultado.

Ambos ejemplos siguientes utilizan la anotación @Scheduled con una expresión cron.

**Devolver un ProcessResult**

Utilice ProcessResult para indicar éxito o error junto con un mensaje de resultado:

@Scheduled(cron = "0/5 * * * * ?")
public ProcessResult helloStandalone1() {
    try {
        logger.info(DateUtil.now() + " " + Thread.currentThread().getName() + " hello world. start");
        TimeUnit.SECONDS.sleep(2L);
        logger.info(DateUtil.now() + " " + Thread.currentThread().getName() + " hello world. end");
    } catch (Exception e) {
        e.printStackTrace();
        logger.info(DateUtil.now() + " " + Thread.currentThread().getName() + " hello world. exception end..");
    }
    // First argument: true for success, false for failure
    // Second argument: result message
    return new ProcessResult(true, "Processing result");
}

**Devolver un String**

Devuelva un String directamente cuando no necesite una marca explícita de éxito o error:

@Scheduled(cron = "0/5 * * * * ?")
public String helloStandalone2() {
    try {
        logger.info(DateUtil.now() + " " + Thread.currentThread().getName() + " hello world. start");
        TimeUnit.SECONDS.sleep(2L);
        logger.info(DateUtil.now() + " " + Thread.currentThread().getName() + " hello world. end");
    } catch (Exception e) {
        e.printStackTrace();
        logger.info(DateUtil.now() + " " + Thread.currentThread().getName() + " hello world. exception end..");
    }
    return "Processing result";
}