1. 问题引入：一个看似简单的配置，为何频频“失联”？

最近在项目里用MyBatis-Plus对接Oracle数据库，遇到了一个挺典型的问题：明明按照文档配置了序列生成器，但插入数据时，主键ID死活不走序列，要么报错，要么就是默认值。这问题乍一看像是配置没生效，但深究下去，你会发现它牵扯到MyBatis-Plus的ID生成策略、Oracle序列的特性以及两者结合时的一些“潜规则”。我花了点时间，把这个问题从现象到根因，再到解决方案彻底捋了一遍。如果你也正在或即将在Oracle环境下使用MyBatis-Plus，这篇踩坑实录或许能帮你省下不少调试时间。

简单来说，MyBatis-Plus提供了@KeySequence注解和IKeyGenerator接口来支持像Oracle序列这类数据库序列的主键生成。但在Oracle上，直接套用模板常常会失灵。核心矛盾点在于：MyBatis-Plus默认的ID生成策略（如ASSIGN_ID，雪花算法）与Oracle序列的调用方式之间存在“认知偏差”。你的配置可能没错，但框架的默认行为在Oracle这儿需要一些额外的“沟通”。

2. 问题现象与根因深度剖析

2.1 典型症状：配置了，但没完全生效

当你遇到这个问题时，通常会有以下几种表现：

1. 插入报错：最常见的错误是“ORA-01400: 无法将 NULL 插入……”，这明确告诉你，主键字段接收到了NULL值，序列根本没被调用。
2. 主键为默认值或固定值：如果你的实体类主键字段有默认值（比如private Long id = 0L;），或者数据库字段设置了默认值，插入后主键就是这个默认值，而不是预期的序列下一个值。
3. 日志无序列调用痕迹：打开MyBatis的SQL日志，你会发现生成的INSERT语句中，主键字段要么是空的，要么是一个固定的参数值，看不到类似SELECT your_seq.NEXTVAL FROM dual这样的语句。

这些现象都指向同一个结论：MyBatis-Plus的ID生成器没有按预期工作，实体对象在进入SQL执行环节前，其主键字段id的值是null或一个无效值。

2.2 三层根因：策略、注解与执行顺序

问题的根源不是单一的，而是由几个层面叠加造成的。

第一层：全局ID类型策略的“霸权”在MyBatis-Plus中，有一个全局配置项id-type。如果你在application.yml或配置类中通过MybatisPlusProperties设置了id-type: ASSIGN_ID（这是3.x版本后的默认值），那么它会为所有实体设置一个默认的ID生成策略。ASSIGN_ID使用的是雪花算法，它会在Java代码中直接生成一个Long类型的ID，完全不会去查询数据库序列。这是导致Oracle序列失效的最常见原因。框架的全局策略优先级很高，它会覆盖或干扰你针对单个实体设置的序列注解。

第二层：@KeySequence注解的“局限性”@KeySequence注解用于声明实体类使用的序列名。但这里有个关键点：这个注解本身并不负责执行SELECT sequence.NEXTVAL。它只是一个“声明”，告诉MyBatis-Plus：“我这个实体要用某个序列”。真正去数据库取值的动作，需要由一个实现了IKeyGenerator接口的生成器来完成。如果你只加了@KeySequence，但没有配套正确的生成器，它就只是一个无用的标记。

第三层：Oracle序列生成器的“执行时机”MyBatis-Plus内置了OracleKeyGenerator，它就是那个负责执行SELECT seq.NEXTVAL FROM dual的类。但它的执行有严格的条件：仅在插入操作执行前，且实体的主键字段值为null时触发。这里有两个陷阱：

1. 如果你的全局ID策略（如ASSIGN_ID）抢先给主键赋了一个值（比如雪花ID），那么主键字段就不为null了，OracleKeyGenerator就会跳过执行。
2. 即使主键为null，OracleKeyGenerator也需要被正确配置和关联到你的实体上。默认情况下，它可能没有被激活或关联。

