All Products
Search
Document Center

Microservices Engine:Pekerjaan terjadwal Spring

Last Updated:Jun 21, 2026

Pekerjaan terjadwal Spring merupakan cara praktis untuk menjalankan tugas terjadwal dalam aplikasi Java, tetapi memiliki keterbatasan dalam skenario enterprise. Dengan mengintegrasikannya ke SchedulerX, Anda dapat menambahkan kemampuan tingkat enterprise ke pekerjaan tersebut.

Prasyarat

Integrasi

Langkah 1: Tambahkan dependensi pom

Untuk aplikasi Spring Boot, tambahkan dependensi berikut ke file pom.xml.

Atur schedulerx2.version ke versi agent terbaru. Untuk informasi selengkapnya, lihat Catatan rilis Agent.

<dependency>
  <groupId>com.aliyun.schedulerx</groupId>
  <artifactId>schedulerx2-spring-boot-starter</artifactId>
  <version>${schedulerx2.version}</version>
  <!-- Jika Anda menggunakan Logback, Anda harus mengecualikan dependensi Log4j dan 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>

Baik Anda membuat pekerjaan terjadwal Spring baru maupun menggunakan yang sudah ada, Anda harus tetap menyertakan anotasi @EnableScheduling pada kelas utama Anda.

@SpringBootApplication
@EnableScheduling /** Aktifkan pekerjaan terjadwal Spring */
public class SchedulerXWorkerApplication {
    public static void main(String[] args) {
        SpringApplication.run(SchedulerXWorkerApplication.class, args);
    }
}
/** Kelas pekerjaan terjadwal Spring native */
@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");
    }
}

Untuk aplikasi baru atau yang sudah ada dengan konfigurasi ini, SchedulerX tidak secara otomatis mengambil alih pekerjaan terjadwal Spring secara default. Pekerjaan tersebut tetap dijadwalkan oleh kontainer Spring. Hal ini memastikan bahwa pekerjaan terjadwal Spring yang sudah ada tidak terpengaruh.

Langkah 2: Tambahkan parameter konfigurasi

Agar SchedulerX dapat mengelola pekerjaan terjadwal Spring Anda, tambahkan konfigurasi berikut ke file Properties Anda.

# 1. Konfigurasi akses aplikasi
spring.schedulerx2.endpoint=${endpoint}
spring.schedulerx2.namespace=${namespace}
spring.schedulerx2.groupId=${groupId}
spring.schedulerx2.appKey=${appKey}
# 2. Aktifkan SchedulerX untuk mengambil alih pekerjaan terjadwal Spring
spring.schedulerx2.task.scheduling.scheduler=schedulerx
# 3. (Opsional) Aktifkan sinkronisasi otomatis untuk pekerjaan
#spring.schedulerx2.task.scheduling.sync=true
#spring.schedulerx2.regionId=ID wilayah target untuk sinkronisasi. Untuk informasi tentang ID wilayah, lihat Endpoints.
#spring.schedulerx2.aliyunAccessKey=XXXXXXXXX
#spring.schedulerx2.aliyunSecretKey=XXXXXXXXX

Deskripsi parameter:

  • Konfigurasi akses aplikasi: Login ke Konsol MSE SchedulerX. Di panel navigasi sebelah kiri, klik Application Management. Di halaman Applications, temukan aplikasi Anda dan klik Access Config di kolom Actions untuk mendapatkan detail konfigurasi. Jika ini pertama kalinya Anda menghubungkan aplikasi, Anda harus membuat kelompok aplikasi.

  • Aktifkan sinkronisasi pekerjaan otomatis: Jika Anda memiliki banyak pekerjaan terjadwal Spring yang sudah ada, Anda dapat mengaktifkan sinkronisasi otomatis dalam file konfigurasi aplikasi. Hal ini sangat menyederhanakan proses pembuatan manual yang dijelaskan di Langkah 3. Untuk ID wilayah dalam konfigurasi, lihat ID wilayah di Endpoints.

Penting

