避坑清单 — 星云 ERP
持续补充:每次解决一个新坑,追加一条(编号递增),写清「坑 → 后果 → 正确做法」。 开发前通读,开发中怀疑踩坑时回来对照。
1. 同一功能的多个查询接口口径必须一致
坑:弹窗查询用 process_status = 'COMPLETED' + frozen = 0,而提交校验用 approval_status = 'PASS',且校验不查 frozen。
后果:前端能选出来的计划,提交时被后端拒绝;或被冻结的计划能通过校验。
正确做法:同一业务对象的所有查询/校验路径统一同一筛选口径(过磅码单已统一为:未删除 + 未冻结 + process_status='COMPLETED' + 不在变更/补单中);新增接口时先 Grep 该表已有查询条件。
2. PageHelper 分页只拦截 startPage 后的第一条 SQL
坑:PageHelperUtil.startPage 与目标查询之间插入了其他查询(如校验用的 count),分页作用到错误的 SQL 上。
正确做法:startPage 紧贴目标查询;需要预校验的逻辑放在 startPage 之前。返回统一 PageResultUtil.convert(new PageInfo<>(datas))。改完接口响应结构会从数组变 {datas, total, ...},必须提醒前端。
3. 逻辑删除 + 唯一键(如 uk_pwt_code)
坑:作废是 deleted=1 逻辑删除,行不物理删除;若取号/查重过滤了 deleted,作废单编号会被复用,撞数据库唯一键。
正确做法:编号类查询(findMaxCodeByPrefix、唯一性 count)不过滤 deleted,并写注释说明"避免与作废单据编号重复"。单列唯一键与逻辑删除自洽,不要改成 (code, deleted) 复合唯一。
4. MyBatis-Plus updateById 的 NOT_NULL 策略会忽略 null 字段
坑:想通过 updateById 清空某字段(置 null),实际 SQL 根本不带该字段,清不掉。
正确做法:需要显式覆盖(含清空)的字段,用 Wrappers.lambdaUpdate(X.class).set(X::getField, value)...eq(...) 逐个 set;批量改字段前想清楚哪些值可能为 null。
5. 数量单位:采购计划=吨,过磅码单=公斤
坑:从计划/计划明细带出数量直接入库或返回,单位错了 1000 倍。
正确做法:跨模块取数统一走 convertTonToKilogram(BigDecimal.movePointRight(3),无精度损失,null 安全),入口(保存子表)和出口(查询返回)都要换算;新代码涉及数量先问单位。
6. Warm-Flow 集成易漏项
-
BPM_FLAG常量值必须与流程设计器里的流程编号完全一致,否则startInstance失败 - 流程结束回调必须在
BusinessDataHandlerServiceImpl的 switch 注册case,忘了注册 = 单据永远停在 AUDIT -
REVOKE(撤销)/TERMINATION(终止)也要映射到 REFUSE,别只处理 REFUSE - 接入流程后:审核按钮
showExamine必须"当前用户有待办 && AUDIT",不能再按状态硬判;本地 examine 接口应删除 - 列表和详情两条返回路径都要调用
fillOperateFlags
7. 编辑锚点不唯一导致改错位置
坑:文件里存在多个相同代码块(如多处 return PageResultUtil.convert(new PageInfo<>(datas));),用短锚点做替换会命中第一个,方法插错位置甚至误删其他方法。
正确做法:替换锚点必须带上下文保证唯一(方法签名/相邻独有行);插入后 Read 回读确认位置;对含重复片段的大文件尤其小心。
8. 改字段名/删字段前必须全局查引用
坑:Vo 字段改名(如 supplierId→supplierName)后,其他地方仍调用旧 getter,编译失败或静默丢参。
正确做法:先 Grep 字段名|Getter名 全仓确认引用点;XML 里的 #{vo.xxx} / test="vo.xxx" 也要同步搜(Java 诊断查不出 XML 引用)。
9. XML 公共 SQL 片段的改动影响所有引用方
坑:为某个查询在 <sql id> 里加 JOIN/列,导致复用该片段的其他查询行为改变或列名冲突(别名重复)。
正确做法:改公共片段前 Grep <include refid="该片段"> 列出所有使用方逐一核对;加 JOIN 用主键关联(一对一)避免行数膨胀;别名避免与既有别名冲突。
10. 数据库字符集/排序规则兼容
坑:新表用错字符集(utf8mb4_bin vs utf8mb4_general_ci vs utf8mb3),关联查询隐式转换或比较不一致。 正确做法:新表/加列跟随同业务老表的字符集与排序规则(过磅码单系 utf8mb4_general_ci,部分老表 utf8mb3);写 SQL 前先看目标表 DDL。
11. 新增字段的完整同步链
坑:只改了 entity,XML resultMap/SELECT、Vo、Bo 漏改,导致查询列缺失或保存丢字段。
正确做法:按 skill/.trae/skills/新增字段 清单走:base.sql(ALTER 追加)→ entity → XML(resultMap+SELECT) → QueryVo/CreateVo/UpdateVo → GetBo;BeanUtil.copyProperties / BaseBo 构造按同名字段自动映射,字段名必须对齐。
实证:diff_quantity_exceeded 上线时实体/Vo/Bo/DDL 全改了,唯独漏了 ProcurementPlanMapper.xml 的 resultMap+SELECT,列表/详情查不出值——XML 自定义查询列是最易漏的一环,加列后 Grep 列名自查 XML 是否覆盖。
12. 非持久化展示字段用 @TableField(exist = false)
坑:把列表聚合值(GROUP_CONCAT 的 plan_codes)、关联名称(workshop_code)、按钮标记(showExamine)当持久字段建列或漏注解,MP 生成 SQL 报"列不存在"。
正确做法:库中没有的字段一律 @TableField(exist = false);由 XML JOIN/子查询填充,或 Service 层回填并给默认值(如 = false 防止序列化出 null)。
13. 单据状态变更不要"顺带"重置审核状态
坑:修改单据时强制 set(approvalStatus, DRAFT),导致驳回单(REFUSE)修改后状态错乱。
正确做法:修改只改业务字段;状态机流转只发生在明确的状态动作里(submit→AUDIT、流程回调→PASS/REFUSE)。驳回单修改后保持 REFUSE,可直接重新提交。
14. 时间语义字段要写清记录时机
坑:firstGrossWeightTime(首次毛重时间)曾在错误的地方(上传签字凭证)赋值;与"完成时间"混用。
正确做法:每个时间字段的注释写明"以什么为准、何时记录、能否覆盖";多入口赋值前先判断"已记录则不再覆盖"。
15. 模糊筛选注意 NULL 与多值字段
坑:LIKE '%补%' 不会命中 NULL(正常计划 plan_type 为 NULL),"精确查正常"和"不传查全部"语义不同;多值字段(如 "变 补")用 LIKE 才能同时命中组合值。
正确做法:筛选语义与用户确认(不传=全部?要不要"正常"选项?);多值枚举字段沿用项目既有 LIKE 方式(参考 ProcurementPlanMapper 的 plan_type)。
16. POI CellStyle 水平对齐方法名是 setAlignment 而非 setHorizontalAlignment
坑:POI 的 CellStyle 接口设置对齐的方法命名不对称:水平对齐是 setAlignment(HorizontalAlignment),垂直对齐才是 setVerticalAlignment(VerticalAlignment);按直觉写 setHorizontalAlignment 会编译报"找不到符号"。
后果:编译失败(IDE 诊断即可发现)。
正确做法:照抄 ExcelUtil.buildPdfVerticalTitleStyle(ExcelUtil.java 约 408 行):style.setAlignment(HorizontalAlignment.CENTER) + style.setVerticalAlignment(VerticalAlignment.CENTER);克隆样式用 cloneStyleFrom 后再改对齐,避免破坏模板边框。
17. BaseBo 子类必须显式声明两个构造器,否则实体转 Bo 属性全空
坑:项目惯例 GetXxxBo extends BaseBo<Xxx> 必须显式写两个构造器:无参(Jackson/MyBatis 反序列化用)和 GetXxxBo(Xxx dto) { super(dto); }(负责把实体属性拷贝进 Bo)。Controller 里 list.stream().map(GetXxxBo::new) 依赖带参构造器完成转换,漏写则编译报错或运行时拿到全空壳数据。
后果:列表/详情接口返回的字段全为 null(或编译报"构造器无法应用"),前端拿到空数据。
正确做法:新建 Bo 时照抄既有 Bo 的构造器写法,例如:
public GetXxxBo() {
super();
}
public GetXxxBo(Xxx dto) {
super(dto);
}
18. 同一业务概念的字段全链路命名必须与源表/已有实现保持一致
坑:新模块引用已有表的字段时自创命名——如过磅明细的"过磅品种"在源表叫 product_id/product_name(关联 base_data_breed_relationship),新化验送样表却写成 breed_relationship_id/breed_name;同类先例:申请明细的品种代号是 category、采购计划明细也是 product_id。
后果:DB 列 → 实体 → VO/Bo → XML → 前端字段各层对不上,联调时前端要额外记忆映射关系,后续维护者搜字段名搜不全,返工改名牵扯全链路(SQL/实体/VO/Bo/XML/前端传参全要动)。
正确做法:动手前先 Grep 源表字段在项目里的既有命名,新表字段、实体属性、VO/Bo 字段、XML 列名、前端传参全部沿用同一名字;仅在语义确实不同(如"品种代号 category"与"品种ID product_id"是两个东西)时才用不同字段名。
19. XML 里主表别名统一用 tb,禁止自创缩写别名
坑:写新查询时自创主表缩写别名(如 pwt/paa),甚至 FROM 定义的别名与 SELECT/WHERE 用的不一致——FROM procurement_weighing_ticket AS tb 但各处引用 pwt.xxx,运行时报"Unknown column 'pwt.id'"。项目全库(30+ 个 Mapper XML)惯例是主表别名一律 tb。
后果:SQL 运行时才报错(Java 诊断查不出);别名不一致的 SQL 拷贝拼接时极易引入此类错误。
正确做法:任何 XML 的主表(业务单据自身表)统一写 FROM 表名 AS tb,SELECT/WHERE/JOIN ON/ORDER BY 全部用 tb. 前缀;只有 JOIN 进来的关联表才用有区分度的别名(如 ws、bdcs、子表 pwtp、明细 pwtl)。新写 SQL 前先看同目录既有 XML 的别名写法,保持一致。
20. MP getById 查不出 exist=false 字段;分厂审核单据传实体给流程引擎前必须联表带出 workshopCode
坑:分厂相关单据的审核节点编码 = 流程前缀 + 分厂前缀(base_data_workshop.code,如 yfc/efc/sfc/ztfc)+ 环节缩写(如 material_settle_yfcckzg)。单据实体只有 workshop_id/workshop_name(冗余列),workshopCode 是 @TableField(exist = false) 联表字段;this.getById(id) 是 MP 单表查询,查出的实体 workshopCode 永远为 null,startInstance(BPM_FLAG, id, BPM_FLAG, entity) 传给流程引擎的实体就缺分厂前缀。
后果:流程引擎按分厂前缀路由审核节点/角色(material_settle_yfcckzg 等)时匹配不上,审核流向错误或全部落到无分厂节点。
正确做法:涉及分厂审核的单据(原料结算详情单等)Mapper XML 提供 findById(公共片段 LEFT JOIN base_data_workshop ws ON ws.id = tb.workshop_id 带出 ws.code AS workshop_code);提交审核、传实体给流程引擎、以及后续涉及分厂审核路由的取数统一用 mapper.findById(id),不用 getById(参考 ProcurementMaterialSettleDetailServiceImpl.submit)。列表查询若要展示编号,同理在列表公共片段里 JOIN 带出。读侧同理:planCodes/planIds 等公共片段子查询字段(GROUP_CONCAT)也是 exist=false,selectList/selectById/getById 全都带不出(永远 null),需要这些字段的取数(如收料单制单下拉、create 冗余存储)一律换 mapper.findById;跨模块取来源单数据时先确认目标字段是不是联表字段。
21. 权限编码后缀用 modify 不用 update(照抄同业务模块惯例)
坑:新模块 Controller 自创权限编码后缀 :update(如 warehouse-manage:warehouse-receive:update),而项目权限编码惯例是 :modify(原料结算详情单原用 :update,后已改回 :modify)。
后果:权限编码与系统权限管理里配置的菜单/按钮权限对不上,用户操作报无权限,需要前端菜单、权限初始化 SQL、后端注解三处返工。
正确做法:新增模块写 @HasPermission 前先 Grep 同业务模块的既有编码(如 warehouse-manage:material-settlement:*)照抄后缀风格:query/add/modify/submit/cancel/review/back/approve/print;修改类操作一律 :modify,不用 :update。
22. 实体审计字段四件套都要带 fill 注解,创建人/更新人不要漏
坑:新建实体只给 createById/updateById/createTime/updateTime 加了 @TableField(fill = FieldFill.INSERT / INSERT_UPDATE),createBy(创建人姓名)和 updateBy(更新人姓名)漏加,MP 自动填充(MetaObjectHandler 按 fill 策略匹配字段)不生效,入库后这两列永远为 null,列表"创建人"列空白。四件套 = createById、createBy、updateById、updateBy,再加 createTime/updateTime 共六个,一个不能少。
后果:页面创建人/更新人显示空白;数据没有操作人追溯;事后补数困难。
正确做法:新建实体时审计字段照抄成熟实体(如 ProcurementMaterialSettleDetail)的写法,六个字段逐一检查注解:createById+createBy+createTime 用 INSERT,updateById+updateBy+updateTime 用 INSERT_UPDATE;写完实体后对照结算详情单实体逐一核对。
23. 工具类方法名禁止臆造,先 Grep 再用
坑:凭空臆造工具方法名(如 lframework 的 StringUtil.isEqual),实际该类没有这个方法,编译报"Cannot resolve method"。
后果:编译失败;IDE 诊断若未及时覆盖会带到提交环节才暴露。
正确做法:使用工具类(StringUtil/CollectionUtil/NumberUtil 等)前先 Grep 项目内该方法既有用法确认存在;字符串等值判断项目内用 java.util.Objects.equals(a, b)(自带 null 安全),或 Grep StringUtil 源码/既有调用确认真实方法名。
24. 「可制单」判定在下拉、提交校验、按钮标记三处必须复用同一套逻辑
坑:新增单据时,可制单下拉按 A 口径过滤,create 提交按 B 口径校验,来源单的前端按钮标记按 C 口径(或根本没有标记),三处各自维护条件,改一处漏两处。实证:请款单里结算比例100%的仓库收料单只在下拉里排除,收料单按钮仍显示;买断自提多车收料单按 receiveId 判占用,同一计划三张收料单可各生成一张尾款请款单(重复付款)。
后果:前端能点、后端拒绝,或后端放行本应禁止的单据,严重时超付/重复付款。
正确做法:把「可制单判定」收敛到一个 private assert 方法(抛具体中文提示);按钮标记用 try-catch 该断言转 boolean,下拉、新增页带出数据全部复用;跨模块按钮标记通过 Service 暴露 canApplyFromXxx(id) 供来源单 fillOperateFlags 调用。按钮标记字段用 @TableField(exist = false),Bo 加同名字段由 copyProperties 带出,无需改 XML resultMap/SELECT。
当前实现(2026-11-10):请款单已取消「可制单来源下拉」,改为计划/过磅码单/仓库收料单三个来源单列表统一返回 showApplyPayment(true/false),前端按该字段显示「生成请款单」按钮并携带来源单ID进入新增页(/generateData 带出数据)。判定入口统一为 canApplyFromPlan/canApplyFromTicket/canApplyFromReceive,三者内部均 try-catch 对应的 assertXxxUsable,与 create 提交校验同源;采购计划在 fillShowExamineInfo 内回填,避免另起一套筛选口径。
25. 过磅码单作废联动链新增单据时,必须同时补调用
坑:过磅码单 delete() 里是一串 xxxService.deleteByWeighingTicketId(id) 联动(化验送样/化验报告/结算详情/收料单/买断核算/请款单)。新模块只写了自己的 deleteByWeighingTicketId 实现,忘了在码单 delete() 里加调用。
后果:码单作废后该模块单据仍然有效,形成孤儿数据。
正确做法:新增「按码单联动作废」方法后,Grep ProcurementWeighingTicketServiceImpl.delete 的联动链,确认新方法在调用列表里。查询范围要同时覆盖 ticket_id = 码单ID 与 receive_id IN (该码单下所有收料单ID) 两类并去重,避免来源收料单未冗余码单ID时漏作废;查收料单ID时不要过滤 deleted(此时收料单已被前面的联动标记作废)。
26. 已有码值直接透传,不要二次映射或补中文名称字段
坑:请款单 bizType 用 determineBizType(plan.getDeliveryMode()) 做「兜底转换」(非 PICK_UP 一律归 FACTORY_DELIVERY),Swagger 里还预留了 bizTypeName 中文名称字段。
后果:来源表原值被改写,null/未知值被伪装成合法业务类型;前后端要维护两套码值和中文映射,口径容易走偏。
正确做法:来源字段本来就是码值时直接 setBizType(plan.getDeliveryMode());判断处统一用同一套常量比较(如 DELIVERY_MODE_PICK_UP),不额外生成中文名称字段,@ApiModelProperty 只写字段语义不做值翻译。
27. 单据自动带出的业务附件要独立字段 + 独立上传接口,并写进制单断言
坑:请款单「计划生成时自动带出计划请款附件」直接取了计划的通用附件 attachment_file_ids;而计划表根本没有独立的请款附件,也没有「附件已上传」的制单前置校验。通用附件与业务附件(请款附件、签字凭证)语义不同,不能混用。
后果:生成的请款单带出的可能是无关附件或空附件,财务审核无凭证;按钮显示 true 但后端拒绝(或反过来),口径不一致。
正确做法:
- 已有表加列按开发流程在
base.sql尾部ALTER TABLE ... ADD COLUMN,不改原 CREATE;Entity、Bo、MapperresultMap、自定义 SQL 的显式 SELECT 列四处同步加。注意selectById走实体字段会自动带出新列,但分页/详情走自定义 resultMap 会漏值,只测一条路径容易漏改。 - 上传走独立接口(如
PUT /attachment/request)+ 独立 Vo,Service 内只lambdaUpdate().set(两个附件字段);不要复用整表update(BeanUtil.copyProperties(vo, Entity.class)会带出 null,还可能覆盖流程/审核字段)。 - 把「附件非空」写进唯一的
assertXxxUsable;按钮标记canApplyFromXxxtry-catch 同一断言,/generateData与create复用buildContext,三处口径自动一致,无需各自加判断。 本次实现(2026-11-10):计划新增request_file_ids/request_file_names+uploadRequestFiles(Vo 中fileIds@NotBlank,权限复用plan-manage:domestic-plan:upload);buildContext改读计划请款附件;assertPlanUsable增加「请先上传请款附件再生成请款单」。注意子计划createSubPlan从 Vo 复制,不继承父计划请款附件,拆分后需重新上传。
28. 「带出数据」接口改成「调用即建单」时:收敛建单逻辑、幂等、提交前拦截
坑:generateData 原本只读带出数据、create 才落库,两份组装逻辑;改为「调用 generateData 就生成草稿」时若复制一遍 create 的字段填充,后续改口径必然只改一处。GET 落库还会被刷新/预取重复触发;草稿的手填字段为空却可以直接提交审核。
后果:两条路径生成的单据字段不一致;重复请求产生多张单;申请金额为空的草稿进入审核流程。
正确做法:
- 抽私有
buildDraft(source, sourceId, vo),vo=null时只写自动字段并跳过matchApplyAmount等手填校验;create与generateData共用,只有一份建单口径。 - 幂等:按
source + sourceId + 草稿状态 + deleted=false先查已有单,有则直接返回该单 ID,不重复建单。 - 生成类接口加
@Transactional和@OpLog;对草稿留空的必填字段,在submit加拦截(本次:明细applyAmount为 null 不允许提交)。 - 有副作用就别用纯 GET:本次
@RequestMapping(method={POST, GET})保留前端兼容并在 Swagger 标注推荐 POST。 -
生成接口只返回落库单据 ID(String),不要组装一份「生成数据 Bo」回传:前端后续拿 ID 走详情查询(
GetFundPaymentRequestBo已含主表 + 明细全部字段),再走update修改补充,不再有「新增页带出数据」这一环。回传 Bo 等于把详情 Bo 复制一份,字段口径必然分叉,且白查一次主表/明细。 本次实现(2026-11-10):requestDate=LocalDate.now()、payMethod固定「电汇」由buildDraft统一写入;自动带出来源单信息、请款附件、明细预付金额与合计;对方户名/开户行/账号、请款说明、补充说明附件、明细申请金额留空由update补充(update的matchApplyAmount仍要求传全量明细,编辑页从详情lines取planId后逐行填applyAmount)。 后续调整(2026-11-10):删除GetFundPaymentGenerateDataBo(含LineBo)与getGenerateData中「从落库单据读回再组装 Bo」的整段;Service 方法改名generate返回String,Controller 返回InvokeResult<String>。接口路径/generateData保留兼容,Swagger 文案改为「调用即落库,仅返回请款单ID」。
29. 新建「资金台账」这类宽表模块:包/表名避让 + 五处列名对齐 + 分月筛选
坑:项目已有「应收款台账」占用 sc/impl/ledger、sc/controller/ledger、resources/mappers/ledger 和 receipt_ledger_info 表;新台账若直接叫 ledger 会混淆。宽表 60+ 字段,DDL / Entity / resultMap / <sql> SELECT / Bo 任一处漏列或拼错列名,都是运行时才暴露(Java 编译查不出)。分月筛选用 YEAR(col)/MONTH(col) 会让索引失效。
后果:包冲突或 SQL 报 Unknown column;列表字段悄悄返回 null 且无人发现;按月查询全表扫描。
正确做法:
- 新模块用独立包名/表名(本次
procurement/fundledger+fund_ledger),表名字符集跟随同业务老表(资金支付系utf8mb3)。先 Grep 全仓确认无同名表。 - 写完后用脚本比对 DDL 列名、实体字段(驼峰转下划线)、resultMap column、公共 SELECT 列、Bo 字段五处集合,必须完全一致(本次各 70 列,Bo 有意少
createById/updateById两个不对外字段)。 - 分月筛选:Vo 收
Integer year + Integer month,Controller 用YearMonth.of(y,m).atDay(1)/atEndOfMonth()换算成LocalDate applyDateStart/applyDateEnd,XML 用>= / <=(可用idx_apply_date);同时保留日期区间入参供「申报日期」筛选,两组共用同一组条件。 - 权限后缀照抄既有:查询
:query、修改:modify、平账:reconciliation(应收款台账已有);不要自创:red(第 21 条),冲红复用:modify。 - 派生字段(欠票额/欠单额/增票余款/对比/是否清欠等)在「先做基础方法」阶段只建列 + 注释写清公式,不写回填/重算;但「平账后是否清欠改为否」这类状态动作属于基础方法,要在 Service 内落库(
lambdaUpdate().set(..., false)),不可留给后续。 本次实现(2026-11-13):fund_ledger一个计划一条(uk_fl_plan_id),基础方法 = 分页列表 / 详情 / 修改(来票时间·数量·金额、出库单数量、备注)/ 冲红(金额·说明·附件)/ 平账(说明·附件 + 清欠校验与置否)。列表与详情共用GetFundLedgerBo(第 28 条口径,不复制第二份 Bo)。台账行生成与各业务字段的数据更新逻辑本期明确不做。
30. 取 @TableField(exist = false) 字段必须走带联表的 Mapper 方法,MP 内置查询恒为 null
坑:这类字段不是数据库列(值来自 JOIN 其它表或 GROUP_CONCAT),selectById / selectList / selectBatchIds / getById / this.list() 都不会查询它,结果永远 null,且编译和 IDE 诊断都不报错。资金台账刷新就踩了两次:
-
procurementPlanMapper.selectById(planId)取purchaseDepartmentName/regionName/supplierName,实际全是 null(改用findById,XML 里 JOINsys_dept/base_data_company_short/ 供应商表); -
procurementPlanLineMapper.selectList(...)取productName(来自LEFT JOIN base_data_breed_relationship br),台账「品种」列全空(改用getByProcurementPlanId)。
常见非持久化字段(取数前先看实体注解,不要凭字段名猜):
-
ProcurementPlan:supplierName、companyShortName、companyFullName、purchaseDepartmentName、regionName、priceCode、workshopName、showExamine、showExamineDetail、showApplyPayment -
ProcurementPlanLine:planCode、productName、workshopName -
ProcurementWeighingTicket:workshopCode、planCodes、planIds、showExamine、showExamineDetail、showApplyPayment -
ProcurementWarehouseReceiveOrder:planDate、workshopCode、showExamine、showExamineDetail、showApplyPayment(注意该实体的planCodes/planIds/workshopName是数据库冗余列,可直接用内置查询) -
ShipmentsPlan:workshopName -
FundPaymentRequest:showExamine、showExamineDetail(由代码填充,不是查询)
后果:字段静默为空,页面列空白、按名称匹配/限额计算失效,运行时无任何报错,排查成本高。
正确做法:
- 取数写代码前先确认目标实体字段是否带
@TableField(exist = false);只要带,禁止用 MP 内置查询方法取值。 - 改用 Mapper XML 里带联表的方法:
procurementPlanMapper.findById(id)、procurementPlanLineMapper.getByProcurementPlanId(planId)/getByProcurementPlanIds(ids)、shipmentsPlanMapper.getById(id);没有现成方法就在该 Mapper XML 公共<sql>片段补 JOIN 与列,再新增查询方法。 - 只用到数据库列的取数(如仅
code、deliveryMode、settlementRatio、approvalStatus)继续用内置查询即可,不必一律替换。 - 同类禁止:
@TableField(exist = false)字段也不能写进Wrappers.lambdaQuery().eq/orderBy条件(MyBatis-Plus 取不到列名会直接抛异常)。 - 新增非持久化字段时,在实体注释里写明来源表,并在对应 Mapper XML 的公共片段同步带出,避免调用方误用内置查询。
回写模板(新增踩坑时复制)
## N. 标题
**坑**:
**后果**:
**正确做法**: