跳至主要內容

MyBatis Plus 实体注解

JustQ2025/11/30大约 5 分钟Java-learningJavaWebORMjavamybatisannotationormdatabasetutorialintermediate

MyBatis-Plus 常用注解笔记

📚 三大核心注解

MyBatis-Plus 中比较常用的几个注解：

1. @TableName

作用： 用来指定表名

使用场景： 当实体类名与数据库表名不一致时使用，默认是驼峰（实体类）转下划线（数据库表）

@TableName("tb_user")  // 指定数据库表名为 tb_user
public class User {
    // ...
}

注意：

  • 如果类名与表名一致（忽略大小写和下划线），可以不写
  • 例如：User 类对应 user 表，可以省略注解

2. @TableId

作用： 用来指定表中的主键字段信息

属性：

  • value：指定数据库主键字段名（默认为 id）
  • type：指定主键生成策略
@TableId(value = "id", type = IdType.AUTO)
private Long id;

IdType 枚举值详解

枚举值说明适用场景
AUTO数据库自增长数据库主键设置了 AUTO_INCREMENT
INPUT通过 set 方法自行输入手动设置主键值（程序员自己输入）
ASSIGN_ID分配 ID（雪花算法 nextId）分布式 ID 生成，默认策略
ASSIGN_UUID分配 UUID需要字符串类型主键

推荐使用：

  • 单体应用：IdType.AUTO（数据库自增）
  • 分布式应用：IdType.ASSIGN_ID（雪花算法，默认值）
// 数据库自增
@TableId(type = IdType.AUTO)
private Long id;

// 手动输入
@TableId(type = IdType.INPUT)
private Long id;

// 雪花算法（默认）
@TableId(type = IdType.ASSIGN_ID)
private Long id;

3. @TableField

作用： 用来指定表中的普通字段信息，默认是驼峰（实体类）转下划线（数据库表）

常用属性：

  • value：指定数据库字段名
  • exist：是否为数据库表字段（默认 true）
@TableField("username")  // 映射到数据库的 username 字段
private String name;

@TableField(exist = false)  // 标记为非数据库字段
private String address;

使用场景

场景1：成员变量名与数据库字段名不一致

@TableField("username")
private String name;  // Java 属性名是 name，数据库字段是 username

场景2：成员变量名以 is 开头，且是布尔值

@TableField("is_married")
private Boolean isMarried;  // 避免驼峰转换问题

因为会把is去掉，导致找不到对应字段。

场景3：成员变量名与数据库关键字冲突

@TableField("`order`")  // order 是 SQL 关键字，用反引号包裹
private Integer order;

场景4：成员变量不是数据库字段

@TableField(exist = false)
private String address;  // 这个字段不存在于数据库表中

看到这里差不多就够用了

💡 完整示例

实体类示例

package com.belnuan.entity;

import com.baomidou.mybatisplus.annotation.*;
import lombok.Data;
import java.time.LocalDateTime;

@Data
@TableName("tb_user")  // 表名：tb_user
public class User {
    
    // 主键：数据库自增
    @TableId(value = "id", type = IdType.AUTO)
    private Long id;
    
    // 普通字段：属性名与字段名不一致
    @TableField("username")
    private String name;
    
    // 普通字段：以 is 开头的布尔值
    @TableField("is_married")
    private Boolean isMarried;
    
    // 普通字段：与 SQL 关键字冲突
    @TableField("`order`")
    private Integer order;
    
    // 非数据库字段：仅在 Java 代码中使用
    @TableField(exist = false)
    private String address;
    
    // 以下字段使用驼峰自动转换，无需注解
    private String email;
    private Integer age;
    private LocalDateTime createTime;  // 自动映射到 create_time
    private LocalDateTime updateTime;  // 自动映射到 update_time
    
    // 逻辑删除字段
    @TableLogic
    private Integer deleted;
}

对应的数据库表

