配置项

Rabbit SQL 详细的类和接口配置项。

BakiDao

Baki 接口的默认实现。

globalPageHelperProvider

全局分页提供程序，通过实现此接口来支持更多数据库分页。例如内置实现没有直接匹配人大金仓、达梦等数据库，BakiDao 会通过 JDBC 驱动获取数据库名称，再决定使用哪个分页实现：

(info, namedParamPrefix) -> {
   if (info.getName().equals("kingbasees")) {
       return new PGPageHelper();
   }
   if (info.getName().equals("dm dbms")) {
     return new OraclePageHelper();
   }
   return null;
};

如上例子，人大金仓直接使用 PostgreSQL 的实现即可，达梦使用 Oracle 的即可，或者自行实现接口 com.github.chengyuxing.sql.page.PageHelper 。

sqlInterceptor

SQL 拦截器。在 SQL 解析开始时，可以通过抛出特定异常拦截不满足条件的 SQL，阻止其执行。

statementValueHandler

自定义预编译 SQL 参数值处理器，默认实现支持的特殊值类型包括：

• java.util.Date，以及 java.sql.Date、java.sql.Time、java.sql.Timestamp
• java8 新的日期时间：LocalDateTime ， LocalDate ，LocalTime ， OffsetDateTime ， OffsetTime ， ZonedDateTime ， Instant
• java.util.UUID
• java.io.InputStream
• java.io.File
• java.nio.file.Path

从 Rabbit SQL 10.3.23 起，UUID 使用 ps.setString(index, uuid.toString()) 绑定标准 36 位格式，文本列需能容纳 36 个字符。之前去横线写入的 32 位文本主键需统一存储格式，见 升级与迁移。

setObject(UUID) 的行为依赖数据库和 JDBC 驱动，不作为统一默认策略。使用 PostgreSQL 原生 uuid 列时可在现有处理器中专门绑定，其余类型继续复用默认逻辑：

// 此示例针对 PostgreSQL 原生 uuid 列，不作为跨数据库通用绑定策略。
baki.setStatementValueHandler((ps, index, value, metadata) -> {
    if (value instanceof UUID) {
        ps.setObject(index, value);
    } else {
        JdbcUtils.setStatementValue(ps, index, value);
    }
});

同一项目若同时使用原生 UUID 列和文本列，应按实际语句、列类型选择绑定方式。二进制列也需根据数据库约定显式编码，不能仅替换为 setObject。

日期参数按实际类型绑定：

日期或时间单独使用时，建议选择对应 SQL 类型或 LocalDate、LocalTime。实体字段如何适配 JDBC 返回类型，见 实体操作；公共类型转换见 实用工具。

默认处理器通过 Files.readAllBytes 将 File / Path 内容读入内存，并调用 PreparedStatement#setBytes 绑定。大文件如需流式传输，可传入 InputStream；调用方需保持流打开直到执行结束，并负责关闭。自定义处理器自行管理其打开的资源，示例见 扩展预编译 SQL 值处理器。

executionWatcher

SQL 执行观察者，可用于记录 SQL 执行开始时间和结束时间，可用于记录日志、统计 SQL 耗时、性能分析、SQL 审计等操作。

xqlFileManager

XQL 文件管理器，统一管理 SQL，执行动态 SQL，和插件协同工作，支持 Baki 接口通过 & 取地址符来获取并执行动态 SQL

batchSize

JDBC 底层每次执行的批量大小，默认为 1000，必须大于 0。它不表示事务提交次数；整批回滚需要事务。各行预编译 SQL 必须一致，详见 批量操作。

pageKey

分页查询的当前页码参数名，默认为 page ，在调用方法时，.pageable(page?, size?) 时，如果参数中有对应值，则可以不用写。

sizeKey

分页查询的每页条数参数名，默认为 size ，在调用方法时，.pageable(page?, size?) 时，如果参数中有对应值，则可以不用写。

queryTimeoutHandler

查询超时处理器，默认值为 0，表示没有超时限制。可根据需求设置超时时间，避免慢查询堆积占满连接池。

queryCacheManager

查询缓存管理器，支持自定义缓存实现，如 Redis、内存缓存等。命中缓存时直接从缓存中获取结果，提高性能。启用后会作用于以下查询：

• query()
• executeQueryStream()
• entity(class).query()
• entity(class).findById(id)

详细配置参考查询缓存管理。

entityMetaProvider

默认使用类简单名、字段名及值类型适配，不识别 JPA 注解或自动标记主键。可自定义表名、列元数据和值转换，框架的实体结果映射使用此配置。更换提供者会清除缓存，已有实体执行器需重新获取，详见 实体操作。

databaseInfoProvider

数据库信息提供者，主要用于动态数据源或其他不需要默认数据库信息的情况。通过实现该接口，可以改变框架内部的数据库信息初始化逻辑。

例如：baki.query(...).findFirstEntity(User.class)

IPageable

分页查询构建器。

args

分页查询 SQL 的总参数。

count

记录条数：可以传入数字总条数，也可以传入字符串形式的 count 查询语句。

disableDefaultPageSql

禁用默认分页查询 SQL 生成，并指定条数查询语句，同时重写默认分页参数 [start, end]。

pageHelper

针对当前执行的 SQL，优先使用局部配置的分页提供者；未配置时，使用全局分页提供者 BakiDao#globalPageHelperProvider。

XQLFileManager

constants:
#  base: &basePath pgsql

files:
# 使用 !path 标签合并列表得到 "pgsql/bar.xql"
   foo: !path [ *basePath, foo.xql ]
   bar: bar.xql
   remote: http://127.0.0.1:8080/share/cyx.xql?token=${env.TOKEN}

pipes:
#  upper: org.example.Upper

charset: UTF-8
named-param-prefix: ':'

constants

字符串模板常量池。初始化时，如果 SQL 中出现 ${base} 这样的模板占位符，框架会从常量池中查找并替换为对应值，例如 pgsql。

也可以通过 YAML 的锚点语法为常量定义 &basePath，供后面的变量引用。

files

XQL 文件字典集合，键为别名，值为 SQL 文件名。路径支持 YAML 数组语法，通过内置 !path 函数自动连接为一个路径。之后可以通过 别名.SQL名 获取 SQL，例如 my.query。

文件路径支持的格式有：

• Classpath: sql/rabbit.sql
• URI 格式:
  • Windows: file:/D:/rabbit.sql
  • Linux/Unix: file:/root/rabbit.sql
  • HTTP(S): http(s)://host/rabbit.sql
  • FTP: ftp://username:password@ftp.example.com/path/rabbit.sql

文件路径支持环境变量 ${env.}，如上 ${env.TOKEN} 将获取系统环境变量 TOKEN 。

pipes

动态 SQL 脚本引擎的自定义管道操作符字典，key 是管道名，value 是管道实现类的完整限定类名。通过添加自定义管道可以增强动态 SQL 表达式的能力。

charset

解析 XQL 文件所使用的编码，默认为 UTF-8。

namedParamPrefix

命名参数前缀符号，默认为 :，例如 where id = :id。可以自定义以适配不同环境。例如图数据库 Neo4j 的语法中 : 表示类型，会和命名参数前缀冲突，此时可以改为其他符号来避免执行异常。