# job-test-http

**Repository Path**: qinstudy/job-test-http

## Basic Information

- **Project Name**: job-test-http
- **Description**: 分布式定时任务从零实现（对话+流程图+代码示例）
- **Primary Language**: Java
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 2
- **Created**: 2026-03-11
- **Last Updated**: 2026-05-23

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 基于SpringBoot和http/Kafka的分布式定时任务调度系统
com.example.businessmodule.service.TaskRegistrationService.taskDefinitions

com.example.businessmodule.controller.InternalTaskController.executeTask

有5秒的时间间隔。定时任务有几秒的延迟
com.example.schedulercenter.service.SchedulerService.scanAndExecuteTasks

手动触发任务
com.example.schedulercenter.controller.SchedulerController.triggerTask
com.example.schedulercenter.service.SchedulerService.triggerTask

## 项目概述

本项目实现了一个分布式的定时任务调度系统，采用"任务注册+消息驱动"的架构模式。系统由调度中心和业务模块两部分组成，通过Kafka实现任务的注册、调度和执行。

## 系统架构

```
┌─────────────────┐    Kafka     ┌─────────────────┐
│  Scheduler      │ ──────────► │  Business       │
│  Center         │             │  Module         │
│                 │             │                 │
│ - 任务管理      │             │ - 任务注册      │
│ - 调度触发      │             │ - 任务执行      │
│ - 状态监控      │             │ - 结果反馈      │
└─────────────────┘             └─────────────────┘
```

## 核心特性

- **分布式架构**：调度中心与业务模块分离，支持水平扩展
- **消息驱动**：基于Kafka实现异步消息传递
- **注解驱动**：业务模块使用`@ScheduledTask`注解定义任务
- **自动注册**：业务模块启动时自动将任务注册到调度中心
- **统一调度**：调度中心统一管理所有任务的执行时间
- **状态监控**：提供任务执行状态和统计信息的REST API

## 技术栈

- **Spring Boot 2.7.14**：应用框架
- **Spring Kafka**：Kafka集成
- **Spring Data JPA**：数据访问层
- **H2 Database**：嵌入式数据库（演示用）
- **Maven**：项目管理工具
- **Java 11**：开发语言

## 项目结构

```
job-test/
├── scheduler-center/          # 调度中心服务
│   ├── src/main/java/
│   │   └── com/example/schedulercenter/
│   │       ├── entity/       # 实体类
│   │       ├── dto/          # 数据传输对象
│   │       ├── repository/   # 数据访问层
│   │       ├── service/      # 业务服务层
│   │       ├── kafka/        # Kafka消费者
│   │       └── controller/   # REST API控制器
│   └── pom.xml
├── business-module/          # 业务模块服务
│   ├── src/main/java/
│   │   └── com/example/businessmodule/
│   │       ├── annotation/   # 自定义注解
│   │       ├── context/      # 执行上下文
│   │       ├── model/        # 数据模型
│   │       └── service/      # 业务服务层
│   └── pom.xml
└── README.md
```

## 快速开始

### 1. 环境准备

确保已安装以下环境：
- JDK 11+
- Maven 3.6+
- Apache Kafka

启动Kafka：
```bash
# 启动ZooKeeper
bin/zookeeper-server-start.sh config/zookeeper.properties

# 启动Kafka
bin/kafka-server-start.sh config/server.properties
```

### 2. 启动调度中心

```bash
cd scheduler-center
mvn spring-boot:run
```

调度中心将在端口8080启动。

### 3. 启动业务模块

```bash
cd business-module
mvn spring-boot:run
```

业务模块将在端口8081启动。

### 4. 验证系统运行

访问调度中心的REST API：

```bash
# 检查调度中心健康状态
curl http://localhost:8080/api/scheduler/health

# 获取所有任务
curl http://localhost:8080/api/scheduler/tasks

# 获取统计信息
curl http://localhost:8080/api/scheduler/statistics
```

## 使用指南

