3.0.2 版本说明与已知限制
郭胜凯2026/08/17
本文档以 Smart MyBatis 主项目当前 3.0.2 源码为准。版本升级时应同时核对 POM、公开 API、示例工程和数据库集成测试，不能只替换依赖版本号。
3.x 主要能力
SqlDialects方言体系，内置 MySQL、H2、Oracle、DB2。selectWithRelations自动关联字段查询。- 嵌套
Where和Where.or(...)。 - JSON 字段 ResultMap 自动注入。
- AUTO 主键与批量插入回填适配。
@SmartMeta编译期实体元数据。- 初始化 SQL 脚本和方言化 DDL。
已知限制
selectTrees 尚未实现
SmartMapper.selectTrees(...) 当前会直接抛出运行时异常，不应在业务中使用。
INPUT 主键策略
3.0.2 的 BaseSqlProvider.generatePk 中，INPUT 分支会继续进入 UUID 分支，提供的主键可能被 UUID 覆盖。在修复发布前，不要依赖 INPUT 保留调用方传入值；需要手动主键时请使用明确的自定义 Mapper SQL 并添加回归测试。
TableField.value 字段名覆盖
3.0.2 的字段名解析会在读取 @TableField.value 后继续按全局 naming-convention 计算字段名，因此自定义列名覆盖目前不可靠。请优先让 Java 字段名与命名策略可推导到真实列名；遗留列名应通过原生 MyBatis 映射处理，直到该行为修复并发布。
自定义方言扫描包固定
DialectResolver 当前只扫描 ink.icoding.smartmybatis.mapper.provider.dialects.impl。自定义方言放在其他包不会被自动发现。
自动同步不是迁移工具
自动同步会创建表、添加缺失列，并可能根据类型或注释差异修改列；它不会删除列，也不提供版本历史、回滚、锁和数据迁移。生产环境请使用 Flyway、Liquibase 等方案。
MyBatis-Plus 混用
Starter 检测到 MyBatis-Plus 代理时会输出兼容性警告，并尝试转换为原生 MyBatis MapperProxy。两者同时替换 Mapper 代理可能产生未知行为，不建议在同一个 Mapper 上混用。
升级检查
- 确认 Java、Spring Boot、MyBatis 和数据库驱动版本。
- 确认启动日志选择了预期方言。
- 测试单条/批量插入和主键回填。
- 测试 JSON、枚举、关联和分页。
- 开启
auto-sync-db前审查生成 DDL。 - 搜索旧配置键
enable，替换为enabled。 - 搜索旧依赖版本和已移除的注解属性。