当前位置： 首页 > news >正文

MyBatis-Plus 核心注解详解：从表映射到逻辑删除的全方位指南

news 2025/7/27 9:02:49

在使用 MyBatis-Plus 进行数据库操作时，我们会发现它通过一系列注解简化了传统 MyBatis 的 XML 配置，让 CRUD 操作变得更加高效。本文将详细解析 MyBatis-Plus 中最核心的几个注解（@TableName、@TableId、@TableField、@TableLogic），包括它们的使用场景、解决的问题以及实战示例，帮助你彻底掌握 MyBatis-Plus 的实体映射逻辑。

一、@TableName：实体与表的 "桥梁"

MyBatis-Plus 的 CRUD 操作默认以实体类名作为表名（如User实体对应user表），但实际开发中实体类名与表名往往不一致（如表名常加前缀t_）。@TableName注解正是为解决这一问题而生。

1.1 问题场景：实体类名与表名不一致

假设我们有一个User实体类，但数据库表名为t_user（而非默认的user）。此时执行查询操作会直接报错：

Table 'mybatis_plus.user' doesn't exist

原因是 MyBatis-Plus 默认将实体类名User映射为表名user，而实际表名为t_user，导致表不存在异常。

1.2 解决方案 1：使用 @TableName 注解

在实体类上添加@TableName注解，直接指定对应的表名：

// 实体类User映射到表t_user
@TableName("t_user")
public class User {private Long id;private String username;private Integer age;// 省略getter/setter
}

添加注解后，MyBatis-Plus 会自动将User实体的操作映射到t_user表，CRUD 操作可正常执行。

 

1.3 解决方案 2：全局配置表名前缀

如果项目中所有表都有固定前缀（如t_或tbl_），逐个添加@TableName会很繁琐。此时可通过全局配置统一设置表名前缀：

# application.yml
mybatis-plus:configuration:log-impl: org.apache.ibatis.logging.stdout.StdOutImpl # 打印SQL日志global-config:db-config:table-prefix: t_ # 所有实体类对应的表名自动添加前缀t_

配置后，User实体会自动映射到t_user表，Order实体映射到t_order表，无需再给每个实体添@TableName。

 

二、@TableId：主键映射的核心注解

MyBatis-Plus 默认将实体类中的id字段作为主键，但实际开发中主键字段可能不是id（如uid），或需要自定义主键生成策略。@TableId注解用于标识主键字段并配置相关策略。

2.1 问题场景：主键字段非 id

若实体类中主键字段为uid，表中主键字段也为uid，但未添加任何注解，执行插入操作时会报错：

Field 'uid' doesn't have a default value

原因是 MyBatis-Plus 未识别uid为主键，不会自动生成主键值，导致数据库因主键无默认值而拒绝插入。

 

2.2 解决方案：使用 @TableId 标识主键

在实体类的主键字段上添加@TableId注解，明确标识该字段为主键：

public class User {// 标识uid为主键@TableIdprivate Long uid; private String username;private Integer age;// 省略getter/setter
}

此时 MyBatis-Plus 会将uid作为主键处理，并自动生成主键值（默认使用雪花算法）。

 

 

2.3 @TableId 的 value 属性：解决主键名不一致

若实体类中主键字段为id，但表中主键字段为uid（字段名不一致），仅添加@TableId会报错：

Unknown column 'id' in 'field list'

原因是 MyBatis-Plus 仍会将id作为表中主键字段名。此时需通过value属性指定表中的主键字段名：

public class User {// 实体id对应表中uid字段@TableId(value = "uid") private Long id; private String username;private Integer age;
}

2.4 @TableId 的 type 属性：自定义主键策略

type属性用于指定主键生成策略，MyBatis-Plus 提供了多种策略，常用的有以下两种：

策略值描述
IdType.ASSIGN_ID基于雪花算法生成主键（默认策略），与数据库是否自增无关
IdType.AUTO使用数据库自增策略，需确保数据库表中主键已设置自增
示例：使用数据库自增策略
public class User {// 主键使用数据库自增策略@TableId(type = IdType.AUTO) private Long id; private String username;
}

需配合数据库表设置（主键自增）：

CREATE TABLE t_user (id BIGINT PRIMARY KEY AUTO_INCREMENT, -- 主键自增username VARCHAR(20)
);
全局配置主键策略

若项目中所有表都使用相同的主键策略（如全库自增），可通过全局配置统一设置：

mybatis-plus:global-config:db-config:id-type: auto # 全局使用数据库自增策略

 

2.5 深入理解：雪花算法（IdType.ASSIGN_ID）

雪花算法是 Twitter 开源的分布式主键生成算法，解决了分库分表场景下的主键唯一性问题，也是 MyBatis-Plus 的默认主键策略。

为什么需要雪花算法？

当数据量激增时，单表无法承载，需进行分库分表（将数据分散到多个表 / 库）。此时传统主键策略会失效：

  • 自增主键：不同表可能生成相同 id，导致全局不唯一；
  • 取模分片：扩容时需重新分布数据，成本极高。

雪花算法能生成全局唯一、有序的 id，完美适配分库分表场景。

