的用途与常见坑解析)
第一次看到 TableField(exist false) 的时候我盯着注解愣了好几秒。字面意思很直接——“这个实体属性在数据库表里不存在”但问题也随之而来既然表里没有这一列你把它写在实体类里干什么后来在真实项目里被“未知列”报错折磨过几次才彻底想明白实体类从来不只是“一张表”的镜像它还得当查询结果的承载对象。做联表查询、统计汇总、临时状态标记的时候总有那么几个属性在数据库里找不到归宿代码却必须用它们来接数据。这个注解就是 MyBatis-Plus 用来区分“物理列”和“非持久化字段”的开关。这篇内容写给所有用 Java 写后端、天天和 MyBatis-Plus 打交道的同学尤其是刚把实体类当成万能袋子的初级开发——看完你不仅能搞懂它是什么意思还能避开我踩过的那些坑。1. 注解本质它声明的是“虚拟字段”1.1 先搞懂 exist 参数到底在哪里生效TableField 的全限定名是 com.baomidou.mybatisplus.annotation.TableField它是一个作用于实体类成员变量上的注解。最常用的参数除了 value指定物理列名之外就是 exist。exist 的默认值是 true意思是“这个属性对应数据库表里的某个真实列”。当你把它写成 false就等于在告诉 MyBatis-Plus当前这个属性只是一个普通 Java 字段表里没有和它对应的列你在自动生成 SQL 的时候不要把它写进去。举个例子一张用户表 user 只有三个字段id、name、age。但我在做用户列表接口的时候想同时在每个用户后面带上他的订单数量 orderCount。订单数量不是 user 表里的列那这个值放哪最自然的做法就是放在用户实体里Data public class User { TableId private Long id; private String name; private Integer age; /** 数据库表中没有此字段仅用于接收联表统计结果 */ TableField(exist false) private Integer orderCount; }这段代码表达的意思非常明确orderCount 在表里没有对应列但它依然是 User 类的一个合法属性可以用来存查询结果。1.2 为什么叫 exist而不是 exclude名字很有意思。如果叫 exclude那表述重点可能是“排除字段”叫 exist重点则是“是否存在物理列”。区别虽小但对理解底层逻辑很重要——MyBatis-Plus 在解析实体类的时候会检查每一个属性是否存在对应的数据表列。存在就纳入字段列表不存在就直接跳过。existfalse 只是在“是否纳入字段列表”这个环节提前把这个属性过滤掉了而不是在执行 SQL 时临时删掉哪一部分。理解这一点后面很多“奇怪现象”就都能解释通了。顺便说一句如果一个字段在数据库里明明有对应列你却错误地标上 existfalse那么 MyBatis-Plus 生成 SQL 时不会报任何错只是那个字段的读写操作会“凭空消失”。这比报错更可怕因为数据静默丢失很难排查。2. 数据库里没有的字段为什么非要放在实体类里很多初学者看到这里都会问既然数据库没有这列我新建一个 DTO、VO 来放它不就行了答案是“可以”但现实中的很多场景直接塞在实体类里往往更省事这也是这个注解被大量使用的原因。做后端开发几年我见到的常见场景主要是下面这几种场景字段示例为什么不建议单独建 DTO联表查询带出统计值订单总数、销售总额、评论数量只是多一个字段为它单独建一个类太啰嗦关联查询带出其他表信息商品名称、用户昵称、分类路径数据查出来了顺手放实体里省一次回表内存临时标记是否选中、查询起始时间、当前页码纯粹是代码运行过程的中间变量表单展示字段状态描述文字、格式化后的时间串响应给前端时方便不想再封装一层我之前维护过一个订单模块订单实体 Order 的表里只有 status 这个整数但页面要显示“待支付”“已发货”这样的中文状态。最简单的办法是在 Order 类里加一个 statusDesc标上 existfalse然后在查询后统一转换一次。如果你非要为此建一个 OrderVO再把几十个字段一个个拷贝过去工作量瞬间翻倍还容易漏字段。另一个高频场景是“减少 N1 查询”。假设商品列表需要展示每个商品的累计销量如果不加非持久化字段很多人会先查商品列表再循环查每个商品的销量——商品有几百条数据库就要被轰炸几百次。而利用实体类加 existfalse再用一条 LEFT JOIN 聚合 SQL就能一次性把列表和销量全部取回来。后面第五章我会给完整示例。当然实体类塞非持久字段也要有节制否则实体类会变得非常臃肿。我的个人判断标准是额外字段控制在两三个以内并且只在当前实体的查询生命周期里使用就直接加注解如果字段很多或者要跨多个表组合出完全不同的结构该建 DTO/VO 还是要建。3. 不只是 exist它周围的一圈“兄弟参数”3.1 TableField 常用参数速查要真正用好 existfalse不能只看 exist 一个参数。我习惯把 TableField 看作一个“字段行为配置中心”它下面还有很多控制字段行为的参数。把它们放在一起才能避免踩到组合使用时的暗坑。参数作用默认值关键注意点value指定实体属性对应的物理列名驼峰转下划线存在物理列时才有意义exist该属性是否为数据表字段true设为 false 后字段不参与自动 SQLselect是否出现在 SELECT 子句中true只对物理列有意义fill字段自动填充策略DEFAULT配合插入、更新时自动填充updateStrategy更新时的字段策略继承全局控制为 NULL 时不更新insertStrategy插入时的字段策略继承全局控制为 NULL 时不插入whereStrategy作为查询条件时的策略继承全局控制 NULL 值是否参与查询keepGlobalFormat是否保留全局字段格式化false一般和物理列名格式化相关3.2 existfalse 与其他参数的相互作用很多人在网上抄到这样的写法TableField(exist false, select true) private String tempName;说实话select true 在这里是没多大意义的。因为一个字段一旦标记为 existfalse它在 BaseMapper 自动生成的 SELECT 语句中就已经被彻底剔除了select 属性根本没有机会发挥作用。select 参数的真实使用场景是数据库里有这个大字段但默认查询不想每次都把它带出来比如富文本内容、长 JSON 串这时才用 selectfalse 控制默认查询不加载。真正需要警惕的是和 fill 参数组合。假如你写TableField(exist false, fill FieldFill.INSERT) private String remark;启动时 MyBatis-Plus 解析字段虽然不会报错但执行 insert 的时候自动填充逻辑会给 remark 赋值而 INSERT 语句的字段列表里又会因为某些自定义逻辑带上它最终数据库执行时直接报“Unknown column remark”。除非你非常清楚底层机制否则我不建议把 existfalse 和 fill 同时用。道理很简单一个不存在于数据库的列谈何“填充”还有一点容易被忽略MyBatis-Plus 的全局更新策略默认是“非 NULL 字段才更新”。即使你没有给某个字段加 TableField(existfalse)普通字段如果值为 NULLupdateById 也不会更新它。但加了 existfalse 的字段是从“字段收集”源头就消失了跟值是不是 NULL 没有关系任何策略都对它无效。这个区别理解清楚了就不会在调试时白费功夫。4. 原理拆解MyBatis-Plus 是怎么把它从 SQL 里“剔除”的4.1 实体解析阶段的字段收集如果把这个问题上升到原理层你会发现整个流程非常清晰。MyBatis-Plus 在应用启动时会扫描项目里所有的实体类为每个实体构建一个 TableInfo 对象。TableInfo 里记录了主键字段、普通字段列表、逻辑删除字段、版本号字段等元数据。扫描到某个成员变量时它会检查是否有 TableField 注解注解存在且 existfalse不把该属性加入普通字段列表。注解存在且 value 有值把属性名映射为 value 指定的列名。没有注解按驼峰转下划线的规则把属性名当作物理列名。也就是说existfalse 的过滤发生在最靠前的“元数据收集”阶段。之后 BaseMapper 的 insert 方法生成 INSERT INTO 语句时是从 TableInfo 的字段列表里挨个取值拼装的update 方法生成 SET 子句时也一样。既然字段列表里根本没有这个属性SQL 里自然不可能出现它的身影。4.2 一个容易混淆的点自定义 SQL 为什么能映射上很多读者会有疑问既然这个字段不参与 SELECT那为什么我自己写 SQL 查出来的列会自动填到这个属性里面这里要区分两套机制。MyBatis-Plus 自动 SQL 的生成依赖的是上面说的 TableInfo 字段列表但 SQL 执行完后的结果映射是 MyBatis 框架自己的 ResultMap autoMapping 在起作用。自定义 SQL 里只要查了某个列而且通过列别名开启驼峰映射后也能通过下划线转驼峰能对应上实体属性名MyBatis 就会尝试把值赋值过去。哪怕这个属性标记了 existfalse也不影响。举个例子Select(SELECT u.id, u.name, COUNT(o.id) AS order_count FROM user u LEFT JOIN orders o ON u.id o.user_id GROUP BY u.id) ListUser selectUserWithOrderCount();只要 MyBatis 开启了 mapUnderscoreToCamelCaseorder_count 会自动映射到 User.orderCount就算不开启你把别名写成 orderCount 也能映射上。也就是说existfalse 管的是“自动 SQL 的拼装”而自定义 SQL 的映射归 MyBatis 管。两者互不干扰这才是这个注解真正的玩法——用来自定义查询结果落地非常顺畅。4.3 那为什么不直接加 transient 或 static有人可能会说Java 的 transient 关键字或者 static 修饰符也能让 MyBatis-Plus 跳过字段何必要用注解确实MyBatis-Plus 默认会忽略被 transient 或 static 修饰的属性但副作用很麻烦。transient 表达的是“不参与 Java 序列化”Spring Boot 默认用 Jackson 序列化为 JSON 时很多版本的 Jackson 并不认 transient它依然会把字段序列化出去static 则是类级变量实例之间共享在并发场景下容易出现数据错乱而且静态字段在序列化时也容易被忽略。TableField(existfalse) 的语义最纯粹它就是告诉持久层框架“表里没这一列”不影响序列化不影响实例隔离也不会给 JSON 输出造成额外负担。如果不想让某个虚拟字段出现在接口返回值里那是另一个话题用 JsonIgnore 去控制即可。5. 实战聚合统计字段如何优雅落地5.1 先看一下最直接的场景代码假设商品模块有两张表商品表 goodsid、name、price、stock和订单明细表 order_detailid、goods_id、quantity。现在有个需求商品详情接口要返回该商品的累计销量。先在商品实体里加一个虚拟字段Data public class Goods { TableId private Long id; private String name; private BigDecimal price; private Integer stock; /** 累计销量数据库表 goods 中没有此列 */ TableField(exist false) private Integer salesCount; }然后写一个自定义查询Mapper public interface GoodsMapper extends BaseMapperGoods { Select(SELECT g.*, IFNULL(SUM(od.quantity), 0) AS sales_count FROM goods g LEFT JOIN order_detail od ON g.id od.goods_id WHERE g.id #{id} GROUP BY g.id) Goods selectDetailWithSalesCount(Param(id) Long id); }开启驼峰映射后sales_count 列就会自动映射到 salesCount 属性。如果全局配置没开驼峰就把 SQL 里的别名直接写成 salesCount兼容性最强。这样查询出来的 Goods 对象里既包含真实的表字段又带着统计结果接口层直接返回即可。5.2 不加注解到底会发生什么重点来了。如果你忘记在 salesCount 上标记 existfalse会发生什么表面上看上面的自定义查询照样能跑通因为结果映射是 MyBatis 负责的不会去校验“这个实体属性是否在表里存在”。但隐患会在你调用 BaseMapper 内置方法时爆发。最常见的情况是后端同学查完详情后顺手调用 updateById 去更新商品价格比如Goods goods goodsMapper.selectDetailWithSalesCount(1L); goods.setPrice(new BigDecimal(99.00)); goodsMapper.updateById(goods);由于 salesCount 没有注解MyBatis-Plus 会把它当成 goods 表的真实列update 语句生成时就会变成UPDATE goods SET name ?, price ?, stock ?, sales_count ? WHERE id ?数据库里根本没有 sales_count 这一列立刻抛出Unknown column sales_count in field list这个报错我见过太多次了。加了 TableField(existfalse) 之后updateById 生成的 UPDATE 语句就只包含 id、name、price、stock干净利落不会再出这种问题。所以这个注解不是给“查询”用的而是保护“写入”的。5.3 分页场景的额外提醒再往外扩展一步。如果商品列表也要带销量统计一般会写成分页查询。MyBatis-Plus 的分页插件会对原 SQL 做处理生成 count 语句。带 GROUP BY 和聚合函数的 SQL如果 count 语句生成不严谨统计数量会变成分组后数量而不是总记录数。我常用的规避方法是把分页 SQL 包一层子查询或者使用分页插件的 optimizeCountSql 参数调整。这虽然不是 existfalse 本身的问题但实战中只要遇到“分页聚合统计虚拟字段”的组合就一定会碰到。提前知道这个坑能少熬一个通宵。6. 避坑用错这个注解的典型翻车现场6.1 坑一insert 时报 Unknown column这是出现频率最高的问题。某个实体类加了一个表里不存在的字段比如 createdBy却忘了写 existfalse然后执行 insert。MyBatis-Plus 把 created_by 拼进 INSERT 语句数据库直接报“Unknown column created_by”。有些框架的 SQL 日志默认没打开你看到报错时往往会一脸懵。我这里的排查思路很简单先打开 MyBatis-Plus 的 SQL 日志看它打印出的 INSERT 语句里有哪些列凡是“实体里有、表里没有”的列就是漏加注解的那个。6.2 坑二数据库里有列却标注了 existfalse这个坑的隐蔽性极强。比如某次数据库表结构升级新增了一列 remark实体类里也加了字段但团队另一个同事习惯性地复制粘贴了注解把 remark 标成了 existfalse。后果是insert 和 update 时 remark 永远不会写入数据库查询时尽管表里有数据返回值却一直是 null。而且这个过程不会报任何错误。排查方法是查看打印出的 SQL发现 INSERT / UPDATE 子句里根本没有 remark 列再去翻实体类十有八九就是注解写错了。这类问题不用慌多注意 SQL 日志就能快速定位。6.3 坑三虚拟字段被意外序列化返回给前端TableField(existfalse) 不影响 JSON 序列化。如果你加了一个内部标记字段比如“查询过程中是否命中缓存”本意只给后端逻辑用但 Spring Boot 返回 JSON 时它也会被带出去等于把内部实现细节暴露给了客户端。轻则产生冗余字段重则泄露敏感信息。我的习惯是虚拟字段如果不需要返回就统一加 JsonIgnore如果需要返回再单独建一个 VO 或者在字段上配合 JsonProperty 指定返回名称。说白了ORM 管数据库序列化管接口两个层面要分开控制。6.4 坑四和 TableLogic、Version 一起用逻辑删除字段 TableLogic、乐观锁版本字段 Version这两个注解都要求字段对应真实物理列。如果手误把逻辑删除字段也标成了 existfalse那 deleteById 生成的 SQL 将不再包含逻辑删除条件可能直接把数据库记录物理删除了。乐观锁版本号字段如果标错update 时不会带 version 比较条件并发更新就失去了保护。这里一定要特别谨慎所有“参与 SQL 条件生成”的特殊字段绝对不能标记为 existfalse。这类安全相关的问题光靠代码 review 还不够建议把它写进团队的代码规范里。6.5 坑五实体类膨胀虚拟字段扎堆有些项目用久了实体类里积累了十几个 TableField(existfalse) 字段时间一长没人分得清哪些是表里的真实列哪些是虚拟字段。这时候如果再让新成员接手很容易把虚拟字段当作查询条件写进 QueryWrapper导致“Unknown column”。我的处理办法是把虚拟字段集中放在实体类底部一个单独的注释块里并且命名上做统一约定比如统计类字段用 xxxCount、xxxTotal 开头临时标记用 xxxFlag这样看名字就能知道它们不是物理列。如果虚拟字段超过三四个我就会重新审视是不是应该拆一个 VO 出来了。下面把常见问题整理成一张对照表方便日常排查症状可能原因解决方式INSERT/UPDATE 报 Unknown column实体字段漏标 existfalse检查 SQL 日志给字段加注解写入后字段始终为 NULL表里有列却错标 existfalse检查注解移除 existfalseJSON 返回多余字段虚拟字段未加 JsonIgnore按需配置序列化注解删除变成物理删除TableLogic 字段误标 existfalse恢复物理列映射纠正注解乐观锁不生效Version 字段误标 existfalse恢复物理列映射纠正注解分页总数不准聚合 SQL 搭配分页插件子查询包一层调整 count 优化策略7. 我的选型建议什么时候用注解什么时候用 DTO/VO7.1 五条判断标准很多新手问到底“能不能用”其实不是技术能不能而是维护成本划不划算。我根据自己的项目经验总结出几条比较实用的判断标准额外字段小于等于两个并且只服务于当前实体的查询直接用 existfalse。额外字段要作为独立对象返回比如用户信息里嵌套一层收货地址就不要塞实体了建 VO。字段数量多或来源分散比如一个页面同时聚合订单、商品、用户三张表的数据DTO 是更清晰的选择。实体类已经有很多复杂注解比如多租户、逻辑删除、乐观锁再堆虚拟字段会让类很难读建议拆 DTO。接口返回的字段和实体字段差别很大需要隐藏或改造字段名这时候用 VO 更安全。7.2 三种方案的对比方案优点缺点适用场景TableField(existfalse)代码量少结果自动映射实体类不再纯净易滥用少量统计字段、临时标记、单实体查询扩展独立 DTO职责清晰不影响实体需要额外类字段拷贝繁琐跨表聚合、字段差异大、接口返回定制ResultMap 手动映射完全掌控列和属性对应关系XML 配置繁琐维护成本高查询关系很复杂的报表场景7.3 团队协作更看重一致性说到底用什么方案不是核心团队规范一致性才是。一个项目里最怕的是部分人往实体类里塞虚拟字段部分人坚持用 DTO结果代码风格割裂维护时反复切换上下文。我现在的项目组约定是实体类只保留与当前业务表强相关的虚拟字段且每个虚拟字段必须有清晰的注释跨模块、跨表的返回结构一律走 DTO。这条约定救了我们很多次至少在排查“某字段到底是数据库列还是内存字段”时看一眼注释就够了不用去数据库翻表结构。7.4 我实际操作中的体会最后再分享一点排查经验。遇到 MyBatis-Plus 相关 SQL 报错先不要急着百度报错信息第一步永远是看打印出来的 SQL 日志。通过 SQL 里实际的字段列表反推实体类中哪些字段被卷了进去。如果是 insert/update 报“Unknown column”十有八九是有属性忘了加 existfalse如果是查询字段一直为 null再检查是否错加了这个注解。配合 IDE 里字段的跳转和注释标记这类问题半小时内一定能定位完。这个小习惯帮我省下的时间比任何一行优雅代码都值钱。