### 1. 定义定时任务

在业务模块中使用`@ScheduledTask`注解定义任务：

```java
@Service
public class MyTaskService {

    @ScheduledTask(
        taskId = "my-task",
        taskName = "我的定时任务",
        cron = "0 */1 * * * ?",  // 每分钟执行
        description = "这是一个示例任务"
    )
    public String executeMyTask() {
        // 任务逻辑
        return "任务执行完成";
    }
}
```

### 2. Cron表达式格式

系统支持标准的Cron表达式格式：`秒 分 时 日 月 周 [年]`

常用示例：
- `0 0 12 * * ?` - 每天中午12点
- `0 15 10 ? * *` - 每天上午10:15
- `0 */5 * * * ?` - 每5分钟
- `0 0 2 * * ?` - 每天凌晨2点

### 3. REST API接口

调度中心提供以下API接口：

#### 任务管理
- `GET /api/scheduler/tasks` - 获取所有任务
- `GET /api/scheduler/tasks/{taskId}` - 获取特定任务
- `GET /api/scheduler/tasks/service/{serviceName}` - 获取指定服务的任务
- `POST /api/scheduler/tasks/{taskId}/trigger` - 手动触发任务
- `PUT /api/scheduler/tasks/{taskId}/status` - 更新任务状态
- `DELETE /api/scheduler/tasks/{taskId}` - 删除任务

#### 监控统计
- `GET /api/scheduler/statistics` - 获取统计信息
- `GET /api/scheduler/health` - 健康检查

### 4. 任务执行流程

1. **注册阶段**：
   - 业务模块启动时扫描`@ScheduledTask`注解
   - 将任务定义通过Kafka发送到调度中心
   - 调度中心存储任务定义并计算执行时间

2. **调度阶段**：
   - 调度中心定时扫描需要执行的任务
   - 通过Kafka发送任务执行指令
   - 业务模块接收指令并执行对应方法

3. **结果反馈**：
   - 业务模块执行完成后将结果发送回调度中心
   - 调度中心更新任务状态和执行记录
   - 计算任务的下次执行时间

## 扩展配置

### 1. 数据库配置

默认使用H2内存数据库，生产环境建议配置MySQL等数据库：

```yaml
spring:
  datasource:
    url: jdbc:mysql://localhost:3306/scheduler_db
    username: root
    password: password
    driver-class-name: com.mysql.cj.jdbc.Driver
```

### 2. Kafka集群配置

```yaml
spring:
  kafka:
    bootstrap-servers: kafka1:9092,kafka2:9092,kafka3:9092
    producer:
      acks: all
      retries: 3
    consumer:
      group-id: scheduler-group
```

### 3. 调度参数配置

```yaml
scheduler:
  scan:
    interval: 10s  # 任务扫描间隔
  kafka:
    topics:
      task-registration: task-registration
      task-execution: task-execution
      task-result: task-result
```

## 监控和运维

### 1. 日志监控

系统提供详细的执行日志，包括：
- 任务注册信息
- 任务调度日志
- 执行结果记录
- 错误异常信息

### 2. 性能监控

通过统计API可以获取：
- 总任务数量
- 今日执行次数
- 成功/失败统计
- 执行时长统计

### 3. 故障处理

- 任务执行失败会记录详细错误信息
- 支持手动重新触发失败任务
- 调度中心异常不会影响业务模块运行

## 注意事项

1. **任务幂等性**：建议任务方法设计为幂等的，避免重复执行造成问题
2. **异常处理**：任务方法应该妥善处理异常，避免影响调度系统
3. **执行时间**：长时间运行的任务可能会影响调度精度
4. **资源管理**：合理控制并发任务数量，避免系统资源耗尽

## 示例项目

项目包含完整的示例代码，演示了：
- 数据清理任务
- 报表生成任务
- 系统监控任务
- 数据备份任务
- 邮件通知任务

可以直接运行这些示例来了解系统的工作原理。