Skip to content

Commit e40c20a

Browse files
v-kkhuangv-kkhuang
committed
#AI commit# 开发阶段：任务历史新增引擎版本筛选功能
1 parent f84e27f commit e40c20a

File tree

11 files changed

+1511
-18
lines changed

11 files changed

+1511
-18
lines changed

‎docs/dev-1.19.0-webank/design/job-history-engine-version-filter_设计.md‎

Lines changed: 255 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,255 @@
1+
# 任务历史新增引擎版本展示 - 设计文档
2+
3+
## 文档信息
4+
5+
| 项目 | 内容 |
6+
|-----|------|
7+
| 设计名称 | 任务历史新增引擎版本展示 |
8+
| 需求类型 | 功能增强（ENHANCE） |
9+
| 优先级 | P2（重要） |
10+
| 预估工作量 | 2-3人天 |
11+
| 目标版本 | dev-1.19.0-webank |
12+
| 创建日期 | 2026-02-09 |
13+
| 文档状态 | 已完成 |
14+
15+
---
16+
17+
## 📋 执行摘要
18+
19+
### 设计目标
20+
为JobHistory模块的list接口增加引擎版本筛选能力，支持精确匹配和模糊匹配。
21+
22+
### 核心决策
23+
1. **参数扩展**: 添加可选参数engineVersion，保持向后兼容
24+
2. **数据查询**: 基于labels字段JSON内容进行LIKE匹配
25+
3. **版本匹配**: 支持精确（2.4.3）和模糊（2.4、3）匹配
26+
4. **参数校验**: Controller层校验engineVersion必须与engineType一起使用
27+
28+
### 兼容性策略
29+
- 接口兼容：engineVersion为可选参数
30+
- 数据兼容：基于现有labels字段
31+
- 行为兼容：不修改现有engineType筛选逻辑
32+
33+
---
34+
35+
## 一、代码改动清单
36+
37+
### 1.1 Controller层
38+
39+
**文件**: `QueryRestfulApi.java`
40+
41+
**改动1**: list方法添加engineVersion参数
42+
```java
43+
@RequestParam(value = "engineVersion", required = false) String engineVersion
44+
```
45+
46+
**改动2**: 参数校验
47+
```java
48+
if (StringUtils.isNotBlank(engineVersion) && StringUtils.isBlank(runType)) {
49+
return Message.error("engineVersion参数必须与engineType参数一起使用");
50+
}
51+
```
52+
53+
**改动3**: 传递参数到Service层
54+
```java
55+
queryTasks = getJobhistoryList(..., runType, engineVersion);
56+
```
57+
58+
### 1.2 Service层
59+
60+
**文件**: `JobHistoryQueryService.java`
61+
62+
**改动**: 接口方法添加engineVersion参数
63+
```java
64+
List<JobHistory> search(..., String runType, String engineVersion, ...);
65+
```
66+
67+
**文件**: `JobHistoryQueryServiceImpl.java`
68+
69+
**改动**: 实现类传递参数到Mapper
70+
```java
71+
@Override
72+
public List<JobHistory> search(..., String runType, String engineVersion, ...) {
73+
return jobHistoryMapper.search(..., runType, engineVersion, ...);
74+
}
75+
```
76+
77+
### 1.3 Mapper层
78+
79+
**文件**: `JobHistoryMapper.java`
80+
81+
**改动**: 接口方法添加@Param注解
82+
```java
83+
List<JobHistory> search(
84+
...,
85+
@Param("runType") String runType,
86+
@Param("engineVersion") String engineVersion,
87+
...
88+
);
89+
```
90+
91+
**文件**: `JobHistoryMapper.xml`
92+
93+
**改动**: 添加动态SQL条件
94+
```xml
95+
<if test="engineVersion != null and engineVersion != ''">
96+
AND labels LIKE CONCAT('%"engineType":"', #{runType}, '-', #{engineVersion}, '%')
97+
</if>
98+
```
99+
100+
---
101+
102+
## 二、时序图
103+
104+
```
105+
用户 -> 前端: 选择引擎类型和版本
106+
前端 -> QueryRestfulApi: GET /jobhistory/list?engineType=spark&engineVersion=2.4.3
107+
QueryRestfulApi -> QueryRestfulApi: 参数校验
108+
QueryRestfulApi -> JobHistoryQueryService: search(..., "spark", "2.4.3", ...)
109+
JobHistoryQueryService -> JobHistoryMapper: search(..., "spark", "2.4.3", ...)
110+
JobHistoryMapper -> Database: SELECT * WHERE labels LIKE '%"engineType":"spark-2.4.3%'
111+
Database -> JobHistoryMapper: List<JobHistory>
112+
JobHistoryMapper -> JobHistoryQueryService: List<JobHistory>
113+
JobHistoryQueryService -> QueryRestfulApi: List<JobHistory>
114+
QueryRestfulApi -> 前端: Message.ok().data("tasks", vos)
115+
前端 -> 用户: 显示筛选结果
116+
```
117+
118+
---
119+
120+
## 三、SQL设计
121+
122+
### 3.1 版本匹配SQL
123+
124+
**精确匹配** (engineVersion=2.4.3):
125+
```sql
126+
SELECT * FROM linkis_ps_job_history
127+
WHERE engine_type = 'spark'
128+
AND labels LIKE '%"engineType":"spark-2.4.3%'
129+
```
130+
131+
**模糊匹配-次版本** (engineVersion=2.4):
132+
```sql
133+
SELECT * FROM linkis_ps_job_history
134+
WHERE engine_type = 'spark'
135+
AND labels LIKE '%"engineType":"spark-2.4%'
136+
```
137+
138+
**模糊匹配-主版本** (engineVersion=3):
139+
```sql
140+
SELECT * FROM linkis_ps_job_history
141+
WHERE engine_type = 'spark'
142+
AND labels LIKE '%"engineType":"spark-3%'
143+
```
144+
145+
### 3.2 动态SQL实现
146+
147+
```xml
148+
<select id="search" resultMap="JobHistoryMap">
149+
SELECT * FROM linkis_ps_job_history
150+
WHERE 1=1
151+
<if test="runType != null and runType != ''">
152+
AND engine_type = #{runType}
153+
</if>
154+
<if test="engineVersion != null and engineVersion != ''">
155+
AND labels LIKE CONCAT('%"engineType":"', #{runType}, '-', #{engineVersion}, '%')
156+
</if>
157+
<!-- 其他现有条件 -->
158+
</select>
159+
```
160+
161+
---
162+
163+
## 四、兼容性分析
164+
165+
### 4.1 接口兼容性
166+
167+
| 场景 | 参数 | 行为 | 兼容性 |
168+
|-----|------|------|--------|
169+
| 现有调用 | 不传engineVersion | 查询逻辑不变 | ✅ 完全兼容 |
170+
| 新增调用 | 传engineVersion | 增加版本筛选 | ✅ 功能增强 |
171+
| 错误调用 | 只传engineVersion | 返回异常提示 | ✅ 明确提示 |
172+
173+
### 4.2 数据兼容性
174+
175+
- 基于现有labels字段，无需数据迁移
176+
- labels字段格式固定：`{"engineType":"spark-2.4.3"}`
177+
- 不修改现有数据结构
178+
179+
### 4.3 性能影响
180+
181+
| 影响项 | 评估 | 说明 |
182+
|-------|------|------|
183+
| 查询性能 | 中等影响 | LIKE查询，暂不添加索引 |
184+
| 接口响应时间 | 微小增加 | 增加一个可选条件 |
185+
| 数据库负载 | 无明显影响 | 查询条件增加，但数据量可控 |
186+
187+
---
188+
189+
## 五、测试策略
190+
191+
### 5.1 单元测试
192+
193+
**测试类**: `QueryRestfulApiTest.java`
194+
195+
**测试用例**:
196+
1. testListWithEngineVersion_Precise() - 精确版本匹配
197+
2. testListWithEngineVersion_Fuzzy() - 模糊版本匹配
198+
3. testListWithoutEngineVersion() - 兼容性测试
199+
4. testListWithEngineVersionOnly() - 参数校验测试
200+
201+
### 5.2 集成测试
202+
203+
**测试场景**:
204+
1. 端到端测试：前端 -> Controller -> Service -> Mapper -> Database
205+
2. 性能测试：大数据量下的查询性能
206+
3. 兼容性测试：现有调用方不受影响
207+
208+
---
209+
210+
## 六、部署方案
211+
212+
### 6.1 部署步骤
213+
214+
1. 代码合并到dev-1.19.0-webank分支
215+
2. 执行单元测试和集成测试
216+
3. 部署到测试环境验证
217+
4. 部署到生产环境
218+
219+
### 6.2 回滚方案
220+
221+
- 代码回滚：回退到上一个版本
222+
- 数据回滚：无需数据回滚（未修改数据结构）
223+
- 接口回滚：移除engineVersion参数
224+
225+
---
226+
227+
## 七、监控指标
228+
229+
| 指标 | 监控方式 | 告警阈值 |
230+
|-----|---------|---------|
231+
| 接口响应时间 | APM监控 | >2秒 |
232+
| 查询错误率 | 日志监控 | >1% |
233+
| 参数校验失败次数 | 日志统计 | >100次/小时 |
234+
235+
---
236+
237+
## 八、附录
238+
239+
### 8.1 相关文档
240+
241+
- 需求文档：`docs/dev-1.19.0-webank/requirements/job-history-engine-version-filter_需求.md`
242+
- Feature文件：`docs/dev-1.19.0-webank/features/job-history-engine-version-filter.feature`
243+
244+
### 8.2 变更历史
245+
246+
| 版本 | 日期 | 变更内容 | 变更人 |
247+
|-----|------|---------|--------|
248+
| 1.0 | 2026-02-09 | 初始版本 | des-enhance-feature |
249+
250+
---
251+
252+
**文档生成信息**:
253+
- 生成时间：2026-02-09T03:45:00Z
254+
- 生成工具：des-enhance-feature v3.3
255+
- 设计复杂度：中等