Untuk menjaga konsistensi dengan cara pekerjaan Spring native dijalankan dalam kluster, pekerjaan yang disinkronkan secara otomatis secara default menggunakan mode eksekusi Broadcast run. Artinya, pekerjaan tersebut dijalankan di setiap mesin dalam kluster pada waktu yang dijadwalkan. Jika Anda ingin pekerjaan hanya dijalankan di satu mesin yang dipilih dari kluster, Anda dapat mengedit pekerjaan tersebut di konsol dan mengubah mode eksekusinya menjadi Stand-alone operation. Untuk informasi selengkapnya tentang parameter tersebut, lihat Langkah 3.

Langkah 3: Buat pekerjaan terjadwal secara manual (opsional)

Catatan

Jika Anda telah mengaktifkan sinkronisasi otomatis di Langkah 2, Anda tidak perlu melakukan langkah ini.

  1. Login ke Konsol MSE SchedulerX.

  2. Di panel navigasi sebelah kiri, klik Task Management.

  3. Di halaman Task Management, klik Add Task. Pilih tipe tugas SpringSchedule, lalu konfigurasikan nama kelas dan nama metode untuk pekerjaan terjadwal tersebut.

    Parameter

    Deskripsi

    Task name

    Nama pekerjaan.

    Description

    Deskripsi singkat pekerjaan untuk mempermudah pencarian dan pengelolaan.

    Application ID

    Kelompok aplikasi tempat pekerjaan tersebut berada. Pilih nilai dari daftar drop-down.

    Task Type

    Bahasa yang digunakan untuk mengimplementasikan pekerjaan. Jenis yang didukung meliputi Java, Shell, Python, Go, HTTP, Node.js, XXL-JOB, dan DataWorks. Untuk Shell, Python, dan Go, editor akan muncul sehingga Anda dapat menulis skrip pekerjaan.

    Dalam topik ini, tipe tugas adalah SpringSchedule.

    Spring Schedule configuration

    Nama kelas lengkap (fully qualified class name) dan nama metode dari pekerjaan terjadwal.

    Execution Mode

    Mode eksekusi pekerjaan. Mode yang didukung meliputi:

    • Stand-alone operation: Dijalankan di satu mesin yang dipilih secara acak.

    • Broadcast run: Dijalankan di semua mesin secara bersamaan dan menunggu hingga semuanya selesai.

    Catatan

    Parameter dalam pengaturan lanjutan bervariasi tergantung pada mode eksekusi yang dipilih.

    Priority

    Saat beberapa pekerjaan dalam aplikasi yang sama dijalankan pada instans yang sama, pekerjaan dengan prioritas lebih tinggi dieksekusi terlebih dahulu. Namun, jika pekerjaan didistribusikan ke beberapa instans, pekerjaan dengan prioritas lebih rendah mungkin dieksekusi lebih dulu jika dijadwalkan ke instans berbeda. SchedulerX mencegah hal ini dengan menggunakan antrian prioritas preemptible, yang memastikan pekerjaan berprioritas tinggi dalam antrian selalu dieksekusi terlebih dahulu. Untuk informasi selengkapnya, lihat Gunakan antrian prioritas pekerjaan untuk pembatasan laju tingkat aplikasi.

    Task Parameters

    Anda dapat mengambil parameter ini dari konteks pekerjaan saat waktu proses.

  4. Konfigurasikan frekuensi pemicu.

    Catatan

    Frekuensi yang dikonfigurasi di konsol memiliki prioritas lebih tinggi. Konfigurasi dalam anotasi @Scheduled native di kode pekerjaan terjadwal Spring Anda akan diabaikan, tetapi Anda harus tetap menyimpan anotasi tersebut di kode.

    Parameter waktu dijelaskan sebagai berikut:

    Parameter

    Deskripsi

    Time type

    • none: Tidak ada tipe penjadwalan. Biasanya dipicu oleh alur kerja.

    • cron: Ekspresi cron.

    • api: Dipicu oleh panggilan API.

    • fixed_rate: Frekuensi tetap.

    • second_delay: Penundaan tetap dalam detik.

    • one_time: Pekerjaan satu kali.

    cron expression (hanya untuk tipe cron)

    Masukkan ekspresi cron. Anda dapat memasukkannya langsung atau menggunakan tool untuk menghasilkan dan memvalidasinya.

    Fixed frequency (hanya untuk tipe fixed_rate)

    Frekuensi minimum yang didukung adalah 60 detik. Misalnya, nilai 200 menjadwalkan pekerjaan untuk dijalankan setiap 200 detik.

    Fixed delay (hanya untuk tipe second_delay)

    Nilai yang valid berkisar antara 1 hingga 60. Misalnya, nilai 5 memicu pekerjaan setelah penundaan 5 detik.

    Parameter konfigurasi lanjutan dijelaskan sebagai berikut:

    Parameter

    Deskripsi

    Data Timestamp Offset

    Nilai ini dapat diambil dari konteks pekerjaan selama penjadwalan.

    Time zone

    Anda dapat memilih zona waktu sesuai kebutuhan, termasuk negara atau wilayah umum, serta format GMT standar.

    Calendar

    Pilih Workday atau Financial day.

  5. Tetapkan kondisi peringatan dan saluran notifikasi. Untuk informasi selengkapnya tentang saluran notifikasi, lihat Kontak notifikasi.

    Setelah menyelesaikan langkah-langkah ini, platform SchedulerX akan mengambil alih dan menjalankan pekerjaan terjadwal Spring Anda. Anda dapat menggunakan fitur tingkat enterprise seperti manajemen visual, kueri log pekerjaan, pelacakan eksekusi, dan pemberitahuan peringatan.

