railwaysystem/RuoYi-Vue/docs/kingbase_compatibility_audit.md

RuoYi-Vue KingbaseES (人大金仓) 适配审计报告

审计说明：本轮审计仅对代码与配置文件进行静态分析与兼容性评估，未修改任何工程代码文件，未执行任何 DDL/DML 操作，所有凭据敏感信息已脱敏。

---

A. 已确认适配

1. JDBC 驱动类已切换

   • 在 ruoyi-admin/src/main/resources/application-druid.yml 中，主库驱动已正确指定为人大金仓驱动：

     driverClassName: com.kingbase8.Driver
     

2. JDBC 连接串协议与 Schema 参数已配置

   • 连接串已适配为 jdbc:kingbase8 协议，并显式指定了 currentSchema=public：

     url: jdbc:kingbase8://192.168.139.218:4321/training?currentSchema=public&useUnicode=true&characterEncoding=utf8
     

   • 经网络探测，Mac 宿主机到目标数据库 192.168.139.218:4321 的网络端口畅通可达。

3. 依赖声明已添加

   • 根模块 pom.xml 的 <dependencyManagement> 与 ruoyi-admin/pom.xml 中已添加 Kingbase 驱动坐标：

     <groupId>com.kingbase</groupId>
     <artifactId>kingbase8</artifactId>
     <version>8.6.0</version>
     

4. 业务模块 SQL 规范度较好

   • 核心业务模块 ruoyi-train 下的 14 个业务表 Mapper（如 TrainStudentMapper.xml 等）均为标准单表 CRUD 语句，未使用复杂的 MySQL 专有方言函数。

---

B. 明确存在的问题

1. 本地仓库缺失 Kingbase JDBC Jar 包

• 本地 ~/.m2/repository/com/kingbase/kingbase8/8.6.0/ 目录不存在。
• 人大金仓官方商业驱动未公开发布至 Maven 中央仓库或阿里云公共镜像，导致命令行执行 Maven 命令时依赖无法解析，构建失败。

2. PageHelper 分页插件方言被硬编码为 MySQL

• 在 ruoyi-admin/src/main/resources/application.yml 中明确配置了：

  pagehelper:
    helperDialect: mysql
  

• 强制指定 mysql 方言会导致 PageHelper 加载 MySqlDialect，而非 Kingbase/PostgreSQL 专属分页与 Count 优化器，埋下深层分页与嵌套查询隐患。

