@QueryHint是注解而非接口，用于向JPA提供者传递键值对，Oracle原生hint（如/+ INDEX /）只能在@Query(nativeQuery=true)中手写；EclipseLink支持PARALLEL等QueryHints，Hibernate则需手动setHint或改用原生SQL。
@QueryHint 不是接口，是注解；真正起作用的是 JPA 标准的 javax.persistence.QueryHint，Spring Data JPA 用 @QueryHints 包裹它来支持方法级配置。Oracle 场景下，你要的不是“SQL 提示”字面翻译，而是让 Oracle 优化器按你意图执行计划——比如强制走索引、禁用绑定变量窥探、设置并行度等。这必须通过数据库厂商特定的 hint name + value 实现，且依赖底层 JPA 提供商（如 EclipseLink、Hibernate）是否透传。
Oracle 的 /*+ ... */ 提示无法直接用 @QueryHint 注入
很多人误以为写 @queryhint(name = "org.hibernate.hql.ast.tree.sqlnode", value = "/*+ index(t idx_name) */") 就能生效，实际不会。jpa 查询提示（queryhint）不处理 sql 文本内联注释，它只向 entitymanager 的底层查询对象（如 hibernate 的 query 或 eclipselink 的 jpqlquery）传递键值对，由提供商决定是否解释、如何解释。
- Oracle 原生 hint（如
/*+ USE_NL(t1 t2) */）只能出现在原生 SQL 中，且需在@Query(nativeQuery = true)的value字符串里手写 -
@QueryHint的name必须是提供商定义的合法 key，例如 EclipseLink 的org.eclipse.persistence.config.QueryHints.JDBC_STATEMENT，不是任意字符串 - Hibernate 对标准
QueryHint支持有限，多数 Oracle 相关 hint（如oracle.jdbc.driver.OracleStatement级配置）需通过hibernate.dialect或自定义Interceptor注入
用 @QueryHints 配合 EclipseLink 实现 Oracle 并行查询
EclipseLink 是少数对 Oracle hint 支持较完整的 JPA 提供商。它定义了 org.eclipse.persistence.config.QueryHints.PARALLEL 等常量，可触发 Oracle 的并行执行计划。
- 确保你用的是 EclipseLink（非 Hibernate），且版本 ≥ 2.7
- 在 Repository 方法上添加：
@QueryHints(value = {
@QueryHint(name = org.eclipse.persistence.config.QueryHints.PARALLEL, value = "true"),
@QueryHint(name = org.eclipse.persistence.config.QueryHints.PARALLEL_MAX_THREADS, value = "4"),
@QueryHint(name = org.eclipse.persistence.config.QueryHints.QUERY_TYPE, value = "ReadObjectQuery")
}, forCounting = false)
List<product> findByCategory(String category);
</product>
-
forCounting = false很关键：分页时 count 查询通常不需要并行，否则可能引发 Oracle 并行 DML 限制或锁升级 - 这些 hint 不会生成
/*+ PARALLEL(4) */，而是让 EclipseLink 在 prepare 阶段调用 Oracle JDBC 的setParallel()方法 - 必须配合 Oracle 数据库端启用并行：检查
PARALLEL_DEGREE_POLICY和表/索引的DEGREE设置
在 @Query(nativeQuery = true) 中安全嵌入 Oracle hint
这是最可控、也最常用的方式。你完全掌控 SQL 文本，但要注意参数化与注入风险。
- hint 必须紧贴
SELECT关键字后，且用/*+ ... */包裹：
@Query(value = "SELECT /*+ INDEX(u IDX_USER_EMAIL) USE_NL(u d) */ u.id, u.email, d.name " +
"FROM users u JOIN departments d ON u.dept_id = d.id " +
"WHERE u.email = ?1", nativeQuery = true)
UserWithDept findByEmail(String email);
- 不要在 hint 里拼接变量，避免 SQL 注入；所有动态部分必须用
?1、:param占位符 - Oracle 对 hint 大小写不敏感，但空格和换行会影响解析——建议写在一行，用空格分隔多个 hint
- 如果使用
@Param，确保命名与 SQL 中:param严格一致，且不能和 Oracle 保留字冲突（如:order会报错） - Hibernate 用户注意：
nativeQuery = true下，@QueryHint默认不生效；若需同时用 hint 和原生 SQL，得改用EntityManager.createNativeQuery(...).setHint(...)手动构造
为什么 JpaSpecificationExecutor 几乎无法用 @QueryHint
JpaSpecificationExecutor::findAll(Specification) 底层走的是 Criteria API，生成的是 JPQL，再由提供商翻译为 SQL。这个过程绕过了 Spring Data 的 @QueryHints 解析逻辑——因为没方法签名可绑定注解。
- 你不能在
findAll(Specification)调用处加@QueryHints，它只对 Repository 接口方法有效 - 唯一可行路径是：用
EntityManager手动创建查询，再 setHint：
public List<product> findWithHints(String category) {
CriteriaBuilder cb = em.getCriteriaBuilder();
CriteriaQuery<product> cq = cb.createQuery(Product.class);
Root<product> root = cq.from(Product.class);
cq.select(root).where(cb.equal(root.get("category"), category));
TypedQuery<product> query = em.createQuery(cq);
query.setHint("org.eclipse.persistence.config.QueryHints.PARALLEL", "true");
return query.getResultList();
}
</product></product></product></product>
- 这意味着你放弃了
JpaSpecificationExecutor的便利性，但换来了完全可控的 hint 注入时机 - 如果你坚持用 Specification，又想加 hint，只能封装一个自定义 Repository 实现类，在
findAll内部做setHint
oracle.jdbc.useFetchSizeWithLongColumn=true）、甚至数据库补丁级别。别只看 Java 层配置是否“写对了”，务必用 EXPLAIN PLAN FOR ... 和 V$SQL_PLAN 确认实际执行计划是否真用了你指定的 hint。
