KingbaseES（电科金仓）是国产主流关系型数据库，广泛应用于政务、金融、国企等国产化场景。本文将手把手教你基于 SpringBoot 3.x + MyBatis-Plus 快速集成 KingbaseES 数据库，实现用户表的增、删、改、查基础功能，代码可直接复用至生产环境。

一、基本环境准备

环境准备：

1. 开发工具：IntelliJ IDEA
2. 框架版本：SpringBoot 3.x
3. 数据库：KingbaseES_V009R001C010B0004_x86_64_Docker.tar
4. JDK：17+（SpringBoot 3.x 要求）
5. 核心依赖：MyBatis-Plus、KingbaseES 驱动、Druid 连接池

1. 硬件要求

• 支持 X86_64、龙芯、飞腾、鲲鹏等架构

• 建议至少 2 核 4G 内存，10GB 可用磁盘空间

2. 软件要求

• Docker 版本 ≥ 20.10.0（推荐 24.x 稳定版）

小提示：使用 docker --version 快速确认当前版本。本文用docker 26.1.3进行实操记录！

3.创建数据目录

为了避免容器销毁后数据丢失，我们先在宿主机创建持久化目录：

mkdir -p /opt/kingbase/data
chmod -R 755 /opt/kingbase/data

小提示：建议统一放在 /opt 下，方便管理。

4.获取镜像包

你可以通过以下方式获取 KingbaseES 镜像：

1、官网下载：https://www.kingbase.com.cn/

2、入口位置：服务与支持 > 下载中 > KES，如下图所示：

3、KingbaseES数据库Docker镜像，根据自己电脑配置选择对应的版本下载。

点击下载会提示下载验证，输入相关信息后就可以下载啦！

如果有特殊需求镜像：

• 联系销售人员或代理商获取

• 内部项目提供（如涉密项目）

本文使用的是KingbaseES_V009R001C010B0004_x86_64_Docker.tar 镜像包，大小约 754MB。

5.导入镜像

1、将镜像包上传至 /opt/kingbase 目录下，这个目录可根据自身情况自定义，如下图：

2、将镜像包上传至 /opt/kingbase 目录后，执行导入：

docker load -i /opt/kingbase/KingbaseES_V009R001C010B0004_x86_64_Docker.tar

3、导入成功后，使用 docker images 查看：

REPOSITORY                                                                         TAG                                  IMAGE ID       CREATED         SIZE
kingbase_v009r001c010b0004_single_x86                                              v1                                   10ba6f33e228   2 months ago    754MB

如果 docker load 报错，可尝试 docker import，但推荐使用 load，兼容性更好。

6.最小启动（无持久化）

适合临时测试，容器删除后数据不保留：

docker run -tid --privileged \
  -p 54321:54321 \
  --name kingbase \
  kingbase_v009r001c010b0004_single_x86:v1 /usr/sbin/init

7.推荐启动（数据持久化）

生产或长期使用建议挂载数据卷：

docker run -tid --privileged \
  -p 9099:54321 \
  --name kingbase \
  -v /opt/kingbase/data:/home/kingbase/userdata \
  kingbase_v009r001c010b0004_single_x86:v1 /usr/sbin/init

端口说明：KingbaseES 默认使用 54321 端口，非 PostgreSQL 的 5432，注意区分。

8.查看容器状态

docker ps

输出示例：

CONTAINER ID   IMAGE                                                                                                  COMMAND                  CREATED         STATUS                  PORTS                                                                            NAMES
6f2958b65b3d   kingbase_v009r001c010b0004_single_x86:v1                                                               "/bin/bash /home/kin…"   5 seconds ago   Up 5 seconds            0.0.0.0:9099->54321/tcp, :::9099->54321/tcp                                      kingbase

9.进入容器

docker exec -it kingbase /bin/bash

[kingbase@6f2958b65b3d ~]$ du -sh *
8.0K    docker-entrypoint.sh
439M    install
167M    userdata

进入跟目录，可以打印 docker-entrypoint.sh 启动类出来看看，看一下启动都发生了什么事，搞技术就喜欢追究底层原理，常话说：知其然，知其所以然！

二、SpringBoot 项目搭建

1. 新建 SpringBoot 项目

创建标准 SpringBoot 项目，勾选 Lombok 基础依赖，其余依赖手动引入。

2. 核心 Maven 依赖（pom.xml）

