必须继承oracle12cdialect而非oracledialect，因其专为oracle 12c+设计，支持offset/fetch分页语法、正确处理pageable的count+limit组合及自定义函数注册；而oracledialect基于旧版rownum机制，易导致分页sql错误、函数未注册、建表失败等问题。
必须继承 oracle12cdialect（或对应实际 oracle 版本的方言基类），不能直接 new 一个空方言；否则函数注册无效、建表失败、分页报 could not extract resultset 等问题全都会冒出来。
为什么必须继承 Oracle12cDialect 而不是 OracleDialect？
Oracle 官方从 12c 开始引入了更多 SQL 标准支持（如 OFFSET ... FETCH 分页语法），而老版本 OracleDialect（实际指向 8i/9i）默认用 ROWNUM 套子实现分页，容易在 Spring Data JPA 的 Pageable 场景下生成错误 SQL。如果你用的是 Oracle 12c+（2019 年后部署基本都是），Oracle12cDialect 是唯一能正确处理 count query + limit/offset 组合的基类。
常见错误现象：
- 配置了自定义方言但分页查询直接抛
could not extract ResultSet - 表结构不自动创建（
ddl-auto: create/update失效） - 自定义函数在 JPQL 中调用时报
function not registered
如何注册自定义函数（比如 PKG_TEST.HELLO_WORLD）
在构造函数里调用 registerFunction，传入函数名、返回类型和 SQL 模板。注意：模板里的占位符是 ?1、?2，不是 :param 或 {0}。
示例代码片段：
public class CustomOracleDialect extends Oracle12cDialect {
public CustomOracleDialect() {
super();
registerFunction("hello_world",
new SQLFunctionTemplate(StandardBasicTypes.STRING, "PKG_TEST.HELLO_WORLD(?1)"));
registerFunction("listagg_distinct",
new SQLFunctionTemplate(StandardBasicTypes.STRING, "LISTAGG(DISTINCT ?1, ?2) WITHIN GROUP (ORDER BY ?1)"));
}
}
关键点：
-
SQLFunctionTemplate第二个参数是完整 SQL 片段，要自己拼好括号、WITHIN GROUP等 Oracle 语法 - 如果函数有多个参数，模板中按顺序写
?1、?2…，不要漏掉 - 别用
StandardSQLFunction—— 它不支持带WITHIN GROUP这类复杂结构的函数
application.yml 配置必须生效，且不能被覆盖
配置项必须写成 spring.jpa.properties.hibernate.dialect，路径不能少 properties 一级；如果项目里同时存在 application.properties 和 application.yml，后者可能被前者静默覆盖（尤其旧版 Spring Boot）。
正确写法：
spring:
jpa:
properties:
hibernate:
dialect: com.example.CustomOracleDialect
容易踩的坑：
- 写成
spring.jpa.hibernate.dialect（漏掉properties）→ 配置不加载，日志里也无提示 - 类路径写错，比如包名拼错或类没加
public修饰 → 启动时抛ClassNotFoundException但可能被吞掉 - 用了 Lombok 的
@RequiredArgsConstructor却忘了方言类没字段 → 构造函数为空，registerFunction根本没执行
Criteria API 中调用自定义函数的写法
不能直接写 cb.function("hello_world", ...) 就完事——JPA 只认方言里注册过的函数名。只要方言注册成功，下面这行就能生成带 PKG_TEST.HELLO_WORLD(xxx) 的 SQL：
Expression<string> expr = cb.function("hello_world", String.class, root.get("name"));</string>
注意事项：
- 函数名（第一个参数）必须和
registerFunction里传的一致，大小写敏感 - 如果函数在 Oracle 里是大写的（如
LISTAGG），注册时也得用大写，否则匹配失败 - 别试图在
function()里嵌套distinct表达式来模拟LISTAGG(DISTINCT ...)—— Oracle 不支持这种写法，必须在方言模板里硬编码DISTINCT
最常被忽略的是：方言类必须被 Spring 扫描到（放在主启动类同包或子包），且不能有编译错误或依赖缺失；哪怕只差一个分号，整个方言都不会注册，但控制台可能完全不报错，只会默默退化成基础 OracleDialect 行为。
