Skip to content

Commit dfcd9d7

Browse files
SunPengWanSunPengWan
committed
添加1.22.0版本文档 #AI commit#
1 parent eb8ceba commit dfcd9d7

10 files changed

Lines changed: 3952 additions & 0 deletions

‎docs/1.22.0/design/ITSM接口字段适配_设计.md‎

Lines changed: 281 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,281 @@
1+
# ITSM接口字段适配_设计
2+
3+
## 一、设计概述
4+
5+
### 1.1 设计目标
6+
适配ITSM系统版本升级后的请求报文，确保：
7+
- 接口能够正常接收并解析包含新字段的请求报文
8+
- 对于未知字段采用静默忽略策略，不抛出异常
9+
- 保持向后兼容性，不影响现有功能正常运行
10+
11+
### 1.2 设计范围
12+
- **dss-framework-workspace-server**：ItsmRequest类添加Jackson注解
13+
- **dss-scriptis-server-webank**：ItsmRequest类添加Jackson注解
14+
15+
### 1.3 影响接口
16+
| 接口 | 路径 | 说明 |
17+
|-----|------|------|
18+
| updateWorkspace | /dss/framework/workspace/updateWorkspace | 工作空间新建/修改 |
19+
| addProjectAndOrchestratorWhite | /dss/framework/orchestrator/addOrchestratorWhite | 添加工作流白名单 |
20+
| addUserProxy | /dss/scriptis/proxy/addUserProxy | 添加代理用户 |
21+
22+
## 二、现状分析
23+
24+
### 2.1 ItsmRequest类现状
25+
26+
系统中存在两处`ItsmRequest`定义：
27+
28+
#### 2.1.1 dss-framework-workspace-server模块
29+
**位置**：`dss-framework/dss-framework-workspace-server/src/main/java/com/webank/wedatasphere/dss/framework/workspace/bean/itsm/ItsmRequest.java`
30+
31+
**现有字段**：
32+
| 字段名 | 类型 | 说明 |
33+
|-------|------|------|
34+
| createDate | String | 创建日期 |
35+
| createUser | String | 创建用户 |
36+
| data | String | 数据内容（JSON字符串） |
37+
| externalId | String | 外部ID |
38+
| flowId | String | 流程ID |
39+
| operateUser | String | 操作用户 |
40+
| requestTitle | String | 请求标题 |
41+
| style | String | 样式 |
42+
| taskId | String | 任务ID |
43+
| formId | String | 表单ID |
44+
45+
#### 2.1.2 dss-scriptis-server-webank模块
46+
**位置**：`dss-apps/dss-scriptis-server-webank/src/main/java/com/webank/wedatasphere/dss/scriptis/bean/ItsmRequest.java`
47+
48+
**现有字段**：
49+
| 字段名 | 类型 | 说明 |
50+
|-------|------|------|
51+
| createDate | String | 创建日期 |
52+
| createUser | String | 创建用户 |
53+
| data | String | 数据内容（JSON字符串） |
54+
| externalId | String | 外部ID |
55+
| flowId | String | 流程ID |
56+
| operateUser | String | 操作用户 |
57+
| requestTitle | String | 请求标题 |
58+
| style | String | 样式 |
59+
| taskId | String | 任务ID |
60+
| expireTime | String | 过期时间（该模块特有） |
61+
62+
### 2.2 反序列化方式
63+
Spring MVC 使用 Jackson 进行 JSON 反序列化，默认情况下遇到未知字段会抛出 `UnrecognizedPropertyException` 异常。
64+
65+
### 2.3 问题分析
66+
- Jackson 默认不允许未知字段，会导致反序列化失败
67+
- 接口调用会因为未知字段而报错
68+
69+
## 三、详细设计
70+
71+
### 3.1 设计方案
72+
73+
采用 **Jackson 注解方案**，在 `ItsmRequest` 类上添加 `@JsonIgnoreProperties(ignoreUnknown = true)` 注解。
74+
75+
#### 3.1.1 方案优势
76+
- 实现简单，改动最小
77+
- 无需新增文件
78+
- 无需修改其他代码
79+
- Spring 原生支持，无需额外配置
80+
81+
### 3.2 ItsmRequest类改造
82+
83+
#### 3.2.1 dss-framework-workspace-server模块
84+
85+
**文件**：`dss-framework/dss-framework-workspace-server/src/main/java/com/webank/wedatasphere/dss/framework/workspace/bean/itsm/ItsmRequest.java`
86+
87+
**修改内容**：
88+
```java
89+
package com.webank.wedatasphere.dss.framework.workspace.bean.itsm;
90+
91+
import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
92+
import com.google.gson.Gson;
93+
import com.google.gson.JsonArray;
94+
import com.google.gson.JsonObject;
95+
import com.google.gson.reflect.TypeToken;
96+
import org.springframework.util.StringUtils;
97+
98+
import java.lang.reflect.Type;
99+
import java.util.Collections;
100+
import java.util.List;
101+
import java.util.Map;
102+
103+
@JsonIgnoreProperties(ignoreUnknown = true)
104+
public class ItsmRequest {
105+
// ... 现有字段保持不变 ...
106+
}
107+
```
108+
109+
#### 3.2.2 dss-scriptis-server-webank模块
110+
111+
**文件**：`dss-apps/dss-scriptis-server-webank/src/main/java/com/webank/wedatasphere/dss/scriptis/bean/ItsmRequest.java`
112+
113+
**修改内容**：
114+
```java
115+
package com.webank.wedatasphere.dss.scriptis.bean;
116+
117+
import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
118+
import com.google.gson.Gson;
119+
import com.google.gson.JsonArray;
120+
import com.google.gson.JsonObject;
121+
import com.google.gson.JsonParser;
122+
import com.google.gson.reflect.TypeToken;
123+
import org.springframework.util.StringUtils;
124+
125+
import java.lang.reflect.Type;
126+
import java.util.ArrayList;
127+
import java.util.Collections;
128+
import java.util.List;
129+
import java.util.Map;
130+
131+
/** itsm请求我们的入参
132+
* Author: xlinliu
133+
* Date: 2024/5/22
134+
*/
135+
@JsonIgnoreProperties(ignoreUnknown = true)
136+
public class ItsmRequest {
137+
// ... 现有字段保持不变 ...
138+
}
139+
```
140+
141+
### 3.3 注解说明
142+
143+
`@JsonIgnoreProperties(ignoreUnknown = true)` 注解作用：
144+
- 告诉 Jackson 在反序列化时忽略 JSON 中存在但 Java 类中不存在的属性
145+
- 不会抛出 `UnrecognizedPropertyException` 异常
146+
- 静默忽略未知字段，不影响业务逻辑
147+
148+
## 四、数据模型变更
149+
150+
### 4.1 ItsmRequest类变更
151+
152+
#### 变更前
153+
```java
154+
public class ItsmRequest {
155+
private String createDate;
156+
private String createUser;
157+
// ... 其他字段 ...
158+
}
159+
```
160+
161+
#### 变更后
162+
```java
163+
import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
164+
165+
@JsonIgnoreProperties(ignoreUnknown = true)
166+
public class ItsmRequest {
167+
private String createDate;
168+
private String createUser;
169+
// ... 其他字段 ...
170+
}
171+
```
172+
173+
### 4.2 无数据库变更
174+
- 本需求不涉及数据库表结构变更
175+
- 无需执行DDL脚本
176+
177+
## 五、测试设计
178+
179+
### 5.1 单元测试
180+
181+
#### 5.1.1 测试用例1：正常请求（无未知字段）
182+
```java
183+
@Test
184+
public void testDeserializeWithKnownFields() throws Exception {
185+
String json = "{\"createUser\":\"admin\",\"data\":\"{\\\"dataList\\\":[]}\",\"externalId\":\"123\"}";
186+
ObjectMapper mapper = new ObjectMapper();
187+
ItsmRequest request = mapper.readValue(json, ItsmRequest.class);
188+
189+
assertEquals("admin", request.getCreateUser());
190+
assertEquals("123", request.getExternalId());
191+
}
192+
```
193+
194+
#### 5.1.2 测试用例2：包含未知字段
195+
```java
196+
@Test
197+
public void testDeserializeWithUnknownFields() throws Exception {
198+
String json = "{\"createUser\":\"admin\",\"newField\":\"newValue\",\"externalId\":\"123\"}";
199+
ObjectMapper mapper = new ObjectMapper();
200+
ItsmRequest request = mapper.readValue(json, ItsmRequest.class);
201+
202+
// 正常解析，不抛出异常
203+
assertEquals("admin", request.getCreateUser());
204+
assertEquals("123", request.getExternalId());
205+
}
206+
```
207+
208+
#### 5.1.3 测试用例3：向后兼容性
209+
```java
210+
@Test
211+
public void testBackwardCompatibility() throws Exception {
212+
// 旧版请求格式
213+
String oldJson = "{\"createUser\":\"admin\",\"data\":\"{\\\"dataList\\\":[]}\"}";
214+
ObjectMapper mapper = new ObjectMapper();
215+
ItsmRequest request = mapper.readValue(oldJson, ItsmRequest.class);
216+
217+
// 正常解析，无异常
218+
assertNotNull(request);
219+
assertEquals("admin", request.getCreateUser());
220+
}
221+
```
222+
223+
### 5.2 集成测试
224+
225+
| 测试场景 | 输入 | 预期结果 |
226+
|---------|------|---------|
227+
| 工作空间更新-含新字段 | ITSM请求含新字段 | 正常处理，无异常 |
228+
| 工作空间更新-无新字段 | ITSM请求标准格式 | 正常处理 |
229+
| 白名单添加-含新字段 | ITSM请求含新字段 | 正常处理，无异常 |
230+
| 代理用户添加-含新字段 | ITSM请求含新字段 | 正常处理，无异常 |
231+
232+
## 六、部署方案
233+
234+
### 6.1 部署步骤
235+
1. 编译打包：`mvn clean package -DskipTests`
236+
2. 停止服务：`sh $DSS_HOME/sbin/dss-stop-all.sh`
237+
3. 替换jar包
238+
4. 启动服务：`sh $DSS_HOME/sbin/dss-start-all.sh`
239+
240+
### 6.2 回滚方案
241+
- 保留原jar包备份
242+
- 如有问题，回滚至原版本即可
243+
244+
### 6.3 配置变更
245+
无需配置变更
246+
247+
## 七、风险评估
248+
249+
### 7.1 风险项
250+
| 风险项 | 影响 | 概率 | 应对措施 |
251+
|-------|------|------|---------|
252+
| Jackson注解不生效 | 高 | 低 | Spring默认使用Jackson，注解生效有保障 |
253+
254+
### 7.2 兼容性
255+
- **向后兼容**：完全兼容旧版ITSM请求格式
256+
- **向前兼容**：支持未来新增字段
257+
258+
## 八、附录
259+
260+
### 8.1 相关文件清单
261+
| 模块 | 文件 | 变更类型 |
262+
|-----|------|---------|
263+
| dss-framework-workspace-server | ItsmRequest.java | 添加注解 |
264+
| dss-scriptis-server-webank | ItsmRequest.java | 添加注解 |
265+
266+
### 8.2 预估工时
267+
| 任务 | 工时（人天） |
268+
|-----|------------|
269+
| ItsmRequest类添加注解 | 0.1 |
270+
| 单元测试 | 0.2 |
271+
| 集成测试 | 0.3 |
272+
| 文档更新 | 0.2 |
273+
| **合计** | **0.8** |
274+
275+
---
276+
277+
**文档版本**：v2.0
278+
**创建日期**：2026-04-27
279+
**更新日期**：2026-04-27
280+
**设计负责人**：待定
281+
**需求关联**：[ITSM接口字段适配_需求](../requirements/ITSM接口字段适配_需求.md)

0 commit comments

Comments
 (0)