在 spring boot 的 jpa 中，若直接编写包含子查询、表别名或数据库特定函数的 sql，必须显式声明 `nativequery = true`，否则 hibernate 会尝试将其解析为 jpql，导致语法错误。
Spring Data JPA 默认将 @Query 中的语句视为 JPQL（Java Persistence Query Language），它面向实体对象而非数据库表，不支持原生 SQL 的语法特性（如子查询作为 FROM 表、自定义函数调用、数据库关键字如 AS 别名、GROUOP BY 等）。你遇到的错误——'(' after the first FROM is an unexpected token——正是 Hibernate 在 JPQL 解析器中遇到了非法符号所致。
✅ 正确做法是：明确指定该查询为原生 SQL 查询，通过 nativeQuery = true 参数告知 Spring Data JPA 跳过 JPQL 解析，直接交由数据库执行：
分析 Java Spring Boot 后端 Controller 代码，自动生成 Markdown 格式的接口文档。当用户说“生成 Java 接口文档”、“生成 API 文档”、“从 Spring 代码生成文档”时触发。
@Query(
value = "SELECT com.example.imse22.model.TrvlA_Cust_Dto(books_query.name, COUNT(travelA_query.customer_id)) " +
"FROM (SELECT DISTINCT customer_servant.employee_id, books.customer_id " +
" FROM customer_servant " +
" INNER JOIN books ON customer_servant.employee_id = books.customer_servant_id) AS travelA_query " +
"INNER JOIN " +
"(SELECT travel_agency.id, travel_agency.name, employee.employee_id " +
" FROM travel_agency " +
" INNER JOIN employee ON travel_agency.id = employee.travel_agency_id) AS books_query " +
"ON travelA_query.employee_id = books_query.employee_id " +
"GROUP BY books_query.name", // ⚠️ 注意：原文中拼写错误为 "GROUOP BY"，已修正为 "GROUP BY"
nativeQuery = true
)
List<TrvlA_Cust_Dto> findTravelAgencyCustomerCounts();? 关键要点说明：
- value 属性用于指定原生 SQL 字符串（推荐显式命名，提高可读性）；
- nativeQuery = true 是强制要求，缺一不可；
- SQL 中的列名、表名需严格匹配数据库实际结构（区分大小写依数据库而定，PostgreSQL 默认小写）；
- 返回类型应为 List
，其中 T 可以是： - 自定义 DTO 类（需确保其构造函数与 SELECT 字段顺序/类型匹配，或使用 @SqlResultSetMapping）；
- 或直接使用 Object[] / Map
接收原始结果（更灵活但需手动映射）；
- 原生查询不支持 JPQL 的实体关系导航（如 customer.travelAgency.name），所有关联必须通过 SQL 显式 JOIN；
- 拼写校验：原文中 GROUOP BY 是明显笔误，务必修正为 GROUP BY，否则 PostgreSQL 也会报错。
? 进阶建议：
若需复用复杂查询逻辑或提升类型安全性，可考虑结合 @SqlResultSetMapping + @ConstructorResult，让 JPA 将结果集自动映射为强类型 DTO；对于高频使用的原生查询，也可封装进 JdbcTemplate 或 NamedParameterJdbcTemplate 中，获得更细粒度的控制能力。
总之，只要涉及非 JPQL 语法（尤其是含子查询、函数、数据库专有特性），就请始终启用 nativeQuery = true ——这是 JPA 原生 SQL 的“开启开关”。
