一、核心概念

MyBatis-Plus 实体类通过注解映射数据库字段，代码生成器可自动添加这些注解：

注解 作用
@TableId 标识主键字段（可指定生成策略）
@TableField 标识普通字段（可设置填充、条件、自动转驼峰等）
@TableName 标识表名（类级别）
@Version 乐观锁字段（需配合配置）
@TableLogic 逻辑删除字段（需配合配置）

注解生成逻辑

代码生成器根据数据库元信息（字段名、主键、类型等）和策略配置，自动判断并生成对应注解：

  • 主键字段 → @TableId
  • 普通字段 → @TableField
  • 逻辑删除字段 → @TableLogic
  • 乐观锁字段 → @Version
  • 非数据库字段 → @TableField(exist = false)

二、操作步骤（超详细）

第一步：准备数据库表结构

CREATE TABLE `user` (
  `id` BIGINT NOT NULL AUTO_INCREMENT COMMENT '主键ID',
  `name` VARCHAR(30) DEFAULT NULL COMMENT '姓名',
  `age` INT DEFAULT NULL COMMENT '年龄',
  `email` VARCHAR(50) DEFAULT NULL COMMENT '邮箱',
  `create_time` DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
  `update_time` DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
  `deleted` TINYINT DEFAULT 0 COMMENT '逻辑删除 0-未删 1-已删',
  `version` INT DEFAULT 1 COMMENT '版本号',
  PRIMARY KEY (`id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

第二步：添加依赖

确保 pom.xml 包含：

<dependencies>
    <dependency>
        <groupId>com.baomidou</groupId>
        <artifactId>mybatis-plus-boot-starter</artifactId>
        <version>3.5.6</version>
    </dependency>
    <dependency>
        <groupId>com.baomidou</groupId>
        <artifactId>mybatis-plus-generator</artifactId>
        <version>3.5.6</version>
    </dependency>
    <dependency>
        <groupId>org.projectlombok</groupId>
        <artifactId>lombok</artifactId>
        <optional>true</optional>
    </dependency>
</dependencies>

第三步：编写代码生成器

import com.baomidou.mybatisplus.generator.FastAutoGenerator;
import com.baomidou.mybatisplus.generator.config.rules.NamingStrategy;

public class CodeGenerator {

    public static void main(String[] args) {
        generate();
    }

    private static void generate() {
        FastAutoGenerator.create(
                "jdbc:mysql://localhost:3306/demo?useUnicode=true&characterEncoding=utf8&useSSL=false&serverTimezone=GMT%2B8",
                "root",
                "password"
            )
            .globalConfig(builder -> {
                builder.author("Your Name")
                       .outputDir(System.getProperty("user.dir") + "/src/main/java");
            })
            .packageConfig(builder -> {
                builder.parent("com.example.demo")
                       .moduleName("system")
                       .entity("entity");
            })
            .strategyConfig(builder -> {
                // 实体策略配置
                builder.entityBuilder()
                       .naming(NamingStrategy.underline_to_camel)           // 表字段转驼峰
                       .columnNaming(NamingStrategy.underline_to_camel)     // 字段名转驼峰
                       .enableLombok()                                      // 启用 Lombok
                       .enableTableFieldAnnotation()                        // 开启 @TableField 注解
                       .logicDeleteColumnName("deleted")                    // 逻辑删除字段
                       .versionColumnName("version")                        // 乐观锁字段
                       .addTableFills("create_time", "update_time")         // 自动填充字段
                       .idGeneratorType(com.baomidou.mybatisplus.generator.config.rules.IdGenerator.AUTO) // 主键策略
                       .formatName("%sDO");                                  // 实体类命名后缀

                // 指定表
                builder.addInclude("user");
            })
            .execute();
    }
}

第四步：运行并查看生成的实体类

生成的 UserDO.java 如下：

package com.example.demo.system.entity;

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

@Data
@TableName("user")
public class UserDO {

    /**
     * 主键ID
     */
    @TableId(value = "id", type = IdType.AUTO)
    private Long id;

    /**
     * 姓名
     */
    @TableField("name")
    private String name;

    /**
     * 年龄
     */
    @TableField("age")
    private Integer age;

    /**
     * 邮箱
     */
    @TableField("email")
    private String email;

    /**
     * 创建时间
     */
    @TableField(fill = FieldFill.INSERT)
    private LocalDateTime createTime;

    /**
     * 更新时间
     */
    @TableField(fill = FieldFill.INSERT_UPDATE)
    private LocalDateTime updateTime;

    /**
     * 逻辑删除
     */
    @TableLogic
    @TableField("deleted")
    private Integer deleted;

    /**
     * 版本号
     */
    @Version
    @TableField("version")
    private Integer version;
}

三、常见错误与解决方案

错误现象 原因 解决方案
@TableField 未生成 未调用 .enableTableFieldAnnotation() 添加该配置
主键未加 @TableId 数据库表无主键或未识别 确保表有主键
逻辑删除注解未生成 未设置 logicDeleteColumnName 在 entityBuilder 中指定
乐观锁注解未生成 未设置 versionColumnName 在 entityBuilder 中指定
自动填充未生成 未调用 addTableFills 添加需填充的字段
字段名未转驼峰 未设置 naming/columnNaming 设置 underline_to_camel

四、注意事项

  1. ✅ 主键必须存在：数据库表必须定义主键，否则无法生成 @TableId。
  2. ✅ 字段名一致性：建议数据库使用下划线命名，Java 使用驼峰命名。
  3. ✅ 逻辑删除字段类型：推荐使用 tinyint(1) 或 int，值为 0/1。
  4. ✅ 版本号字段：必须为 Integer 或 Long 类型，初始值建议为 1。
  5. ✅ 自动填充字段：需配合 MetaObjectHandler 实现填充逻辑。
  6. ✅ exist = false：Java 类中存在但数据库不存在的字段需加 @TableField(exist = false)。
  7. ✅ ** transient 字段**：不希望被 MyBatis 处理的字段可加 transient 或 @TableField(select = false)。

五、使用技巧

1. 自定义主键生成策略

.idGeneratorType(IdGenerator.NONE)        // 无（由用户输入）
.idGeneratorType(IdGenerator.AUTO)       // 数据库自增
.idGeneratorType(IdGenerator.ASSIGN_ID)  // 雪花算法
.idGeneratorType(IdGenerator.ASSIGN_UUID)// UUID

2. 忽略特定字段生成注解

// 不生成该字段的 @TableField
@TableField(exist = false)
private String notInDbField;

// 不参与查询
@TableField(select = false)
private String password;

// 不参与插入/更新
@TableField(insertStrategy = FieldStrategy.NOT_NULL)
private String ignoreWhenNull;

3. 复合主键处理

MyBatis-Plus 不直接支持复合主键，可通过以下方式：

// 方式1：使用 @TableId 标记其中一个为主键（不推荐）
// 方式2：不设主键，手动处理
// 方式3：添加唯一ID字段作为主键（推荐）

4. 枚举类型映射

@TableName("user")
public class UserDO {
    @TableField("status")
    private UserStatus status; // 枚举
}

// 需配置 TypeHandler
mybatis-plus:
  type-handlers-package: com.example.handler

六、最佳实践与性能优化

✅ 最佳实践

实践 说明
✅ 统一命名规范 数据库下划线 → Java 驼峰
✅ 启用 Lombok 减少 getter/setter 代码
✅ 启用 @TableField 显式声明字段，避免隐式映射错误
✅ 逻辑删除代替物理删除 保障数据安全
✅ 乐观锁防止并发修改 尤其在订单、库存场景
✅ 自动填充创建/更新时间 避免手动设置
✅ 敏感字段脱敏 如密码、手机号加 @TableField(select = false)

⚡ 性能优化建议

  • ✅ **避免 SELECT ***：使用 @TableField(select = false)排除大字段（如content、image`）
  • ✅ 延迟加载：对大字段可考虑分表或延迟查询
  • ✅ 索引字段：在 @TableField 注释中注明索引，便于维护
  • ✅ 缓存优化：对频繁查询的实体，配合 @Cacheable 使用

七、高级配置：自定义模板控制注解生成

在 resources/templates/entity.java.vm 中：

#foreach($field in ${table.fields})
    #if(${field.keyFlag})
    /**
     * ${field.comment}
     */
    @TableId(value = "${field.name}" #if(${field.keyType} == "Auto") , type = IdType.AUTO #end)
    private ${field.propertyType} ${field.propertyName};
    #else
    /**
     * ${field.comment}
     */
    #if(${field.fill})@TableField(fill = FieldFill.${field.fill}) #end
    #if(${field.name} == "deleted")@TableLogic #end
    #if(${field.name} == "version")@Version #end
    @TableField("${field.name}")
    private ${field.propertyType} ${field.propertyName};
    #end
#end

总结

MyBatis-Plus 代码生成器能智能生成 @TableId、@TableField 等注解，极大提升开发效率。关键配置点：

  1. 启用注解：.enableTableFieldAnnotation()
  2. 逻辑删除：.logicDeleteColumnName("deleted")
  3. 乐观锁：.versionColumnName("version")
  4. 自动填充：.addTableFills("create_time", "update_time")
  5. 命名策略：.naming(NamingStrategy.underline_to_camel)

🚀 建议：生成后审查注解是否正确，特别是主键策略、逻辑删除、填充字段，并配合 MetaObjectHandler 实现自动填充逻辑。