注意：很多人以为加了@KeySequence注解就万事大吉，其实这只是完成了“挂号”，真正“看病取药”（执行序列查询）还需要另一个步骤。

3. 解决方案：从全局配置到自定义生成器

解决这个问题需要一套组合拳，根据你的场景选择最适合的方案。下面我从易到难，给出四种经过验证的解决方案。

3.1 方案一：调整全局ID类型策略（推荐，最简洁）

这是解决大多数情况的首选方法。既然默认的ASSIGN_ID（或ASSIGN_UUID）会干扰序列，我们就把全局策略设置为“无”，将生成权完全下放给数据库或具体的生成器。

在application.yml中配置：

mybatis-plus: global-config: db-config: id-type: auto # 关键！设置为auto，或者直接注释掉id-type配置

将id-type设置为auto，或者干脆不配置这个选项。auto是一个“智能”模式，MyBatis-Plus会根据数据库类型和配置尝试选择策略。对于配置了@KeySequence的实体，它会倾向于使用对应的序列生成器。

同时，在实体类上正确使用注解：

import com.baomidou.mybatisplus.annotation.IdType; import com.baomidou.mybatisplus.annotation.KeySequence; import com.baomidou.mybatisplus.annotation.TableId; import com.baomidou.mybatisplus.annotation.TableName; @KeySequence("SEQ_USER_ID") // 声明使用Oracle中名为SEQ_USER_ID的序列 @TableName("sys_user") public class User { // 这里IdType必须设置为INPUT // INPUT表示这个ID由用户输入（实际上是由KeyGenerator在执行前输入） @TableId(value = "id", type = IdType.INPUT) private Long id; private String name; // ... 其他字段和getter/setter }

关键点解析：

1. @KeySequence("SEQ_USER_ID")：指定序列名，必须和Oracle数据库中创建的序列名完全一致。
2. @TableId(type = IdType.INPUT)：这是灵魂所在。IdType.INPUT意味着MyBatis-Plus不会自动生成ID，而是期望你在执行插入前，自己（或通过生成器）设置好ID值。OracleKeyGenerator正是在INPUT类型下，在插入前这个时机被调用，去查询序列并设置ID。

验证：完成上述配置后，执行插入操作。查看MyBatis日志，你应该能看到类似下面的SQL：

==> Preparing: INSERT INTO sys_user ( id, name ) VALUES ( ?, ? ) ==> Parameters: 125(Long), 张三(String)

并且在INSERT之前，会有一次序列查询：

==> Preparing: SELECT SEQ_USER_ID.NEXTVAL FROM dual ==> Parameters: <== Columns: NEXTVAL <== Row: 125

看到这个，就说明序列生成器成功生效了。

3.2 方案二：使用@TableId的type = IdType.ASSIGN_ID并配合全局配置（特定场景）

在某些老版本或特定需求下，你可能希望保持全局策略为ASSIGN_ID，但又想让某个特定实体使用序列。这需要更精细的控制。

实体类配置：

