Spring Boot 3 + MyBatis-Plus + KES V9 Demo

这是一个面向 KingbaseES V9 的完整后端示例，使用 Java 17、Spring Boot 3.3.2、MyBatis-Plus 3.5.7 和 Druid，包含用户 CRUD、分页、KES 函数调用和插入触发器日志查询。

1. 环境要求

• JDK 17
• Maven 3.9+
• 已部署并允许远程访问的 KES V9
• KES 官方 JDBC 驱动 kingbase8-9.0.0.jar

KES 官方资料指出 JDBC JAR 位于 $KINGBASE_HOME/Interface/jdbc。官方旧案例基于 Spring Boot 2 / Java 8，本项目保留其 KES 连接和 PostgreSQL 方言结论，并升级为 Spring Boot 3 的 Jakarta 技术栈。

2. 安装官方 JDBC 驱动

驱动属于厂商文件，不提交到 Git。取得 JAR 后执行：

chmod +x scripts/install-kes-driver.sh
./scripts/install-kes-driver.sh /绝对路径/kingbase8-9.0.0.jar

脚本会安装 Maven 坐标 com.kingbase8:kingbase8:9.0.0。如果服务器实际提供了其他版本，请同步修改脚本与 pom.xml 中两个 KES Profile 的版本，确保 Maven 坐标与 JAR 一致。

3. 初始化数据库

初始化脚本不会在应用启动时自动执行。使用 KES 客户端执行：

ksql -h 服务器IP -p 54321 -U system -d testdb -f src/main/resources/db/kes-init.sql

脚本创建 user_info、user_opt_log、get_age_level 函数及 after_user_insert 触发器。

4. 配置与启动

export KES_DATASOURCE_URL='jdbc:kingbase8://服务器IP:54321/testdb?currentSchema=public'
export KES_DATASOURCE_USERNAME='system'
export KES_DATASOURCE_PASSWORD='请替换为真实密码'
mvn -Pkes spring-boot:run

开发时需要输出 MyBatis SQL，可增加 Spring Profile：

SPRING_PROFILES_ACTIVE=dev mvn -Pkes spring-boot:run

5. API 验证

新增用户：

curl -i -X POST http://localhost:8080/api/users \
  -H 'Content-Type: application/json' \
  -d '{"userName":"张三","age":28,"email":"zhangsan@example.com"}'

查询、修改和删除（把 1 换成新增返回的 ID）：

curl http://localhost:8080/api/users/1
curl -X PUT http://localhost:8080/api/users/1 -H 'Content-Type: application/json' \
  -d '{"userName":"张小三","age":29,"email":"zhangsan@example.com"}'
curl -i -X DELETE http://localhost:8080/api/users/1

列表与分页：

curl http://localhost:8080/api/users
curl 'http://localhost:8080/api/users/page?pageNum=1&pageSize=5&userName=张'

调用 KES 函数与查询触发器日志：

curl http://localhost:8080/api/users/1/age-level
curl 'http://localhost:8080/api/user-opt-logs?pageNum=1&pageSize=10'

新增成功后，after_user_insert 会自动向 user_opt_log 写入一条“新增”记录。

6. 测试

默认测试不解析官方驱动，也不连接远程数据库：

mvn clean test

安装驱动、执行初始化 SQL 并导出三个数据库环境变量后，可运行真实 KES 全链路测试：

mvn -Pkes-it verify

7. 常见问题

• Connection refused：依次检查服务器防火墙、安全组、Docker 54321:54321 映射和 pg_hba.conf。
• password authentication failed：确认用户名、密码及大小写。
• 找不到表：确认 URL 使用 currentSchema=public，并在同一数据库执行了初始化 SQL。
• 找不到 com.kingbase8.Driver：先运行驱动安装脚本，并使用 -Pkes 或 -Pkes-it。
• Maven 找不到驱动：检查本地仓库中是否存在 com/kingbase8/kingbase8/9.0.0。

8. 项目结构

src/main/java/com/kes/v9/demo
├── audit      # 触发器日志查询
├── common     # 统一错误响应
├── config     # MyBatis-Plus PostgreSQL 分页方言
└── user       # 用户 CRUD 与 KES 函数调用