| name | dto-validation-analyzer |
| description | 分析给定的 JSON 请求数据是否与 Java 后台 DTO 定义吻合,检查字段缺失、字段名不匹配、类型不匹配、必填校验等问题。 |
DTO Validation Analyzer
分析用户提供的 JSON 请求数据是否与 Java 后台 DTO 类定义吻合,找出所有不匹配的问题。
触发条件
当用户提供了一段 JSON 数据和一个 Java DTO 类定义(或文件路径),并要求检查数据是否与 DTO 吻合、能否通过 validation 时,使用本技能。
操作步骤
- 获取 JSON 数据和 Java DTO 定义(用户直接提供或通过文件路径读取)
- 解析 DTO 结构(字段名、类型、注解、嵌套类)
- 按照【分析规则】逐项对比
- 按照【输出格式】生成分析报告
分析规则
1. 字段名匹配
确定 DTO 字段的实际序列化名称,优先级如下:
@JsonProperty("name") 的值
@Schema(name = "name") 的值(仅在框架使用 Schema name 做序列化时)
- Java 字段名本身
重要:对比时使用 DTO 字段的序列化名称(而非 Java 字段名),与 JSON 中的 key 进行匹配。
检查项:
- JSON 中是否存在 DTO 中没有的字段(多余字段)
- DTO 中是否存在 JSON 中没有的字段(缺失字段)
- 字段名是否存在拼写差异(如
teikiBusu vs teikiBunBusu)
2. 必填字段校验
识别以下注解标注的必填字段:
@Required
@NotNull
@NotBlank
@NotEmpty
检查 JSON 中这些字段是否:
- 存在(缺失 → 必定 validation 失败)
- 非 null
- 非空字符串(对于
@NotBlank)
- 非空集合/数组(对于
@NotEmpty)
3. 类型匹配
对比 JSON 中值的类型与 DTO 字段声明的类型:
| DTO Java 类型 | JSON 期望类型 | 常见问题 |
|---|
String | string | 发送了 number 或 boolean |
Integer / Long / int / long | number (整数) | 发送了 string 或小数 |
Double / Float / BigDecimal | number | 发送了 string |
Boolean / boolean | boolean | 发送了 string "true" |
List<T> / Set<T> | array | 发送了单个对象而非数组 |
Date / LocalDateTime 等 | string (日期格式) | 格式不正确 |
注意:Spring 默认的 Jackson 会自动做一些类型转换(如 number → String),但这属于隐式转换,仍应标记为⚠️ 提醒。
4. 格式校验
检查带格式注解的字段值是否符合要求:
@DateFormat("yyyyMM") → 值应匹配 yyyyMM 格式(如 "202603")
@DateFormat("yyyyMMdd") → 值应匹配 yyyyMMdd 格式
@Pattern(regexp = "...") → 值应匹配正则
@TrueNumber → 值应为合法数字(字符串形式时也应为数字字符串)
@Email → 值应为邮箱格式
@Size(min=x, max=y) → 字符串长度或集合大小应在范围内
5. 嵌套对象递归分析
- 如果 DTO 中的字段类型是另一个 DTO 类(如内部类或引用类),递归地对 JSON 中对应的嵌套对象进行同样的分析
- 如果是
List<T> 类型,对数组中的每一个元素进行分析,并在报告中标注是第几个元素出的问题
6. @Valid 级联校验
如果字段或泛型参数上有 @Valid 注解,说明 Spring 会对该嵌套对象/列表元素做级联校验,需要递归检查嵌套结构内的 validation 注解。
输出格式
按照问题严重程度分组输出:
报告结构
## 数据与 DTO 匹配分析报告
### ❌ 必定失败(Validation Error)
> 这些问题会导致请求被后台拒绝
| 级别 | 位置 | 问题 | 说明 |
|------|------|------|------|
| ... | ... | ... | ... |
### ⚠️ 潜在问题(Warning)
> 这些问题可能导致数据丢失或行为异常
| 级别 | 位置 | 问题 | 说明 |
|------|------|------|------|
| ... | ... | ... | ... |
### ℹ️ 信息提示(Info)
> 非必填且未发送的字段,不会导致错误
| 字段 | 说明 |
|------|------|
| ... | ... |
### ✅ 总结
简要概括主要问题和建议修复方向。
严重程度定义
-
❌ 必定失败:
- 缺少
@Required / @NotNull / @NotBlank / @NotEmpty 标注的字段
- 格式不符合
@DateFormat / @Pattern 要求
- 类型完全不兼容(如传 object 给 String 字段)
-
⚠️ 潜在问题:
- JSON 中的字段名在 DTO 中不存在(数据会被忽略/丢失)
- 类型隐式转换(如 number → String,Jackson 可能自动处理但不推荐)
@TrueNumber 字段传了非字符串类型的数字
-
ℹ️ 信息提示:
示例
输入
JSON 数据:
{
"seikyuKikanFrom": "202603",
"seikyuKikanTo": "202603",
"kodokuId": 19,
"kodokuInfo": {
"yusoKbn": "2",
"hinList": [
{
"hinCd": "01",
"kihonBusu": 1,
"teikiBunBusu": 0
}
]
}
}
Java DTO(关键部分):
@Data
public class CalcKdYsPriceReqDto {
@Required
@DateFormat("yyyyMM")
private String seikyuKikanFrom;
@Required
@DateFormat("yyyyMM")
private String targetMonth;
private Integer kodokuId;
@Valid
private KodokuInfo kodokuInfo;
public static class HinItem {
@TrueNumber
@Schema(name = "kihonBusu")
private String kihonBusu;
@TrueNumber
@Schema(name = "teikiBusu")
private String teikiBusu;
}
}
输出
## 数据与 DTO 匹配分析报告
### ❌ 必定失败(Validation Error)
| 级别 | 位置 | 问题 | 说明 |
|------|------|------|------|
| ❌ | `targetMonth` | 缺少必填字段 | 标注了 `@Required` + `@DateFormat("yyyyMM")`,但 JSON 中未提供 |
### ⚠️ 潜在问题(Warning)
| 级别 | 位置 | 问题 | 说明 |
|------|------|------|------|
| ⚠️ | `kodokuInfo.hinList[0].teikiBunBusu` | 字段名不匹配 | JSON 用 `teikiBunBusu`,DTO @Schema name 为 `teikiBusu` |
| ⚠️ | `kodokuInfo.hinList[0].kihonBusu` | 类型隐式转换 | JSON 发送 number `1`,DTO 类型为 `String`,Jackson 会自动转换但不推荐 |
### ✅ 总结
主要问题是缺少必填字段 `targetMonth`。此外 `teikiBunBusu` 字段名与 DTO 不匹配,数据会丢失。