@KeySequence("SEQ_ORDER_ID") @TableName("biz_order") public class Order { // 这里仍然使用ASSIGN_ID，但结合@KeySequence，行为会有所不同 @TableId(value = "id", type = IdType.ASSIGN_ID) private Long id; // ... }

全局配置类（Java Config）：

@Configuration public class MybatisPlusConfig { @Bean public MybatisPlusPropertiesCustomizer plusPropertiesCustomizer() { return properties -> { GlobalConfig globalConfig = properties.getGlobalConfig(); DbConfig dbConfig = globalConfig.getDbConfig(); // 注册一个KeyGenerator，将其与IdType.ASSIGN_ID关联（此方法不一定所有版本都有效，需测试） // 更可靠的做法是使用下一个方案：自定义生成器 }; } }

方案评价：这个方案比较“玄学”，依赖于MyBatis-Plus内部对@KeySequence和IdType.ASSIGN_ID共存的处理逻辑，不同版本行为可能不一致。在3.4.x之后的版本中，这种组合可能无法直接触发序列查询。不推荐作为首选，除非你明确测试过在你的版本中有效。

3.3 方案三：自定义KeyGenerator（最灵活，最强大）

当你需要更复杂的序列逻辑（比如根据分表规则选择不同序列、在序列值前后拼接前缀等）时，自定义生成器是终极武器。

第一步：实现自定义序列生成器

import com.baomidou.mybatisplus.core.incrementer.IdentifierGenerator; import org.springframework.stereotype.Component; import javax.annotation.Resource; import javax.sql.DataSource; import java.sql.Connection; import java.sql.PreparedStatement; import java.sql.ResultSet; @Component // 注册为Spring Bean public class OracleSequenceGenerator implements IdentifierGenerator { @Resource private DataSource dataSource; @Override public Number nextId(Object entity) { // 在实际项目中，你可以通过entity的类信息，决定使用哪个序列 String sequenceName = "SEQ_DEFAULT"; // 默认序列 if (entity instanceof User) { sequenceName = "SEQ_USER_ID"; } else if (entity instanceof Order) { sequenceName = "SEQ_ORDER_ID"; } // 调用自定义方法获取序列值 return getNextSequenceValue(sequenceName); } @Override public String nextUUID(Object entity) { // 如果不是数字ID，可以在这里实现UUID逻辑 return null; // 本例不涉及 } private Long getNextSequenceValue(String sequenceName) { String sql = "SELECT " + sequenceName + ".NEXTVAL FROM dual"; try (Connection conn = dataSource.getConnection(); PreparedStatement pstmt = conn.prepareStatement(sql); ResultSet rs = pstmt.executeQuery()) { if (rs.next()) { return rs.getLong(1); } } catch (Exception e) { throw new RuntimeException("获取序列[" + sequenceName + "]失败", e); } throw new RuntimeException("获取序列[" + sequenceName + "]无结果"); } }

第二步：实体类配置此时，实体类可以简化，甚至不需要@KeySequence（因为序列名在生成器里动态决定了）。但为了清晰，可以保留注解作为文档。

// @KeySequence 注解可以保留，但生成器逻辑以自定义类为准 @TableName("sys_user") public class User { // IdType 设置为 ASSIGN_ID，框架会优先使用自定义的IdentifierGenerator @TableId(value = "id", type = IdType.ASSIGN_ID) private Long id; // ... }

第三步：配置全局使用自定义生成器（可选）在配置类中，可以声明默认使用你的自定义生成器。

@Configuration public class MybatisPlusConfig { @Resource private OracleSequenceGenerator oracleSequenceGenerator; @Bean public IdentifierGenerator identifierGenerator() { // 返回自定义生成器，使其成为全局默认生成器 return oracleSequenceGenerator; } }

方案优势：

• 完全掌控：你可以实现任何复杂的序列生成逻辑。
• 解耦：序列名管理在Java代码中，不硬编码在实体注解里。
• 兼容性好：不受全局id-type和默认生成器行为的限制。

实操心得：自定义生成器虽然代码量稍多，但在多租户、分库分表等复杂场景下几乎是必选项。建议在项目初期就评估是否需要这种灵活性。

3.4 方案四：检查与排查清单（当以上方案都不行时）

如果试了以上方法还是不行，请按照以下清单逐一核对：

1. 数据库序列是否存在且有权访问：

   • 登录Oracle，执行SELECT * FROM user_sequences WHERE sequence_name = 'SEQ_USER_ID';确认序列存在。
   • 确认应用连接数据库的用户有该序列的SELECT权限。

2. MyBatis-Plus版本兼容性：

   • 检查mybatis-plus-boot-starter的版本。一些老版本（如3.0.x）对Oracle序列的支持有bug。建议升级到3.4.0以上稳定版本。

3. 实体类主键字段名与数据库列名映射：