KingbaseES 无公开 Maven 仓库，优先使用项目内置驱动，也可从金仓官网下载驱动包手动引入。

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>3.2.0</version>
        <relativePath/>
    </parent>

    <groupId>com.kingbase</groupId>
    <artifactId>springboot-kingbase-demo</artifactId>
    <version>0.0.1-SNAPSHOT</version>
    <name>springboot-kingbase-demo</name>

    <properties>
        <java.version>17</java.version>
    </properties>

    <dependencies>
        <!-- SpringBoot Web 核心依赖 -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>

        <!-- MyBatis-Plus 集成 SpringBoot（简化CRUD） -->
        <dependency>
            <groupId>com.baomidou</groupId>
            <artifactId>mybatis-plus-boot-starter</artifactId>
            <version>3.5.5</version>
        </dependency>

        <!-- Druid 连接池（国产数据库兼容性最优） -->
        <dependency>
            <groupId>com.alibaba</groupId>
            <artifactId>druid-spring-boot-3-starter</artifactId>
            <version>1.2.20</version>
        </dependency>

        <!-- KingbaseES 数据库驱动（核心！） -->
        <dependency>
            <groupId>com.kingbase8</groupId>
            <artifactId>kingbase8</artifactId>
            <version>8.6.0</version>
            <scope>system</scope>
            <systemPath>${project.basedir}/lib/kingbase8-8.6.0.jar</systemPath>
        </dependency>

        <!-- Lombok 简化代码 -->
        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
            <optional>true</optional>
        </dependency>

        <!-- 测试依赖 -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
        </dependency>
    </dependencies>

    <!-- 打包时包含本地驱动包 -->
    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
                <configuration>
                    <includeSystemScope>true</includeSystemScope>
                </configuration>
            </plugin>
        </plugins>
    </build>
</project>

3. 驱动包放置说明

1. 在项目根目录创建 lib 文件夹
2. 将 kingbase8-8.6.0.jar 放入该文件夹
3. 驱动包可从金仓数据库安装目录获取：KingbaseES/V8/Server/lib/kingbase8.jar

三、KingbaseES 数据库配置

1. 新建测试表（SQL）

在 KingbaseES 中执行以下 SQL，创建用户测试表：

-- 创建用户表
CREATE TABLE sys_user (
    id BIGSERIAL PRIMARY KEY,  -- 自增主键
    username VARCHAR(50) NOT NULL,
    age INT,
    email VARCHAR(100),
    create_time TIMESTAMP DEFAULT NOW()
);

-- 插入测试数据
INSERT INTO sys_user (username, age, email) VALUES 
('张三', 20, 'zhangsan@test.com'),
('李四', 25, 'lisi@test.com');

2. application.yml 配置文件

spring:
  # 数据源配置（KingbaseES 核心）
  datasource:
    driver-class-name: com.kingbase8.Driver
    url: jdbc:kingbase8://localhost:54321/TEST?currentSchema=PUBLIC&useUnicode=true&characterEncoding=utf8
    username: system  # 金仓默认用户名
    password: 123456  # 你的数据库密码
    type: com.alibaba.druid.pool.DruidDataSource

# MyBatis-Plus 配置
mybatis-plus:
  mapper-locations: classpath:mapper/*.xml  # mapper文件路径
  configuration:
    map-underscore-to-camel-case: true  # 下划线转驼峰
    log-impl: org.apache.ibatis.logging.stdout.StdOutImpl  # 打印SQL日志

关键配置说明：

• 驱动类：com.kingbase8.Driver
• 连接地址：默认端口 54321，TEST 为数据库名，PUBLIC 为默认模式
• 用户名 / 密码：安装 KingbaseES 时自定义的账号密码

四、代码实现（标准三层架构）

1. 实体类（SysUser.java）

对应数据库表 sys_user，使用 MyBatis-Plus 注解简化映射：

package com.kingbase.entity;

import com.baomidou.mybatisplus.annotation.IdType;
import com.baomidou.mybatisplus.annotation.TableId;
import com.baomidou.mybatisplus.annotation.TableName;
import lombok.Data;

import java.time.LocalDateTime;

/**
 * 用户实体类
 */
@Data
@TableName("sys_user")  // 绑定数据库表名
public class SysUser {
    // 主键自增（KingbaseES 自增策略）
    @TableId(type = IdType.AUTO)
    private Long id;

    // 用户名
    private String username;

    // 年龄
    private Integer age;

    // 邮箱
    private String email;

    // 创建时间
    private LocalDateTime createTime;
}

2. Mapper 接口（SysUserMapper.java）

继承 MyBatis-Plus 的 BaseMapper，无需编写 XML，自动拥有 CRUD 方法：

package com.kingbase.mapper;

import com.baomidou.mybatisplus.core.mapper.BaseMapper;
import com.kingbase.entity.SysUser;
import org.apache.ibatis.annotations.Mapper;

/**
 * 用户Mapper
 */
@Mapper
public interface SysUserMapper extends BaseMapper<SysUser> {
    // 继承BaseMapper后，自带增删改查方法，无需手写
}

3. Service 层（业务逻辑）

接口（SysUserService.java）

package com.kingbase.service;

import com.baomidou.mybatisplus.extension.service.IService;
import com.kingbase.entity.SysUser;
import java.util.List;

/**
 * 用户Service接口
 */
public interface SysUserService extends IService<SysUser> {
    // 自定义根据姓名查询用户
    List<SysUser> getByUsername(String username);
}

