在 JPA 的 @Query(nativeQuery = true) 中，若需向 PostgreSQL 的 @> 包含操作符传递数组参数（如 ARRAY[:param]），必须避免将命名参数包裹在单引号内，否则参数不会被解析为占位符，而会被当作字面量字符串处理。
在 jpa 的 `@query(nativequery = true)` 中，若需向 postgresql 的 `@>` 包含操作符传递数组参数（如 `array[:param]`），必须避免将命名参数包裹在单引号内，否则参数不会被解析为占位符，而会被当作字面量字符串处理。
在使用 Spring Data JPA 调用 PostgreSQL 原生查询时，尤其涉及 @>（包含）、&&（重叠）等数组操作符时，参数绑定方式与标准 SQL 有细微但关键的区别。常见错误是像这样书写：
@Query(value = "SELECT * FROM my_user x WHERE x.tenant_ids @> ARRAY[':tenantId']", nativeQuery = true) Set<myuser> findDrivers(String tenantId);</myuser>
⚠️ 此写法会导致 ':tenantId' 被 PostgreSQL 当作固定字符串字面量（即数组元素为字符串 ":tenantId"），而非动态替换的参数值，因此查询永远不匹配。
✅ 正确做法是：移除单引号，并使用方括号语法 ARRAY[:paramName]（PostgreSQL 原生支持参数化数组字面量），同时配合 @Param 显式声明参数名：
public interface MyUserRepo extends CrudRepository<myuser string> {
@Query(value = "SELECT * FROM my_user x " +
"WHERE x.tenant_ids @> ARRAY[:tenantId] " +
"AND x.roles @> ARRAY['driver']",
nativeQuery = true)
Set<myuser> findDrivers(@Param("tenantId") String tenantId);
}</myuser></myuser>
? 关键要点说明：
- ARRAY[:tenantId] 是 PostgreSQL 支持的参数化数组语法，JDBC 驱动会将 :tenantId 绑定为单元素数组（如 {"abc123"}），而非字符串拼接；
- 不可写作 ARRAY[':tenantId'] 或 ARRAY[?1]（后者在原生查询中不支持位置参数绑定）；
- @Param("tenantId") 必须与 SQL 中的 :tenantId 完全一致（大小写敏感）；
- 若需传入多值数组（如多个 tenant ID），应改用 List
参数 + ARRAY[:tenantIds]，并确保数据库列类型兼容（如 text[]）。
? 补充建议：
对于更复杂的数组操作，也可考虑使用 ANY() 替代 @>（如 x.tenant_id = ANY(:tenantIds)），但语义不同（精确匹配 vs 子集包含），请按业务逻辑谨慎选择。始终通过日志开启 logging.level.org.springframework.jdbc.core.JdbcTemplate=DEBUG 验证实际执行的 SQL 和绑定参数。