‎docs/dev-1.19.0-webank/features/job-history-engine-version-filter.feature‎

Lines changed: 106 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,106 @@
1+
# language: zh-CN
2+
功能: 任务历史新增引擎版本展示
3+
4+
作为 Linkis系统用户
5+
我想要 在任务历史列表中按引擎版本筛选任务
6+
以便于 可以快速找到特定版本引擎执行的任务，便于问题排查和版本对比
7+
8+
背景:
9+
假如 系统中存在以下任务历史数据
10+
| 任务ID | 引擎类型 | 引擎版本 | labels字段 |
11+
| 1001 | spark | 2.4.3 | {"codeType":"sql","userCreator":"hadoop-IDE","engineType":"spark-2.4.3"} |
12+
| 1002 | spark | 2.4.0 | {"codeType":"sql","userCreator":"hadoop-IDE","engineType":"spark-2.4.0"} |
13+
| 1003 | spark | 3.4.4 | {"codeType":"sql","userCreator":"hadoop-IDE","engineType":"spark-3.4.4"} |
14+
| 1004 | spark | 3.0.0 | {"codeType":"sql","userCreator":"hadoop-IDE","engineType":"spark-3.0.0"} |
15+
| 1005 | hive | 2.3.3 | {"codeType":"sql","userCreator":"hadoop-IDE","engineType":"hive-2.3.3"} |
16+
17+
场景: 精确版本筛选
18+
当 用户请求任务历史列表，参数为
19+
| 参数名 | 参数值 |
20+
| engineType | spark |
21+
| engineVersion | 2.4.3 |
22+
那么 系统应该返回以下任务
23+
| 任务ID | 引擎类型 | 引擎版本 |
24+
| 1001 | spark | 2.4.3 |
25+
并且 返回的任务数量应该是 1
26+
27+
场景: 模糊版本筛选-次版本
28+
当 用户请求任务历史列表，参数为
29+
| 参数名 | 参数值 |
30+
| engineType | spark |
31+
| engineVersion | 2.4 |
32+
那么 系统应该返回以下任务
33+
| 任务ID | 引擎类型 | 引擎版本 |
34+
| 1001 | spark | 2.4.3 |
35+
| 1002 | spark | 2.4.0 |
36+
并且 返回的任务数量应该是 2
37+
38+
场景: 模糊版本筛选-主版本
39+
当 用户请求任务历史列表，参数为
40+
| 参数名 | 参数值 |
41+
| engineType | spark |
42+
| engineVersion | 3 |
43+
那么 系统应该返回以下任务
44+
| 任务ID | 引擎类型 | 引擎版本 |
45+
| 1003 | spark | 3.4.4 |
46+
| 1004 | spark | 3.0.0 |
47+
并且 返回的任务数量应该是 2
48+
49+
场景: 无版本参数-兼容性测试
50+
当 用户请求任务历史列表，参数为
51+
| 参数名 | 参数值 |
52+
| engineType | spark |
53+
| engineVersion | |
54+
那么 系统应该返回所有spark引擎的任务
55+
| 任务ID | 引擎类型 | 引擎版本 |
56+
| 1001 | spark | 2.4.3 |
57+
| 1002 | spark | 2.4.0 |
58+
| 1003 | spark | 3.4.4 |
59+
| 1004 | spark | 3.0.0 |
60+
并且 返回的任务数量应该是 4
61+
并且 查询逻辑应该与原有逻辑完全一致
62+
63+
场景: 参数校验-只传版本不传类型
64+
当 用户请求任务历史列表，参数为
65+
| 参数名 | 参数值 |
66+
| engineType | |
67+
| engineVersion | 2.4.3 |
68+
那么 系统应该返回异常
69+
并且 异常信息应该是 "engineVersion参数必须与engineType参数一起使用"
70+
并且 HTTP状态码应该是 400
71+
72+
场景: 无效版本参数
73+
当 用户请求任务历史列表，参数为
74+
| 参数名 | 参数值 |
75+
| engineType | spark |
76+
| engineVersion | invalid |
77+
那么 系统应该返回空列表
78+
并且 返回的任务数量应该是 0
79+
80+
场景: 跨引擎类型筛选
81+
当 用户请求任务历史列表，参数为
82+
| 参数名 | 参数值 |
83+
| engineType | hive |
84+
| engineVersion | 2.3.3 |
85+
那么 系统应该返回以下任务
86+
| 任务ID | 引擎类型 | 引擎版本 |
87+
| 1005 | hive | 2.3.3 |
88+
并且 返回的任务数量应该是 1
89+
90+
场景大纲: 版本匹配逻辑验证
91+
当 用户请求任务历史列表，参数为
92+
| 参数名 | 参数值 |
93+
| engineType | <引擎类型> |
94+
| engineVersion | <引擎版本> |
95+
那么 系统应该执行SQL查询，条件为
96+
"""
97+
labels LIKE CONCAT('%"engineType":"', <引擎类型>, '-', <引擎版本>, '%')
98+
"""
99+
并且 返回的任务数量应该是 <预期数量>
100+
101+
例子:
102+
| 引擎类型 | 引擎版本 | 预期数量 |
103+
| spark | 2.4.3 | 1 |
104+
| spark | 2.4 | 2 |
105+
| spark | 3 | 2 |
106+
| hive | 2.3.3 | 1 |

0 commit comments

Comments
 (0)