# LE-2026-05-001 - 前端联调高频错误模式归纳（来自 gz-atms-web 项目）

**日期**：2026-05-21
**模块**：通用
**分类**：前后端数据映射 / 接口参数 / 组件框架 / 数据库SQL
**严重程度**：P1(严重)

## 问题描述

从 gz-atms-web 项目（`D:\chinaweal\gz-atms\gz-atms-web\docs\fix\错题库`）的 12 条错题中，归纳出前后端联调的 8 大高频错误模式。

## 错误模式归纳

### 模式 1：字段名不匹配

| 维度 | 说明 |
|------|------|
| 表现 | 表格数据为空，prop 与后端返回的 JSON key 不一致 |
| 根因 | 前端 prop 用中文/自定义名，后端返回 Java camelCase 字段名 |
| 修复 | prop 必须与 API 返回的 JSON key 精确一致 |
| 检测 | 对比前端 table column prop 与后端 VO 字段名 |

### 模式 2：rowKey 不匹配

| 维度 | 说明 |
|------|------|
| 表现 | 翻页后操作列按钮消失、DOM 状态错乱 |
| 根因 | 默认 rowKey='id'，但后端主键字段名不同（如 marketId） |
| 修复 | 显式设置 `row-key="实际主键名"` |
| 检测 | 检查 Entity @TableId 的字段名，与前端 row-key 对比 |

### 模式 3：分页字段名（list vs records）

| 维度 | 说明 |
|------|------|
| 表现 | 列表数据加载不出来 |
| 根因 | MyBatis-Plus 分页返回 `records`，前端误用 `list` |
| 修复 | 统一使用 `res.records` |
| 检测 | 后端返回 `Page<Entity>` 时，前端取列表数据的字段名 |

### 模式 4：JSON 字符串未解析

| 维度 | 说明 |
|------|------|
| 表现 | 调用 `.map()` 报 TypeError: xxx.map is not a function |
| 根因 | 后端 CLOB/JSON 字段返回 String，前端当数组直接使用 |
| 修复 | `JSON.parse(data)` 或 `Array.isArray(data) ? data : JSON.parse(data)` |
| 检测 | 后端 Entity 中 String 类型但实际存储 JSON 的字段（如 relatedRules、scopeDistricts） |

### 模式 5：数组与单对象混淆

| 维度 | 说明 |
|------|------|
| 表现 | 访问属性报 undefined，渲染异常 |
| 根因 | 一对多关系后端返回数组，前端当单个对象使用 |
| 修复 | `Array.isArray(data) ? data[0] : data` |
| 检测 | 详情接口返回类型如果是 `List<Entity>` 而非 `Entity` |

### 模式 6：响应拦截器自动解包

| 维度 | 说明 |
|------|------|
| 表现 | 取 res.data.data 报 undefined |
| 根因 | request.js 拦截器已自动解包 `response.data`，业务代码再解包一次就多了一层 |
| 修复 | 直接使用 `res.list`、`res.total` 等已解包字段 |
| 检测 | 检查前端 request.js 响应拦截器的 return 逻辑 |

### 模式 7：导出接口 responseType 未设 blob

| 维度 | 说明 |
|------|------|
| 表现 | 文件下载报"业务出错"或下载文件损坏 |
| 根因 | 未设置 `responseType: 'blob'`，二进制数据被当文本处理 |
| 修复 | 请求配置中添加 `responseType: 'blob'` |
| 检测 | 所有文件下载接口的前端请求配置 |

### 模式 8：排序字段驼峰未转下划线

| 维度 | 说明 |
|------|------|
| 表现 | 达梦数据库报错"列名无效" |
| 根因 | 前端传驼峰字段名，后端直接拼 SQL，DM8 要求大写下划线列名 |
| 修复 | 后端排序字段先转下划线再拼 SQL，或前端直接传下划线格式 |
| 检测 | 后端 QueryWrapper orderBy 使用了 camelCase 字段名的位置 |

## 检测规则

```
CHECK: 对 OARMS 项目进行以下 8 项自动检测
RULE:
  1. 前端 table column prop == 后端 VO/Entity 字段名
  2. 前端 row-key == 后端 @TableId 字段名
  3. 前端分页取数据字段 == "records"（非 "list"）
  4. 后端 CLOB/String 字段（relatedRules, scopeDistricts 等）前端有 JSON.parse
  5. 详情接口返回数组时前端有 Array.isArray 判断
  6. 前端 request.js 拦截器解包逻辑与业务代码一致
  7. 文件下载接口前端有 responseType:'blob'
  8. 后端排序字段名已转下划线
FAIL: 任一规则不满足 → 报告具体位置和修复建议
```