SpringBoot项目实战：从零集成KingbaseES数据库与MyBatis-Plus

1. 环境准备与项目初始化

在开始集成KingbaseES之前，我们需要确保开发环境已经准备就绪。我建议使用IntelliJ IDEA作为开发工具，因为它对SpringBoot和Maven的支持非常友好。首先打开IDEA，选择"New Project"，然后选择"Spring Initializr"。这里有个小技巧：在Spring Boot版本选择上，建议使用2.7.x系列，因为这个版本对KingbaseES的兼容性经过了我的实测验证。

在依赖选择界面，我们需要勾选：

• Spring Web（用于构建Web应用）
• Lombok（简化实体类编写）
• MyBatis Framework（基础ORM支持）

这里有个容易踩坑的地方：不要直接选择MyBatis-Plus，因为我们需要手动控制MyBatis-Plus的版本。我在实际项目中遇到过自动生成的starter版本与KingbaseES不兼容的情况，后面会详细说明如何正确引入。

项目创建完成后，建议立即配置Maven的settings.xml文件。我在公司内网部署时发现，KingbaseES的JDBC驱动需要从私有仓库获取，所以需要在settings.xml中添加如下镜像配置：

<mirror> <id>kingbase-mirror</id> <name>KingbaseES Mirror</name> <url>http://your-mirror-url/repository/maven-public/</url> <mirrorOf>central</mirrorOf> </mirror>

2. KingbaseES驱动安装与配置

KingbaseES的JDBC驱动安装是个关键步骤。与MySQL不同，KingbaseES的驱动不能直接从Maven中央仓库获取。我通常的做法是先从官网下载最新的JDBC驱动jar包（目前最新是V8R6版本），然后手动安装到本地Maven仓库。这里分享一个实用命令：

mvn install:install-file \ -Dfile=kingbase8-8.6.0.jar \ -DgroupId=com.kingbase \ -DartifactId=kingbase8-jdbc \ -Dversion=8.6.0 \ -Dpackaging=jar

执行成功后，需要在pom.xml中添加依赖声明。特别注意版本号要与安装时保持一致：

<dependency> <groupId>com.kingbase</groupId> <artifactId>kingbase8-jdbc</artifactId> <version>8.6.0</version> </dependency>

在application.yml配置数据源时，我发现KingbaseES有几个特殊参数需要关注：

spring: datasource: driver-class-name: com.kingbase8.Driver url: jdbc:kingbase8://localhost:54321/TEST?currentSchema=public username: system password: 123456 hikari: connection-timeout: 30000 maximum-pool-size: 15

这里有个重要细节：url中的currentSchema参数。KingbaseES采用"数据库-模式-表"的三层结构，如果不指定schema，默认会使用用户名作为schema名，这经常导致"表不存在"的错误。我在三个项目中都踩过这个坑。

3. MyBatis-Plus深度集成

MyBatis-Plus的集成需要特别注意版本兼容性。经过多次测试，我发现3.5.3.1版本与KingbaseES的兼容性最好。在pom.xml中添加如下依赖：

<dependency> <groupId>com.baomidou</groupId> <artifactId>mybatis-plus-boot-starter</artifactId> <version>3.5.3.1</version> </dependency> <dependency> <groupId>com.baomidou</groupId> <artifactId>mybatis-plus-generator</artifactId> <version>3.5.3.1</version> </dependency>

配置MyBatis-Plus时，需要特别处理KingbaseES的分页插件。与MySQL不同，KingbaseES使用ROWNUM实现分页：