3. Mapper XML 中存在反引号（`）转义

• PostgreSQL/Kingbase 识别双引号 " 作为标识符定界符，反引号属于非法语法。
• ruoyi-system/src/main/resources/mapper/system/SysMenuMapper.xml 中共有 6 处使用了反引号字段 `query`（如第 32、53、59、78、149、173 行），执行对应菜单查询/更新 SQL 时将直接抛出语法错误。

4. Mapper XML 中包含 MySQL 专属函数

• date_format(...)（共 14 处）：
  • 涉及：SysUserMapper.xml、SysJobLogMapper.xml、SysOperLogMapper.xml、SysLogininforMapper.xml、GenTableMapper.xml。
  • 典型语法：AND date_format(create_time,'%Y%m%d') >= date_format(#{params.beginTime},'%Y%m%d')。
  • Kingbase 中无原生 date_format，标准函数为 TO_CHAR(...)。带时间范围检索的列表查询将直接报错。
• find_in_set(...)（共 3 处）：
  • 涉及：SysUserMapper.xml（部门权限关联）与 SysDeptMapper.xml（部门树父子过滤）。
  • Kingbase/PG 无原生 find_in_set 函数，涉及组织架构层级查询时将抛出异常。
• ifnull(...)（共 4 处）：
  • 涉及：SysMenuMapper.xml 中的 ifnull(perms, '')。
  • PG 标准函数为 COALESCE。若 Kingbase 处于非兼容模式，会提示函数不存在。

5. 若依代码生成器（ruoyi-generator）完全无法使用

• 表元数据查询失败 (GenTableMapper.xml)：
  • 查询语句：from information_schema.tables where table_schema = (select current_database())。
  • Kingbase 的 current_database() 返回数据库名（如 training），与 schema 名（如 public）不一致，无法检索出任何表。
  • 查询列中的 table_comment、create_time、update_time 在 Kingbase 的 information_schema.tables 视图中并不存在，直接报列不存在异常。
• 字段元数据查询失败 (GenTableColumnMapper.xml)：
  • 包含非标准操作符 &&（PG 中必须用 AND）。
  • 使用了 MySQL 专有的 column_key、extra、column_comment、column_type 字段，在 Kingbase 中不可用。
• 代码生成模板中的 MySQL 专有语法 (vm/sql/sql.vm)：
  • 包含了 SELECT @parentId := LAST_INSERT_ID(); 及 @parentId 变量，Kingbase 无法解析执行。

6. 初始化 SQL 脚本完全未做 Kingbase 迁移

• sql/ry_20250522.sql 和 sql/quartz.sql 均为纯 MySQL 语法。
• 包含 engine=innodb、auto_increment、bigint(20)、datetime、sysdate()、blob 等 MySQL 专有 DDL 与函数，且未创建任何序列（Sequence），在 Kingbase 中无法直接执行初始化。

---

C. 潜在风险

1. Druid 连接保活查询配置风险
   • application-druid.yml 中配置了 validationQuery: SELECT 1 FROM DUAL。
   • Kingbase 在默认或 PG 模式下并无 DUAL 虚拟表（仅 Oracle 兼容模式或手工建视图才有），通用保活语句应为 SELECT 1。
2. Druid WallFilter（SQL 防火墙）误拦截
   • application-druid.yml 启用了 filter.wall，但未配置 Kingbase/PostgreSQL 专属的 WallFilter 白名单规则。Druid 内置 SQL 解析器在解析国产库特有语法时极易抛出 SQLSyntaxErrorException: druid wall filter sql error。
3. pom.xml 构建插件硬编码 Windows 路径
   • pom.xml 和 ruoyi-admin/pom.xml 中的 maven-dependency-plugin 包含了写死的路径： <outputDirectory>D:\maven_repository\com\kingbase\kingbase8\8.6.0</outputDirectory>。
   • 在 macOS 或 Linux 打包部署时将导致构建阶段报错或路径异常。
4. MySQL JDBC 驱动残留
   • ruoyi-admin/pom.xml 中仍声明有 mysql-connector-java，易引起类加载冗余或驱动加载冲突。
5. Schema 硬编码不一致
   • SysUserMapper.xml 与 SysConfigMapper.xml 中部分 SQL 被硬编码加入了 public. 前缀，而其余所有 Mapper 均未带前缀。一旦未来生产环境数据库 schema 迁移或变更，将导致部分 SQL 跨 schema 访问失效。
6. 标识符大小写与 LIKE 模糊匹配规则差异
   • MySQL 对表名、列名以及 LIKE 匹配默认不区分大小写，而 Kingbase/PG 默认区分大小写（LIKE 严格匹配大小写，需用 ILIKE 或 lower() 处理）。若数据库中存在大小写敏感数据，前端模糊搜索可能出现遗漏。

---

D. 后续建议

1. 建立本地/私服 Kingbase 依赖规范
   • 通过 mvn install:install-file 将 kingbase8-8.6.0.jar 安装至本地仓库，或上传至团队私有 Nexus 镜像库。
   • 清理 pom.xml 中残留的 mysql-connector-java 与硬编码的 D:\ 路径插件。
2. 修正数据源与连接池配置
   • 将 validationQuery 修改为标准跨库通用的 SELECT 1。
   • 将 PageHelper 的 helperDialect 修正为自动识别或 kingbase / postgresql。
   • 如果遇到 Druid 报防火墙拦截错误，调整 WallFilter 配置或针对 Kingbase 禁用 WallFilter。
3. 统一定义或兼容 SQL 函数
   • 方式一（推荐）：修改 Mapper XML，将 date_format 替换为 to_char，反引号替换为双引号，find_in_set 替换为数组/字符串函数或子查询。
   • 方式二：在 Kingbase 数据库的 public schema 下自定义创建 date_format、find_in_set、ifnull 兼容函数，降低改动范围。
4. 改造代码生成器元数据查询
   • 重构 GenTableMapper.xml 与 GenTableColumnMapper.xml，使用 information_schema.tables 配合 PostgreSQL 系统目录 pg_class、pg_description、pg_attribute 读取表及字段元数据。

---

E. 开始业务开发前必须解决的问题（阻断级 Checklist）

序号	优先级	类别	阻断问题与解决要点
1	🔴 P0	依赖构建	安装 Kingbase JDBC Jar：在开发机执行 mvn install:install-file 导入 kingbase8-8.6.0.jar，确保编译构建通过。
2	🔴 P0	配置项	纠正 PageHelper 方言：移除 application.yml 中的 helperDialect: mysql，避免分页 SQL 生成异常。
3	🔴 P0	SQL 语法	消除 Mapper XML 中的反引号：修改 SysMenuMapper.xml 中的 `query`，避免系统菜单相关接口直接崩溃。
4	🔴 P0	SQL 函数	解决 find_in_set 与 date_format：在数据库端创建兼容函数，或在 SysUserMapper.xml、SysDeptMapper.xml 等核心 XML 中重写对应 SQL，否则用户管理、部门管理、时间检索必定报错。
5	🔴 P0	初始化数据	准备 Kingbase 版基础 DDL 脚本：当前项目中的 sql/ry_*.sql 无法在 Kingbase 跑通，需提供适配 Kingbase 语法的主键序列及数据初始化脚本。
6	🟡 P1	代码生成	修复代码生成器元数据 SQL：若业务开发需要使用若依代码生成器，必须先重写 ruoyi-generator 的元数据查询 SQL。