雪花算法原理（64bit 长整型）

雪花算法生成的 id 为 64 位 long 型，结构如下：

位段长度（bit）作用
符号位1固定为 0（保证 id 为正数）
时间戳41存储当前时间与起始时间的差值（毫秒级），可支持约 69 年
机器 ID10包含 5 位数据中心 ID 和 5 位机器 ID，支持最多 1024 个节点部署
毫秒内序列号12同一毫秒内生成的序列号，每个节点每毫秒最多生成 4096 个 id
背景


需要选择合适的方案去应对数据规模的增长，以应对逐渐增长的访问压力和数据量。

        数据库的扩展方式主要包括：

                业务分库、主从复制，数据库分表。

分库：比如淘宝，VIP用户有一个库，普通用户一个库

主从复制：备份

分表：100万按照什么规则分表

数据库分表


将不同业务数据分散存储到不同的数据库服务器，能够支撑百万甚至千万用户规模的业务，但如果业务继续发展，同一业务的单表数据也会达到单台数据库服务器的处理瓶颈。例如，淘宝的几亿用户数据，  如果全部存放在一台数据库服务器的一张表中，肯定是无法满足性能要求的，此时就需要对单表数据进行拆分。

        单表数据拆分有两种方式：垂直分表和水平分表。示意图如下：

 

①垂直分表


垂直分表适合将表中某些不常用且占了大量空间的列拆分出去。

        例如，前面示意图中的 nickname 和 description 字段，假设我们是一个婚恋网站，用户在筛选其他用户的时候，主要是用 age 和 sex 两个字段进行查询，而 nickname 和 description 两个字段主要用于展 示， 一般不会在业务查询中用到。description 本身又比较长，因此我们可以将这两个字段独立到另外   一张表中，这样在查询 age 和 sex 时，就能带来一定的性能提升。

②水平分表


水平分表适合表行数特别大的表，有的公司要求单表行数超过 5000 万就必须进行分表，这个数字可以 作为参考，但并不是绝对标准，关键还是要看表的访问性能。对于一些比较复杂的表，可能超过 1000  万就要分表了；而对于一些简单的表，即使存储数据超过 1 亿行，也可以不分表。

        但不管怎样，当看到表的数据量达到千万级别时，作为架构师就要警觉起来，因为这很可能是架构的性能瓶颈或者隐患。

        水平分表相比垂直分表，会引入更多的复杂性，例如要求全局唯一的数据id该如何处理

主键自增


①以最常见的用户 ID 为例，可以按照 1000000 的范围大小进行分段，   1 ~ 999999 放到表 1中， 1000000 ~ 1999999 放到表2中，以此类推。

        因为是自动递增的，所以删除一条数据在增加，ID是后面的，会导致一个表里数据多，一个表少。服务器承受的力度不一样。（比如，第一个表删除5号ID，再新增，ID就是6，这样就会导致实际的表中没有那么多数据。那么管理这个表的服务器实际上只管理那么一点数据。）

        ②复杂点：分段大小的选取。

                分段太小会导致切分后子表数量过多，增加维护复杂度；

                分段太大可能会 导致单表依然存在性能问题，  

                一般建议分段大小在 100 万至 2000 万之间，具体需要根据业务选取合适 的分段大小。

        ③优点：可以随着数据的增加平滑地扩充新的表。例如，现在的用户是 100 万，如果增加到 1000 万， 只需要增加新的表就可以了，原有的数据不需要动。

        ④缺点：分布不均匀。假如按照 1000 万来进行分表，有可能某个分段实际存储的数据量只有 1 条，而 另外一个分段实际存储的数据量有 1000 万条。

取模


①同样以用户 ID 为例，假如我们一开始就规划了 10 个数据库表，可以简单地用 user_id % 10 的值来表示数据所属的数据库表编号，  ID 为 985 的用户放到编号为 5 的子表中，   ID 为 10086 的用户放到编号为 6 的子表中。

        ②复杂点：初始表数量的确定。表数量太多维护比较麻烦，表数量太少又可能导致单表性能存在问题。

        ③优点：表分布比较均匀。

        ④缺点：扩充新的表很麻烦，所有数据都要重分布。

雪花算法


前两种都是基于主键自增的。

        雪花算法是由Twitter公布的分布式主键生成算法，它能够保证不同表的主键的不重复性，以及相同表的 主键的有序性。

①核心思想：

        长度共64bit（一个long型）。

        首先是一个符号位，  1bit标识，由于long基本类型在Java中是带符号的，最高位是符号位，正数是0，负 数是1，所以id一般是正数，最高位是0。

        41bit时间截(毫秒级)，存储的是时间截的差值（当前时间截 - 开始时间截)，结果约等于69.73年。

        10bit作为机器的ID（ 5个bit是数据中心，  5个bit的机器ID，可以部署在1024个节点）。

        12bit作为毫秒内的流水号（意味着每个节点在每毫秒可以产生 4096 个 ID）。

 

②优点：整体上按照时间自增排序，并且整个分布式系统内不会产生ID碰撞，并且效率较高。