@Configuration public class MybatisPlusConfig { @Bean public MybatisPlusInterceptor mybatisPlusInterceptor() { MybatisPlusInterceptor interceptor = new MybatisPlusInterceptor(); // KingbaseES分页插件 interceptor.addInnerInterceptor(new PaginationInnerInterceptor(DbType.KINGBASE_ES)); return interceptor; } }

实体类映射时，必须明确指定schema。这是我推荐的最佳实践：

@Data @TableName(value = "user", schema = "public") public class User { @TableId(type = IdType.AUTO) private Long id; private String username; private Integer age; }

4. 常见问题排查与性能优化

在实际开发中，我总结了几个高频问题及其解决方案：

问题1：连接超时报错信息通常为"Connection timed out"。这往往是因为KingbaseES默认监听54321端口，但防火墙可能阻止了该端口。解决方法：

1. 检查KingbaseES服务是否启动
2. 使用telnet测试端口连通性
3. 在KingbaseES的data目录下的kingbase.conf中修改监听端口

问题2：SQL语法不兼容KingbaseES虽然兼容PostgreSQL，但仍有差异。例如批量插入语句需要调整为：

INSERT INTO user(username, age) VALUES ('张三', 18), ('李四', 20)

性能优化建议：

1. 在application.yml中配置连接池参数：

spring: datasource: hikari: minimum-idle: 5 maximum-pool-size: 15 idle-timeout: 30000 max-lifetime: 1800000

2. 为常用查询字段添加索引。KingbaseES创建索引的语法示例：

CREATE INDEX idx_username ON public.user (username);

3. 在复杂查询中使用EXPLAIN分析执行计划，KingbaseES的解释计划输出格式与MySQL不同，需要特别注意

5. 代码生成器实战配置

MyBatis-Plus的代码生成器能极大提升开发效率。这是我优化过的KingbaseES专用配置：

public class CodeGenerator { public static void main(String[] args) { FastAutoGenerator.create("jdbc:kingbase8://localhost:54321/TEST", "system", "123456") .globalConfig(builder -> { builder.author("yourname") .outputDir(System.getProperty("user.dir") + "/src/main/java"); }) .packageConfig(builder -> { builder.parent("com.example") .moduleName("demo") .entity("entity") .service("service") .serviceImpl("service.impl") .mapper("mapper") .xml("mapper.xml"); }) .strategyConfig(builder -> { builder.addInclude("user", "department") .entityBuilder() .enableLombok() .tablePrefix("t_") .columnNaming(NamingStrategy.underline_to_camel) .controllerBuilder() .enableRestStyle(); }) .templateConfig(builder -> { builder.disable(TemplateType.CONTROLLER); }) .injectionConfig(builder -> { builder.beforeOutputFile((tableInfo, objectMap) -> { System.out.println("生成表:" + tableInfo.getEntityName()); }); }) .execute(); } }

特别注意：

1. 生成的Mapper接口需要添加@Mapper注解
2. KingbaseES的主键策略建议使用IdType.INPUT
3. 生成的XML文件需要手动检查schema是否正确

6. 事务管理与高级特性

KingbaseES的事务处理与MySQL有显著差异。在SpringBoot中配置事务时，需要特别注意：

@Service @Transactional(rollbackFor = Exception.class) public class UserServiceImpl implements UserService { @Override @Transactional(propagation = Propagation.REQUIRES_NEW) public void batchInsert(List<User> users) { // KingbaseES批量操作建议使用JDBC模式 String sql = "INSERT INTO public.user(username, age) VALUES(?,?)"; jdbcTemplate.batchUpdate(sql, new BatchPreparedStatementSetter() { @Override public void setValues(PreparedStatement ps, int i) throws SQLException { ps.setString(1, users.get(i).getUsername()); ps.setInt(2, users.get(i).getAge()); } @Override public int getBatchSize() { return users.size(); } }); } }

对于存储过程调用，KingbaseES的语法比较特殊：

@Select("call public.sp_get_user_by_age(#{age}, #{result, mode=OUT, jdbcType=CURSOR})") @Options(statementType = StatementType.CALLABLE) Map<String, Object> callUserProcedure(@Param("age") Integer age);

在项目后期，我建议启用KingbaseES的SQL审计功能。这需要在kingbase.conf中添加配置：

audit_enabled = on audit_operation_type = ALL audit_user = system