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 典型症状配置了但没完全生效当你遇到这个问题时通常会有以下几种表现插入报错最常见的错误是“ORA-01400: 无法将 NULL 插入……”这明确告诉你主键字段接收到了NULL值序列根本没被调用。主键为默认值或固定值如果你的实体类主键字段有默认值比如private Long id 0L;或者数据库字段设置了默认值插入后主键就是这个默认值而不是预期的序列下一个值。日志无序列调用痕迹打开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时触发。这里有两个陷阱如果你的全局ID策略如ASSIGN_ID抢先给主键赋了一个值比如雪花ID那么主键字段就不为null了OracleKeyGenerator就会跳过执行。即使主键为nullOracleKeyGenerator也需要被正确配置和关联到你的实体上。默认情况下它可能没有被激活或关联。注意很多人以为加了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 }关键点解析KeySequence(SEQ_USER_ID)指定序列名必须和Oracle数据库中创建的序列名完全一致。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 ConfigConfiguration 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 方案四检查与排查清单当以上方案都不行时如果试了以上方法还是不行请按照以下清单逐一核对数据库序列是否存在且有权访问登录Oracle执行SELECT * FROM user_sequences WHERE sequence_name SEQ_USER_ID;确认序列存在。确认应用连接数据库的用户有该序列的SELECT权限。MyBatis-Plus版本兼容性检查mybatis-plus-boot-starter的版本。一些老版本如3.0.x对Oracle序列的支持有bug。建议升级到3.4.0以上稳定版本。实体类主键字段名与数据库列名映射确保TableId(value id)中的value与数据库表的主键列名一致。大小写敏感问题在Oracle中尤其要注意通常Oracle默认大写。是否启用了MyBatis-Plus的元数据自动填充检查是否有其他拦截器或插件如MetaObjectHandler在插入前修改了实体错误地给id字段赋了值。日志级别将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序列生成器“不生效”本质上是一个配置组合和优先级问题。其解决路径非常清晰首选方案适用于90%场景全局id-type设为auto或none实体类使用KeySequenceTableId(type IdType.INPUT)。这是最符合框架设计初衷、最稳定的方式。灵活方案需要复杂逻辑实现自定义的IdentifierGenerator。将序列生成逻辑收拢在自己手中便于实现定制化需求如分表序列、带前缀的ID等。务必检查数据库序列权限、MyBatis-Plus版本、字段映射和SQL日志。日志是调试此类问题的生命线。最后我个人在实际项目中的体会是对于Oracle这类强依赖序列的数据库在项目启动时就应该明确主键生成策略并在团队内形成规范。不要等到各个模块开发完了才发现生成策略混乱。统一采用上述“首选方案”并在一个公共的“BaseEntity”中定义好TableId(type IdType.INPUT)可以让所有实体类保持一致避免很多不必要的麻烦。如果后续真有特殊需求再通过自定义生成器进行局部覆盖这样既能保证大部分场景的简洁又能保留系统的扩展性。