136 行
4.1 KiB
Markdown
136 行
4.1 KiB
Markdown
# 产品 Step1-5 保存接口 JSR-303 校验真实生效
|
||
|
||
**日期**: 2026-04-23
|
||
**PR**: #1270 (Closes #1269) — PR #1259 后续补丁
|
||
**服务**: hl-product-service-v2 / hl-order-service-v2
|
||
**类型**: fix（修复校验漏补）
|
||
|
||
---
|
||
|
||
## 背景
|
||
|
||
PR #1259（装备建议字段改条目列表）里 SaveReqVO 加了 JSR-303 校验注解（`@NotBlank` / `@Size(max=20)` / `@Size(min=1, max=50)`），但 `AdminProductController` 的 Controller 方法未加 `@Valid` 修饰符，**校验注解实际未触发**。非法数据仍能 200 入库。
|
||
|
||
本次补丁把 Step1-5 全部保存接口及一个订单接口补齐 `@Valid`，校验现在真实生效。
|
||
|
||
---
|
||
|
||
## 影响接口（9 处）
|
||
|
||
| 接口 | Method |
|
||
|------|--------|
|
||
| `POST /admin/product/item/basic` | saveBasic |
|
||
| `POST /admin/product/item/{id}/itinerary` | saveItinerary |
|
||
| `POST /admin/product/item/{id}/route` | saveRoute |
|
||
| `POST /admin/product/item/{id}/price-calendar/batch` | savePriceCalendar |
|
||
| `POST /admin/product/item/{id}/schedule` | saveSchedule（2 个）|
|
||
| `POST /admin/product/item/{id}/schedule/batch` | batchCreateSchedule |
|
||
| `PUT /admin/product/item/{id}/supplement` | saveSupplement |
|
||
| `PUT /admin/product/item/{id}/detail-blocks` | saveDetailBlocks |
|
||
| `DELETE /admin/order/{orderId}/itinerary/pending/{editId}` | withdrawPendingEdit |
|
||
|
||
---
|
||
|
||
## 行为变化（前端必读）
|
||
|
||
### 之前（PR #1270 前）
|
||
```http
|
||
PUT /admin/product/item/{id}/supplement
|
||
{
|
||
"equipmentList": [
|
||
{"text": ""} // 非法：空 text
|
||
]
|
||
}
|
||
→ 200 OK（错误地通过！数据存入 DB）
|
||
```
|
||
|
||
### 之后（PR #1270 后）
|
||
```http
|
||
PUT /admin/product/item/{id}/supplement
|
||
{
|
||
"equipmentList": [
|
||
{"text": ""}
|
||
]
|
||
}
|
||
→ 400 {
|
||
"code": 400,
|
||
"success": false,
|
||
"message": "equipmentList[0].text: 装备文案不能为空"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 装备建议校验规则（生效中）
|
||
|
||
| 规则 | 违反时错误消息 |
|
||
|------|---------------|
|
||
| `equipmentList` 条目数 ≤ 20 | `equipmentList: 装备建议条目数不能超过20条` |
|
||
| 单条 `text` 非空非空白 | `equipmentList[0].text: 装备文案不能为空` |
|
||
| 单条 `text` 长度 1-50 字 | `equipmentList[0].text: 装备文案长度需在 1-50 字符之间` |
|
||
|
||
**注意错误消息格式**：`{字段路径}: {消息}`，含数组索引（`[0]`、`[1]` 等），前端可精确定位哪条条目出错。
|
||
|
||
---
|
||
|
||
## 前端建议
|
||
|
||
### 1. 前置校验（推荐）
|
||
admin 编辑器在提交前自行 validate 一次：
|
||
- 条目数 > 20 → 禁止提交 + toast
|
||
- 单条 text 空 → 禁止提交 + 红色高亮
|
||
- 单条 text 长度 > 50 → 禁止提交 + 高亮
|
||
|
||
避免走到后端才发现，体验更好。
|
||
|
||
### 2. 后端报错展示（兜底）
|
||
如果绕过了前置校验，后端 400 返回的 `message` 字段可直接 toast：
|
||
|
||
```javascript
|
||
const resp = await api.saveSupplement(req);
|
||
if (resp.code !== 200) {
|
||
ElMessage.error(resp.message || '保存失败');
|
||
return;
|
||
}
|
||
```
|
||
|
||
**错误消息已中文化**，直接展示即可。
|
||
|
||
### 3. 数组索引提示
|
||
如果要做精细错误提示，可解析 `equipmentList[N].text` 中的 N，滚动聚焦到对应条目输入框。
|
||
|
||
---
|
||
|
||
## 其他接口的校验
|
||
|
||
`basic / itinerary / route / price-calendar / schedule` 等其他 Step 接口的 SaveReqVO 本来就有 JSR-303 注解，但同样因为缺 `@Valid` 没有生效。**本次补丁一起修复**。
|
||
|
||
常见校验约束（以 `ProductBasicSaveReqVO` 为例）:
|
||
- `productType` 非空
|
||
- `name` 长度 ≤ 30 字
|
||
- `tripDays` ≥ 1
|
||
- 具体以 Knife4j `@ApiModelProperty` 中的 `required`/`allowableValues` 为准
|
||
|
||
如果前端之前传错数据能 200，现在可能 400，请以实际接口返回为准调整。
|
||
|
||
---
|
||
|
||
## 向后兼容
|
||
|
||
- **合法请求**：行为不变，仍 200
|
||
- **非法请求**：从"假成功（200 入脏数据）"变为"正确失败（400 + 可读消息）"
|
||
- 属于**修复性变化**，非破坏性
|
||
|
||
---
|
||
|
||
## 验证
|
||
|
||
测试服网关已 curl 4 场景全过：
|
||
|
||
```bash
|
||
# 合法 3 条 → 200
|
||
# 21 条 → 400 equipmentList: 装备建议条目数不能超过20条
|
||
# 空 text → 400 equipmentList[0].text: 装备文案不能为空
|
||
# 51 字 text → 400 equipmentList[0].text: 装备文案长度需在 1-50 字符之间
|
||
```
|