Langkah 4: Verifikasi integrasi pekerjaan

  1. Jalankan aplikasi Spring Anda. Setelah aplikasi berjalan, login ke Konsol MSE SchedulerX. Di panel navigasi sebelah kiri, klik Application Management dan periksa instans yang terhubung dalam kelompok aplikasi. Kehadiran instans mengonfirmasi koneksi berhasil.

Di daftar aplikasi, pastikan Total number of instances untuk aplikasi target lebih besar dari 0. Klik View instances di kolom Operation untuk melihat detail instans.

  1. Di panel navigasi sebelah kiri, klik Task Management. Temukan pekerjaan yang sesuai dengan aplikasi Anda, lalu di kolom Actions, klik Run once. Eksekusi yang berhasil menunjukkan bahwa pengaturan telah selesai.

FAQ

Mengapa timer Spring asli tetap berjalan setelah SchedulerX mengambil alih?

Jika scheduler kustom ditentukan dalam aplikasi Anda, SchedulerX akan menimpa scheduler kustom tersebut. Konflik ini biasanya terjadi ketika sebuah kelas mengimplementasikan org.springframework.scheduling.annotation.SchedulingConfigurer dan memanggil metode setScheduler dari ScheduledTaskRegistrar, yang menimpa scheduler default.

Untuk mengatasi masalah ini:

  1. Cari di proyek Anda kelas apa pun yang mengimplementasikan SchedulingConfigurer.

  2. Periksa apakah metode setScheduler dari ScheduledTaskRegistrar dipanggil.

  3. Jika salah satu kondisi tersebut benar, beri komentar pada kode scheduler kustom tersebut.

Bagaimana cara mendapatkan konteks pekerjaan dalam pekerjaan Spring?

Panggil ContainerFactory.getContainerPool().getContext() untuk mendapatkan JobContext saat ini:

// Dapatkan konteks pekerjaan SchedulerX di dalam metode @Scheduled
JobContext jobContext = ContainerFactory.getContainerPool().getContext();

Apakah pekerjaan Spring dapat mengembalikan hasil pemrosesan?

Fitur ini memerlukan versi agent SchedulerX yang lebih baru dari 1.10.11. Versi 1.10.11 dan sebelumnya tidak mendukung nilai kembali dari pekerjaan Spring.

Hasil pemrosesan dikembalikan berdasarkan metode penjadwalan yang ditentukan. Pekerjaan Spring mendukung dua tipe nilai kembali:

Tipe nilai kembaliKasus penggunaan
ProcessResultMengembalikan status sukses/gagal beserta pesan hasil
StringMengembalikan hanya pesan hasil

Kedua contoh berikut menggunakan anotasi @Scheduled dengan ekspresi cron.

Mengembalikan ProcessResult

Gunakan ProcessResult untuk menunjukkan status sukses atau gagal beserta pesan hasil:

@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..");
    }
    // Argumen pertama: true untuk sukses, false untuk gagal
    // Argumen kedua: pesan hasil
    return new ProcessResult(true, "Processing result");
}

Mengembalikan String

Kembalikan String secara langsung jika Anda tidak memerlukan flag eksplisit sukses/gagal:

@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";
}