createDeadLetterJobQuery

Flowable 7.1.0 摘要：创建死信作业查询对象，用于查询执行失败且重试次数耗尽的作业。

方法签名与说明

DeadLetterJobQuery createDeadLetterJobQuery()

创建死信作业查询构建器。死信作业是指执行失败且重试次数已用完的作业，需要人工干预处理。

Returns:

• DeadLetterJobQuery - 死信作业查询构建器

常见使用场景

1. 失败作业监控

监控系统中彻底失败的作业，及时发现和处理问题。

2. 错误告警

当出现死信作业时，触发告警通知运维人员。

3. 批量重试

对死信作业进行批量重试或清理。

Kotlin + Spring Boot 调用示例

示例1：查询所有死信作业

import org.flowable.engine.ManagementService
import org.springframework.stereotype.Service

@Service
class DeadLetterJobMonitor(
    private val managementService: ManagementService
) {
    
    /**
     * 查询所有死信作业
     * 企业场景：错误监控面板
     */
    fun getAllDeadLetterJobs(): List<Map<String, Any>> {
        val deadLetterJobs = managementService.createDeadLetterJobQuery()
            .list()
        
        if (deadLetterJobs.isNotEmpty()) {
            println("警告：发现 ${deadLetterJobs.size} 个死信作业！")
        }
        
        return deadLetterJobs.map { job ->
            mapOf(
                "jobId" to job.id,
                "processInstanceId" to job.processInstanceId,
                "exceptionMessage" to job.exceptionMessage,
                "duedate" to job.duedate
            )
        }
    }
}

示例2：死信作业告警

import org.flowable.engine.ManagementService
import org.springframework.scheduling.annotation.Scheduled
import org.springframework.stereotype.Service

@Service
class DeadLetterJobAlertService(
    private val managementService: ManagementService
) {
    
    /**
     * 定时检查死信作业并告警
     * 企业场景：每小时检查一次死信作业
     */
    @Scheduled(cron = "0 0 * * * ?")
    fun checkDeadLetterJobs() {
        val count = managementService.createDeadLetterJobQuery()
            .count()
        
        if (count > 0) {
            println("告警：当前有 $count 个死信作业需要处理")
            // 发送告警通知
            sendAlert("发现 $count 个失败作业")
        }
    }
    
    private fun sendAlert(message: String) {
        // 发送邮件、钉钉消息等
        println("发送告警: $message")
    }
}

示例3：批量恢复死信作业

import org.flowable.engine.ManagementService
import org.springframework.stereotype.Service

@Service
class DeadLetterJobRecoveryService(
    private val managementService: ManagementService
) {
    
    /**
     * 批量恢复死信作业
     * 企业场景：修复问题后，批量重试失败的作业
     */
    fun recoverAllDeadLetterJobs(): Map<String, Any> {
        val deadLetterJobs = managementService.createDeadLetterJobQuery()
            .list()
        
        var successCount = 0
        var failCount = 0
        
        deadLetterJobs.forEach { job ->
            try {
                // 移回可执行队列，恢复3次重试机会
                managementService.moveDeadLetterJobToExecutableJob(job.id, 3)
                successCount++
            } catch (e: Exception) {
                println("恢复失败: ${job.id}, ${e.message}")
                failCount++
            }
        }
        
        return mapOf(
            "total" to deadLetterJobs.size,
            "success" to successCount,
            "failed" to failCount
        )
    }
}

示例4：REST API

import org.flowable.engine.ManagementService
import org.springframework.web.bind.annotation.*

@RestController
@RequestMapping("/api/dead-letter-jobs")
class DeadLetterJobController(
    private val managementService: ManagementService
) {
    
    @GetMapping
    fun listDeadLetterJobs(): List<Map<String, Any>> {
        val jobs = managementService.createDeadLetterJobQuery()
            .list()
        
        return jobs.map { job ->
            mapOf(
                "jobId" to job.id,
                "processInstanceId" to job.processInstanceId,
                "exceptionMessage" to job.exceptionMessage
            )
        }
    }
    
    @PostMapping("/{jobId}/recover")
    fun recoverJob(@PathVariable jobId: String): Map<String, Any> {
        return try {
            managementService.moveDeadLetterJobToExecutableJob(jobId, 3)
            mapOf("success" to true, "message" to "作业已恢复")
        } catch (e: Exception) {
            mapOf("success" to false, "message" to e.message)
        }
    }
}

注意事项

1. 死信作业原因

• 异常未捕获导致作业失败
• 外部服务不可用
• 配置错误或数据问题

2. 处理策略

• 修复问题后重试
• 删除无法恢复的作业
• 记录日志用于分析

3. 监控告警

• 建议设置自动告警
• 及时发现和处理问题

相关 API

• ManagementService.createDeadLetterJobQuery() - 查询死信作业
• ManagementService.moveDeadLetterJobToExecutableJob() - 恢复作业
• ManagementService.deleteDeadLetterJob() - 删除死信作业
• ManagementService.getDeadLetterJobExceptionStacktrace() - 获取异常堆栈

本文档说明

• 基于 Flowable 7.1.0 版本编写
• 所有示例均可直接在 Spring Boot + Kotlin 项目中使用