   • 确保@TableId(value = "id")中的value与数据库表的主键列名一致。大小写敏感问题在Oracle中尤其要注意（通常Oracle默认大写）。

4. 是否启用了MyBatis-Plus的元数据自动填充：

   • 检查是否有其他拦截器或插件（如MetaObjectHandler）在插入前修改了实体，错误地给id字段赋了值。

5. 日志级别：

   • 将MyBatis的日志级别调到DEBUG，查看完整的SQL执行过程。这是定位问题的利器。

   logging: level: com.baomidou.mybatisplus: DEBUG com.your.mapper.package: DEBUG # 你的Mapper接口所在包

4. 高级话题与最佳实践

4.1 序列缓存与性能考量

Oracle序列有一个CACHE参数，用于预分配和缓存序列值到内存，这能极大提升高并发下的获取性能。在创建序列时，可以考虑设置一个合理的缓存大小。

CREATE SEQUENCE SEQ_USER_ID START WITH 1 INCREMENT BY 1 CACHE 20 NOCYCLE;

CACHE 20意味着Oracle会一次性在内存中缓存20个序列值。当应用请求下一个值时，直接从内存获取，速度极快。缓存用完后，Oracle会自动再获取下一批20个值。这减少了访问数据字典的次数。

注意事项：CACHE设置过大，在数据库实例重启时，会丢失缓存中未使用的序列值，导致序列号出现“断层”（不连续）。对于严格要求连续主键的业务（如发票号），可以使用NOCACHE，但会牺牲性能。需要根据业务容忍度做权衡。

4.2 在分布式环境下的思考

在微服务或分布式系统中，多个服务实例同时操作同一张Oracle表，使用数据库序列仍然是生成全局唯一主ID的可靠方案之一，因为它由数据库中心化控制。

但需要注意：

• 性能瓶颈：所有实例都通过查询同一个序列来获取ID，数据库可能成为瓶颈。确保数据库连接池和序列缓存设置合理。
• 替代方案：如果对性能要求极高，且可以接受不严格连续，可以考虑使用“号段模式”或“改良的雪花算法（如美团的Leaf）”。号段模式是每次从数据库获取一个号段范围（如1-1000），应用在内存中分配，用完了再取，减少了数据库交互次数。

4.3 常见陷阱：@KeySequence的clazz属性

@KeySequence注解有一个clazz属性，用于指定返回序列值的类型，例如@KeySequence(value = “SEQ_USER_ID”, clazz = Long.class)。在大多数情况下，MyBatis-Plus可以自动推断类型，但如果你遇到类型转换异常（如将BigDecimal转为Long出错），显式指定clazz属性可以解决问题。Oracle的NEXTVAL返回的是Decimal类型，指定为Long.class可以确保框架进行正确的类型转换。

5. 总结与最终建议

回顾整个问题，MyBatis-Plus的Oracle序列生成器“不生效”，本质上是一个配置组合和优先级问题。其解决路径非常清晰：

1. 首选方案（适用于90%场景）：全局id-type设为auto或none，实体类使用@KeySequence+@TableId(type = IdType.INPUT)。这是最符合框架设计初衷、最稳定的方式。
2. 灵活方案（需要复杂逻辑）：实现自定义的IdentifierGenerator。将序列生成逻辑收拢在自己手中，便于实现定制化需求，如分表序列、带前缀的ID等。
3. 务必检查：数据库序列权限、MyBatis-Plus版本、字段映射和SQL日志。日志是调试此类问题的生命线。

最后，我个人在实际项目中的体会是，对于Oracle这类强依赖序列的数据库，在项目启动时就应该明确主键生成策略，并在团队内形成规范。不要等到各个模块开发完了，才发现生成策略混乱。统一采用上述“首选方案”，并在一个公共的“BaseEntity”中定义好@TableId(type = IdType.INPUT)，可以让所有实体类保持一致，避免很多不必要的麻烦。如果后续真有特殊需求，再通过自定义生成器进行局部覆盖，这样既能保证大部分场景的简洁，又能保留系统的扩展性。