主键生成策略

引言

MyBatis-Plus 主键生成策略用于自动生成数据库表唯一主键，大幅简化主键赋值操作。

核心注解：@TableId（标记实体主键字段）
核心枚举：IdType（定义主键生成规则）
支持场景：数据库自增、雪花算法、UUID、数据库序列（Oracle/PostgreSQL）、自定义生成
版本特性：3.3.0 + 版本支持自动识别主键类型，无需手动指定

核心注解与枚举

主键注解 `@TableId`

标记实体类的主键字段，指定主键名和生成策略：

@TableId(value = "id", type = IdType.ASSIGN_ID)
private Long id;

value：数据库主键列名
type：主键生成策略（IdType 枚举）

主键策略枚举 `IdType`

MyBatis-Plus 内置 6 种主键策略，覆盖所有业务场景：

枚举值	含义	适用场景
`AUTO`	数据库 ID 自增	MySQL、SQL Server 等数据库自增主键
`NONE`	无状态（默认）	跟随全局配置，3.3.0 + 自动识别
`INPUT`	手动输入 ID	主键值由用户传入 / 数据库序列生成
`ASSIGN_ID`	分配 ID（默认）	雪花算法，生成 Long/String 类型全局唯一 ID
`ASSIGN_UUID`	分配 UUID	生成 String 类型唯一 UUID（不含横线）
`ID_WORKER`	分布式 ID（旧版）	已废弃，推荐 `ASSIGN_ID`
`ID_WORKER_STR`	字符串分布式 ID（旧版）	已废弃，推荐 `ASSIGN_ID`

主流主键生成策略

雪花算法（默认，首选）

3.3.0 + 默认策略，全局唯一，分布式场景通用，无需数据库配置：

@Data
public class User {
    // 雪花算法：自动生成 Long 类型主键
    @TableId(type = IdType.ASSIGN_ID)
    private Long id;
    private String name;
}

数据库自增

依赖数据库主键自增设置，适用于单库单表：

@Data
public class User {
    @TableId(type = IdType.AUTO)
    private Long id;
}

注意：数据库表必须设置 AUTO_INCREMENT

UUID 生成

String 类型主键，无规则唯一值：

@Data
public class User {
    @TableId(type = IdType.ASSIGN_UUID)
    private String id;
}

手动输入

主键值由业务代码手动赋值：

@Data
public class User {
    @TableId(type = IdType.INPUT)
    private Long id;
}

数据库序列生成策略

适用于 Oracle、DB2、PostgreSQL 等 依赖序列 的数据库，需配合 @KeySequence 使用。

内置序列生成器

MyBatis-Plus 内置主流数据库序列生成器：

DB2KeyGenerator
H2KeyGenerator
KingbaseKeyGenerator
OracleKeyGenerator
PostgreKeyGenerator

`@KeySequence` 注解

绑定数据库序列，指定主键类型：

import com.baomidou.mybatisplus.annotation.KeySequence;
import com.baomidou.mybatisplus.annotation.TableId;
import com.baomidou.mybatisplus.annotation.IdType;

// 绑定 Oracle 序列，主键类型为 String
@KeySequence(value = "SEQ_ORACLE_STRING_KEY", clazz = String.class)
@Data
public class YourEntity {
    // 序列生成必须使用 INPUT 类型
    @TableId(value = "ID_STR", type = IdType.INPUT)
    private String idStr;
}

全局配置主键策略

支持全局统一设置，无需每个实体单独配置 @TableId(type)

Spring Boot 配置（推荐）

方式 1：yml 配置文件

mybatis-plus:
  global-config:
    db-config:
      # 全局默认主键策略：雪花算法
      id-type: assign_id
      # 序列生成器（仅 Oracle/PostgreSQL 等需要）
      key-generator: com.baomidou.mybatisplus.extension.incrementer.OracleKeyGenerator

方式 2：配置类自定义

import com.baomidou.mybatisplus.autoconfigure.MybatisPlusPropertiesCustomizer;
import com.baomidou.mybatisplus.extension.incrementer.H2KeyGenerator;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class MyBatisPlusConfig {

    /**
     * 自定义全局配置
     */
    @Bean
    public MybatisPlusPropertiesCustomizer plusPropertiesCustomizer() {
        return plusProperties ->
            plusProperties.getGlobalConfig().getDbConfig()
                // 设置序列生成器
                .setKeyGenerator(new H2KeyGenerator())
                // 设置全局主键策略
                .setIdType(IdType.ASSIGN_ID);
    }

    /**
     * 单独注册序列生成器 Bean
     */
    @Bean
    public H2KeyGenerator keyGenerator() {
        return new H2KeyGenerator();
    }
}

自定义主键生成器

内置策略不满足需求时，实现 IKeyGenerator 接口扩展自定义生成规则：

import com.baomidou.mybatisplus.extension.incrementer.IKeyGenerator;
import org.springframework.stereotype.Component;

@Component
public class CustomIdGenerator implements IKeyGenerator {
    @Override
    public String executeSql(String incrementerName) {
        // 自定义主键生成 SQL/逻辑
        return "SELECT your_id_sequence.nextval FROM DUAL";
    }
}

优先级规则

实体 @TableId(type) > 全局配置
全局配置 > 默认策略（ASSIGN_ID 雪花算法）
3.3.0 + 版本：自动识别数据库主键类型，无需手动配置

注意事项

主键类型不匹配 雪花算法生成 Long 类型，数据库字段必须为 bigint
Oracle 序列报错 必须使用 IdType.INPUT + @KeySequence 组合
自增 ID 失效 数据库未开启 AUTO_INCREMENT，且策略配置为 AUTO
废弃 API 使用 禁止使用 ID_WORKER，统一使用 ASSIGN_ID
分布式场景 禁止使用数据库自增，推荐雪花算法 ASSIGN_ID

总结

核心选择：分布式项目用 ASSIGN_ID（雪花算法），单库项目用 AUTO（自增）
配置灵活：支持注解单独配置、全局统一配置
兼容全面：适配 MySQL、Oracle、PostgreSQL 等所有主流数据库
扩展便捷：可通过 IKeyGenerator 实现自定义主键生成