优点
  • 全局唯一：分布式系统中不会出现重复 id；
  • 有序性：按时间递增，利于数据库索引优化；
  • 高性能：本地生成，无需数据库交互，效率极高。

 

三、@TableField：解决属性与字段名不一致

MyBatis-Plus 默认要求实体类属性名与表中字段名一致，若不一致需通过@TableField注解手动映射。

3.1 场景 1：驼峰命名与下划线命名的自动转换

实体类中使用驼峰命名（如userName），表中使用下划线命名（如user_name）时，MyBatis-Plus 会自动转换（默认开启驼峰映射），无需额外配置。

示例：

 

public class User {@TableIdprivate Long id;private String userName; // 对应表中user_name字段private Integer age;
}

执行查询时生成的 SQL：

SELECT id, user_name, age FROM t_user

3.2 场景 2：属性与字段名完全不同

若实体类属性与表字段名无驼峰 / 下划线对应关系（如实体name对应表username），需通过@TableField指定字段名：

public class User {@TableIdprivate Long id;// 实体name对应表中username字段@TableField("username") private String name; private Integer age;
}

执行查询时生成的 SQL：

SELECT id, username, age FROM t_user

四、@TableLogic：实现逻辑删除

逻辑删除是指通过修改字段状态（而非物理删除数据）实现 "删除" 效果，便于数据恢复和审计。@TableLogic注解用于标识逻辑删除字段。

4.1 物理删除 vs 逻辑删除

  • 物理删除：直接从数据库删除数据，无法恢复；
  • 逻辑删除：仅修改数据的 "删除状态"（如is_deleted=1），数据仍在库中，可恢复。

4.2 实现逻辑删除的步骤

Step1：数据库添加逻辑删除字段

在表中添加一个标识删除状态的字段（如is_deleted），默认值为 0（未删除）：

ALTER TABLE t_user ADD COLUMN is_deleted INT DEFAULT 0 COMMENT '逻辑删除（0未删，1已删）';

 

Step2：实体类添加逻辑删除属性并注解

在实体类中添加对应字段，并使用@TableLogic标识：

public class User {@TableIdprivate Long id;private String username;private Integer age;// 逻辑删除字段（0未删，1已删）@TableLogic private Integer isDeleted; // 省略getter/setter
}

 

Step3：测试逻辑删除效果

  • 删除操作：执行删除时，MyBatis-Plus 会自动生成更新语句（而非删除语句）：

    @Autowired
private UserMapper userMapper;@Test
public void testLogicDelete() {userMapper.deleteById(1L); // 删除id=1的用户
}

    生成的 SQL：

    UPDATE t_user SET is_deleted=1 WHERE id=1 AND is_deleted=0

  • 查询操作：执行查询时，MyBatis-Plus 会自动过滤已删除数据（只查is_deleted=0的记录）：

    @Test
public void testSelect() {userMapper.selectList(null); // 查询所有用户
}

    生成的 SQL：

    SELECT id, username, age, is_deleted FROM t_user WHERE is_deleted=0

 

http://www.dtcms.com/a/299817.html

相关文章：

  • C++/CLI vs 标准 C++ vs C# 语法对照手册
  • 9.3 快速傅里叶变换
  • 深度解析 noisereduce：开源音频降噪库实践
  • 深入理解Redission释放锁过程
  • Blender入门笔记（一）
  • 利用RAII与析构函数避免C++资源泄漏
  • 基于DataX的数据同步实战
  • 中电建路桥集团有限公司重大项目管理办公室成立
  • 【安全漏洞】网络守门员：深入理解与应用iptables，守护Linux服务器安全
  • Linux 如何统计系统上各个用户登录（或者登出）记录出现的次数？
  • Ubuntu安装node-red
  • 磁悬浮轴承转子不平衡质量控制策略设计：原理、分析与智能实现
  • C/C++中常量放置在比较操作符左侧
  • 基于匿名管道的多进程任务池实现与FD泄漏解决方案
  • 消息缓存系统
  • Docker学习日志-Docker容器配置、Nginx 配置与文件映射
  • Vim 进阶教程
  • React入门学习——指北指南（第四节）
  • Spring核心：Bean生命周期、外部化配置与组件扫描深度解析
  • 龙迅#LT8711UXD适用于Type-C/DP1.4 /EDP转 HDMI2.0 功能,分辨率高达4K60HZ,可支持HDCP!
  • 01 01 02 第一部分 C++编程知识 C++入门 第一个C++程序
  • 其他世界的自来水
  • 【图像理解进阶】如何在自己的数据集上释放segment anything模型方案的潜力？
  • 20250726-3-Kubernetes 网络-Service三种常用类型_笔记
  • 服务器被网络攻击后该如何进行处理？
  • “累”这一身体某部位的感觉可能较多来源于对局部血流阻力的感知
  • 教育培训系统源码解析：如何打造高可扩展的在线学习平台？
  • 疏老师-python训练营-Day26函数专题1：函数定义与参数
  • Dify开发教程笔记(一)： 文件及系统参数变量说明及使用
  • 【n8n教程笔记——工作流Workflow】文本课程（第一阶段）——5.3 过滤订单 (Filtering orders)