# tzy-push-helper **Repository Path**: ljq1307/tzy-push-helper ## Basic Information - **Project Name**: tzy-push-helper - **Description**: No description available - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2025-03-30 - **Last Updated**: 2025-08-09 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # TZY Push Helper TZY Push Helper 是一个数据推送助手项目，主要用于从简道云等第三方平台获取数据，并通过可配置的推送任务将数据推送到指定的目标系统。该项目具备完整的任务管理、数据缓存、消息队列、日志记录和监控功能。 ## 功能特性 1. **任务管理**：创建、配置和管理数据推送任务 2. **数据获取**：从简道云获取表单数据并缓存到Redis 3. **数据筛选**：支持按条件筛选数据 4. **消息队列**：使用Kafka实现异步消息处理，支持多优先级通道 5. **重试机制**：推送失败时自动重试，确保数据可靠传输 6. **日志记录**：完整记录推送过程和结果 7. **实时监控**：监控Kafka队列状态和任务进度 ## 技术架构 ### 核心技术栈 - **后端框架**：Spring Boot 3.2.5 - **数据库**：MySQL 8.0 + MyBatis-Plus - **缓存**：Redis - **消息队列**：Apache Kafka - **JSON处理**：FastJSON2 - **HTTP客户端**：OkHttp、Apache HttpClient ### 系统架构图 ``` ┌─────────────────┐ ┌──────────────┐ ┌──────────────┐ │ 简道云API │───▶│ TZY Push │───▶│ 目标系统 │ └─────────────────┘ │ Helper │ └──────────────┘ │ │ ▲ ┌─────────────────┐ │ ┌─────────┐ │ ┌──────────────┐ │ 用户界面 │────▶│ │任务管理 │ │────▶│ Kafka队列 │ └─────────────────┘ │ ├─────────┤ │ └──────────────┘ │ │数据获取 │ │ ▼ ┌─────────────────┐ │ ├─────────┤ │ ┌──────────────┐ │ 配置管理 │────▶│ │数据推送 │ │◀───▶│ 消费者处理 │ └─────────────────┘ │ ├─────────┤ │ └──────────────┘ │ │日志记录 │ │ ▲ ┌─────────────────┐ │ ├─────────┤ │ ┌──────────────┐ │ 监控系统 │◀───▶│ │队列监控 │ │◀───▶│ 重试机制 │ └─────────────────┘ │ └─────────┘ │ └──────────────┘ └──────────────┘ │ ┌──────────────┐ │ Redis缓存 │ └──────────────┘ ``` ### 消息队列设计 项目采用6个Kafka主题实现多优先级消息处理： 1. **高速队列**（最高优先级）： - `tzy-express-topic-1` - `tzy-express-topic-2` 2. **快速队列**（高优先级）： - `tzy-high-priority-topic-1` - `tzy-high-priority-topic-2` 3. **普通队列**（一般优先级）： - `tzy-normal-priority-topic-1` - `tzy-normal-priority-topic-2` ## 操作流程 ### 1. 环境准备 确保已安装以下软件： - JDK 17 - Maven 3.x - MySQL 8.0 - Redis - Kafka ### 2. 数据库初始化 执行以下SQL脚本创建所需表： - [src/main/resources/db/task.sql](src/main/resources/db/task.sql) - [src/main/resources/db/push_log.sql](src/main/resources/db/push_log.sql) ### 3. 配置文件设置 编辑 [src/main/resources/bootstrap.yaml](src/main/resources/bootstrap.yaml) 文件，配置以下信息： - 数据库连接信息 - Redis连接信息 - Kafka连接信息 - 简道云API密钥、应用ID和表单ID - 推送目标URL ### 4. 编译和运行 ```bash # 克隆项目 git clone <项目地址> # 进入项目目录 cd tzy-push-helper # 编译项目 mvn clean package # 运行项目 mvn spring-boot:run # 或者 java -jar target/tzy-push-helper-0.0.1-SNAPSHOT.jar ``` ### 5. 使用步骤 #### 5.1 创建推送任务 发送POST请求到 `/api/task` 创建任务： ```bash curl -X POST http://localhost:8080/api/task \ -H "Content-Type: application/json" \ -d '{ "taskName": "示例推送任务", "appId": "your_app_id", "entryId": "your_entry_id", "targetUrl": "http://target-system/api/receive", "maxRetries": 3, "creator": "admin", "description": "这是一个示例推送任务" }' ``` #### 5.2 设置筛选条件（可选） 发送PUT请求到 `/api/task/{taskId}/filter` 设置筛选条件： ```bash curl -X PUT http://localhost:8080/api/task/1/filter \ -H "Content-Type: application/json" \ -d '{ "rel": "and", "cond": [ { "field": "field1", "method": "equal", "value": "value1" } ] }' ``` #### 5.3 获取数据并存储到Redis 发送GET请求到 `/api/jdy/data/task/{taskId}/fetch-and-store` 获取数据： ```bash curl -X GET "http://localhost:8080/api/jdy/data/task/1/fetch-and-store?page=1&size=100" ``` #### 5.4 选择需要推送的数据 发送POST请求到 `/api/jdy/data/task/{taskId}` 添加数据到任务： ```bash curl -X POST http://localhost:8080/api/jdy/data/task/1 \ -H "Content-Type: application/json" \ -d '["data_id_1", "data_id_2", "data_id_3"]' ``` #### 5.5 推送数据到Kafka队列 发送POST请求到 `/api/jdy/data/push-from-redis` 推送数据： ```bash curl -X POST http://localhost:8080/api/jdy/data/push-from-redis?priority=high&taskId=1 \ -H "Content-Type: application/json" \ -d '["data_id_1", "data_id_2"]' ``` #### 5.6 查看推送结果 发送GET请求到 `/api/push-log/page` 查看推送日志： ```bash curl -X GET "http://localhost:8080/api/push-log/page?page=1&size=10" ``` #### 5.7 监控队列状态 发送GET请求到 `/api/kafka-monitor/queue-counts` 查看队列状态： ```bash curl -X GET "http://localhost:8080/api/kafka-monitor/queue-counts" ``` ## 技术实现细节 ### 1. 任务管理系统 任务管理系统基于MyBatis-Plus实现，包含以下核心组件： - **Task实体类**：定义任务属性，包括任务名称、应用ID、表单ID、目标URL、重试次数等 - **TaskMapper**：数据访问接口 - **TaskService**：业务逻辑处理 - **TaskController**：RESTful API接口 ### 2. 数据获取与缓存 数据获取模块通过简道云API获取表单数据，并使用Redis进行缓存： - **JdyUtil**：简道云API工具类，封装数据获取逻辑 - **RedisDataService**：Redis数据服务，提供数据缓存和检索功能 - 支持分页获取大量数据 - 使用data_id作为Redis键，实现O(1)时间复杂度的数据查找 ### 3. 消息队列处理 消息队列模块使用Kafka实现异步消息处理： - **KafkaProducerService**：消息生产者，支持6个主题的消息发送 - **KafkaConsumerService**：消息消费者，处理推送任务 - **KafkaMonitorService**：队列监控服务，实时监控各主题消息数量 - 支持负载均衡，在同一优先级的多个主题间随机分配消息 ### 4. 推送服务与重试机制 推送服务模块负责实际的数据推送和重试处理： - **DataPushService**：数据推送服务，支持HTTP请求和重试机制 - 重试次数可配置，默认3次重试 - 逐步增加重试间隔时间 - 完整的错误处理和日志记录 ### 5. 日志记录系统 日志记录系统完整记录推送过程和结果： - **PushLog实体类**：定义日志属性 - **PushLogMapper/Service/Controller**：完整的MyBatis-Plus结构 - 自动记录推送时间、结果、错误信息等 ## API接口文档 ### 任务管理接口 - `POST /api/task` - 创建任务 - `PUT /api/task/{id}` - 更新任务 - `DELETE /api/task/{id}` - 删除任务 - `GET /api/task/{id}` - 获取任务详情 - `GET /api/task/page` - 分页查询任务列表 - `PUT /api/task/{id}/status` - 更新任务状态 - `PUT /api/task/{id}/progress` - 更新任务进度 - `PUT /api/task/{id}/filter` - 设置任务筛选条件 ### 数据处理接口 - `GET /api/jdy/data/task/{taskId}/fetch-and-store` - 根据任务获取数据并存储 - `POST /api/jdy/data/task/{taskId}` - 为任务添加数据 - `POST /api/jdy/data/task/{taskId}/push-to-queue` - 推送任务数据到队列 - `POST /api/jdy/data/push-from-redis` - 从Redis推送数据 - `GET /api/jdy/data/{dataId}` - 获取单条数据 - `POST /api/jdy/data/batch-get` - 批量获取数据 ### 日志查询接口 - `GET /api/push-log/page` - 分页查询推送日志 - `GET /api/push-log/{id}` - 根据ID查询推送日志 - `GET /api/push-log/data/{dataId}` - 根据数据ID查询推送日志 - `GET /api/push-log/result/{pushResult}` - 根据推送结果查询推送日志 ### 队列监控接口 - `GET /api/kafka-monitor/queue-counts` - 获取所有队列消息数量 - `GET /api/kafka-monitor/express-count` - 获取高速队列消息数量 - `GET /api/kafka-monitor/high-priority-count` - 获取高优先级队列消息数量 - `GET /api/kafka-monitor/normal-priority-count` - 获取普通优先级队列消息数量 - `GET /api/kafka-monitor/queue-count/{priorityType}` - 根据优先级类型获取队列消息数量 ## 项目结构 ``` src/main/java/com/zjssnf/tzypushhelper/ ├── TzyPushHelperApplication.java # Spring Boot启动类 ├── config/ # 配置类 │ ├── KafkaConfig.java # Kafka配置 │ └── MybatisPlusConfig.java # MyBatis-Plus配置 ├── controller/ # 控制器层 │ ├── DataReceiverController.java # 数据接收控制器 │ ├── JdyDataController.java # 简道云数据控制器 │ ├── KafkaMonitorController.java # Kafka监控控制器 │ ├── PushLogController.java # 推送日志控制器 │ ├── TaskController.java # 任务控制器 │ └── TaskDataController.java # 任务数据控制器 ├── domain/ # 数据模型 │ ├── PushLog.java # 推送日志实体 │ ├── Task.java # 任务实体 │ └── TaskData.java # 任务数据实体 ├── mapper/ # 数据访问层 │ ├── PushLogMapper.java # 推送日志Mapper │ ├── TaskMapper.java # 任务Mapper │ └── TaskDataMapper.java # 任务数据Mapper ├── service/ # 服务层 │ ├── DataPushService.java # 数据推送服务 │ ├── KafkaConsumerService.java # Kafka消费者服务 │ ├── KafkaMonitorService.java # Kafka监控服务 │ ├── KafkaProducerService.java # Kafka生产者服务 │ ├── PushLogService.java # 推送日志服务 │ ├── RedisDataService.java # Redis数据服务 │ ├── TaskDataService.java # 任务数据服务 │ ├── TaskService.java # 任务服务 │ └── impl/ # 服务实现 │ ├── PushLogServiceImpl.java # 推送日志服务实现 │ ├── TaskDataServiceImpl.java # 任务数据服务实现 │ └── TaskServiceImpl.java # 任务服务实现 └── util/ # 工具类 ├── HttpUtils.java # HTTP工具类 └── JdyUtil.java # 简道云工具类 ``` ## 扩展与维护 ### 扩展建议 1. **增加更多数据源支持**：除了简道云，还可以支持其他数据源 2. **增强筛选功能**：提供更多筛选条件和组合方式 3. **完善监控告警**：增加邮件、短信等告警方式 4. **优化性能**：针对大数据量场景进行性能优化 5. **增强安全性**：增加API鉴权、数据加密等功能 ### 维护要点 1. **定期清理Redis缓存**：避免缓存数据过多占用内存 2. **监控Kafka队列**：确保消息处理及时，避免消息积压 3. **备份数据库**：定期备份任务和日志数据 4. **更新依赖版本**：定期检查并更新项目依赖 5. **监控系统日志**：及时发现和处理异常情况 ## 贡献指南 欢迎提交Issue和Pull Request来帮助改进项目。 ## 许可证 [MIT License](LICENSE)