CREATE TABLE tb_user (
    id BIGINT PRIMARY KEY AUTO_INCREMENT COMMENT '主键',
    username VARCHAR(50) COMMENT '用户名',
    is_married BIT COMMENT '是否已婚',
    `order` TINYINT COMMENT '序号',
    email VARCHAR(100) COMMENT '邮箱',
    age INT COMMENT '年龄',
    create_time DATETIME COMMENT '创建时间',
    update_time DATETIME COMMENT '更新时间',
    deleted TINYINT DEFAULT 0 COMMENT '逻辑删除'
);

🎯 注解使用原则

什么时候需要使用注解？

@TableName

  • ✅ 需要使用：类名与表名不一致
    • 例如：User 类对应 tb_user 表
  • ❌ 不需要使用：类名与表名一致（忽略大小写和下划线）
    • 例如：User 类对应 user 表

@TableId

  • ✅ 需要使用：
    • 主键字段名不是 id
    • 需要指定主键生成策略（AUTO、INPUT 等）
  • ❌ 不需要使用：
    • 主键字段名是 id 且使用默认策略（ASSIGN_ID）

@TableField

  • ✅ 需要使用：
    • 属性名与字段名不一致
    • 属性名以 is 开头且是布尔值
    • 属性名与 SQL 关键字冲突
    • 属性不是数据库字段（exist = false）
  • ❌ 不需要使用：
    • 驼峰命名自动转换下划线
    • 例如：createTime 自动映射到 create_time

📋 其他常用注解

@TableLogic（逻辑删除）

@TableLogic
private Integer deleted;  // 0=未删除, 1=已删除

配置（application.yml）：

mybatis-plus:
  global-config:
    db-config:
      logic-delete-field: deleted
      logic-delete-value: 1
      logic-not-delete-value: 0

效果：

  • 删除操作变成更新：UPDATE user SET deleted = 1 WHERE id = 1
  • 查询自动过滤：SELECT * FROM user WHERE deleted = 0

@Version（乐观锁）

@Version
private Integer version;

配置插件：

@Configuration
public class MybatisPlusConfig {
    @Bean
    public MybatisPlusInterceptor mybatisPlusInterceptor() {
        MybatisPlusInterceptor interceptor = new MybatisPlusInterceptor();
        interceptor.addInnerInterceptor(new OptimisticLockerInnerInterceptor());
        return interceptor;
    }
}

效果：

  • 更新时自动检查版本号
  • UPDATE user SET name = ?, version = version + 1 WHERE id = ? AND version = ?

@EnumValue（枚举映射）

public enum StatusEnum {
    NORMAL(0, "正常"),
    DISABLED(1, "禁用");
    
    @EnumValue  // 标记为数据库存储的值
    private final int code;
    private final String desc;
    
    // 构造方法和 getter
}

// 实体类中使用
private StatusEnum status;

@TableField 的其他属性

// 查询时不返回该字段
@TableField(select = false)
private String password;

// 插入时自动填充
@TableField(fill = FieldFill.INSERT)
private LocalDateTime createTime;

// 更新时自动填充
@TableField(fill = FieldFill.UPDATE)
private LocalDateTime updateTime;

// 插入和更新时都自动填充
@TableField(fill = FieldFill.INSERT_UPDATE)
private String updateUser;

🎓 总结

核心注解速记

注解作用何时使用
@TableName指定表名类名与表名不一致
@TableId指定主键字段名不是 id 或需要设置生成策略
@TableField指定字段属性名与字段名不一致或特殊情况
@TableLogic逻辑删除需要逻辑删除功能
@Version乐观锁需要并发控制

注解使用口诀

表名不同加 TableName，主键策略 TableId 见
字段特殊 TableField 管，逻辑删除 Logic 伴
驼峰转换可省略，关键字冲突要标记
exist false 非表字段，注解使用要牢记

最佳实践

  1. ✅ 优先使用驼峰命名自动转换
  2. ✅ 只在必要时添加注解
  3. ✅ 主键优先使用 AUTO 或 ASSIGN_ID
  4. ✅ 逻辑删除统一使用 @TableLogic
  5. ✅ 非数据库字段必须标记 exist = false
默认页脚
Copyright © 2025 JustQ