实现类（SysUserServiceImpl.java）

package com.kingbase.service.impl;

import com.baomidou.mybatisplus.core.conditions.query.LambdaQueryWrapper;
import com.baomidou.mybatisplus.extension.service.impl.ServiceImpl;
import com.kingbase.entity.SysUser;
import com.kingbase.mapper.SysUserMapper;
import com.kingbase.service.SysUserService;
import org.springframework.stereotype.Service;

import java.util.List;

/**
 * 用户Service实现类
 */
@Service
public class SysUserServiceImpl extends ServiceImpl<SysUserMapper, SysUser> implements SysUserService {

    /**
     * 根据用户名查询用户
     */
    @Override
    public List<SysUser> getByUsername(String username) {
        LambdaQueryWrapper<SysUser> wrapper = new LambdaQueryWrapper<>();
        wrapper.eq(SysUser::getUsername, username);
        return this.list(wrapper);
    }
}

4. Controller 层（接口提供）

编写 RESTful 风格接口，实现完整增删改查：

package com.kingbase.controller;

import com.kingbase.entity.SysUser;
import com.kingbase.service.SysUserService;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.*;

import java.util.List;

/**
 * 用户CRUD控制层
 */
@RestController
@RequestMapping("/user")
public class SysUserController {

    @Autowired
    private SysUserService userService;

    // 1. 新增用户
    @PostMapping("/add")
    public String addUser(@RequestBody SysUser user) {
        boolean save = userService.save(user);
        return save ? "新增成功" : "新增失败";
    }

    // 2. 根据ID删除用户
    @DeleteMapping("/delete/{id}")
    public String deleteUser(@PathVariable Long id) {
        boolean remove = userService.removeById(id);
        return remove ? "删除成功" : "删除失败";
    }

    // 3. 修改用户
    @PutMapping("/update")
    public String updateUser(@RequestBody SysUser user) {
        boolean update = userService.updateById(user);
        return update ? "修改成功" : "修改失败";
    }

    // 4. 根据ID查询用户
    @GetMapping("/get/{id}")
    public SysUser getUserById(@PathVariable Long id) {
        return userService.getById(id);
    }

    // 5. 查询所有用户
    @GetMapping("/list")
    public List<SysUser> getAllUser() {
        return userService.list();
    }

    // 6. 根据用户名模糊查询
    @GetMapping("/getByName")
    public List<SysUser> getByUsername(@RequestParam String username) {
        return userService.getByUsername(username);
    }
}

5. 启动类

package com.kingbase;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

/**
 * SpringBoot 启动类
 */
@SpringBootApplication
public class SpringbootKingbaseDemoApplication {
    public static void main(String[] args) {
        SpringApplication.run(SpringbootKingbaseDemoApplication.class, args);
    }
}

五、接口测试（Postman/ApiFox）

启动项目后，通过以下接口测试 CRUD 功能：

1. 新增用户：POST http://localhost:8080/user/add 请求体：{"username":"王五","age":30,"email":"wangwu@test.com"}
2. 删除用户：DELETE http://localhost:8080/user/delete/1
3. 修改用户：PUT http://localhost:8080/user/update 请求体：{"id":2,"username":"李四-修改","age":26}
4. 根据 ID 查询：GET http://localhost:8080/user/get/2
5. 查询所有：GET http://localhost:8080/user/list
6. 按姓名查询：GET http://localhost:8080/user/getByName?username=张三

六、常见问题解决

1. 驱动包找不到

第一步：检查 lib 文件夹路径是否正确

第二步：确认 pom.xml 中 systemPath 路径匹配

第三步：执行 Maven reload 刷新依赖

2. 数据库连接失败

第1步：检查 KingbaseES 服务是否启动

第2步：确认端口（默认 54321）、数据库名、模式名正确

第3步：核对用户名 / 密码是否正确

3. SQL 执行报错

1、表名 / 字段名大小写：KingbaseES 默认不区分大小写，建议全小写

2、自增主键：必须使用 IdType.AUTO 适配金仓自增序列

七、总结

本文通过 SpringBoot + MyBatis-Plus 快速实现了 KingbaseES 的增删改查，核心优势：

1. 零冗余 XML 配置，MyBatis-Plus 自动生成 CRUD 方法
2. 适配国产金仓数据库，符合国产化项目要求
3. 代码简洁、结构清晰，可直接用于企业级项目开发

如果你需要适配 MyBatis（原生 XML）、JPA 或更复杂的多表查询、分页功能，可以在本教程基础上快速扩展。

心得记录

1. 核心配置：驱动com.kingbase8.Driver、连接地址、账号密码是集成金仓的关键
2. 极简开发：MyBatis-Plus 继承BaseMapper/IService即可实现全自动 CRUD
3. 国产化适配：Druid 连接池 + Kingbase 驱动，完美兼容国产数据库环境
4. 标准架构：Controller+Service+Mapper 三层结构，符合企业开发规范