Spring Boot中Hibernate-OGM搭配MongoDB时@Query注解失效问题

首先得戳破核心问题：你之前用的是Spring Data JPA体系的Repository（依赖org.springframework.data.repository.CrudRepository），对应的@Query注解是为JPQL/SQL设计的，但切换到Hibernate-OGM + MongoDB后，这套注解和查询逻辑并不适配——Hibernate-OGM确实能让Hibernate兼容MongoDB，但Spring Data JPA的Repository对NoSQL的支持有限，尤其是@Query的解析逻辑还是偏向关系型数据库的。

下面是一步步的修复方案：

1. 切换Repository接口类型 #

把原来继承CrudRepository的接口，改成继承Spring Data MongoDB的MongoRepository（如果需要分页，也可以用PagingAndSortingRepository）。MongoRepository是专门为MongoDB打造的Repository接口，能更好地配合Hibernate-OGM完成文档操作。

示例代码：

// 原来的JPA风格Repository
// import org.springframework.data.repository.CrudRepository;
// public interface UserRepository extends CrudRepository<User, Long> { ... }

// 修改后的MongoDB适配Repository
import org.springframework.data.mongodb.repository.MongoRepository;
import org.springframework.data.mongodb.repository.Query;

public interface UserRepository extends MongoRepository<User, String> {
    // 在这里定义查询方法
}

2. 修正@Query注解的查询语法 #

如果要保留@Query注解，必须把原来的JPQL/SQL语句改成MongoDB的文档查询语法（JSON格式），不能再用关系型数据库的查询逻辑。

比如原来的JPA查询：

@Query("SELECT u FROM User u WHERE u.email = ?1")
User findByEmail(String email);

要改成MongoDB的查询格式：

@Query("{ 'email' : ?0 }")
User findByEmail(String email);

注意：MongoDB的查询是基于文档结构的JSON，参数占位符用?0、?1（索引从0开始），也可以用命名参数:email来提高可读性。

3. 检查Hibernate-OGM与Spring的整合配置 #

确保你的Spring Boot配置文件（application.properties/application.yml）正确指向MongoDB，同时避免JPA自动配置的冲突：

# Hibernate OGM 核心配置
spring.jpa.properties.hibernate.ogm.datastore.provider=MONGODB
spring.jpa.properties.hibernate.ogm.datastore.database=your_db_name
spring.jpa.properties.hibernate.ogm.datastore.host=localhost
spring.jpa.properties.hibernate.ogm.datastore.port=27017

# 禁用JPA数据源自动配置（防止和MongoDB冲突）
spring.autoconfigure.exclude=org.springframework.boot.autoconfigure.jdbc.DataSourceAutoConfiguration

另外，实体类上的JPA注解（比如@Entity、@Id）Hibernate-OGM是兼容的，如果需要更贴合MongoDB的特性，也可以额外添加@Document注解（来自org.springframework.data.mongodb.core.mapping.Document），不过不添加也不影响基本功能。

4. 确认依赖的正确性 #

确保你的pom.xml（或build.gradle）引入了适配的Hibernate-OGM和Spring Data MongoDB依赖：

Maven示例：

<!-- Hibernate OGM for MongoDB -->
<dependency>
    <groupId>org.hibernate.ogm</groupId>
    <artifactId>hibernate-ogm-mongodb</artifactId>
    <version>5.4.1.Final</version> <!-- 选择和你的Spring Boot版本兼容的版本 -->
</dependency>

<!-- Spring Data MongoDB 核心依赖 -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-data-mongodb</artifactId>
</dependency>

注意版本兼容性：Hibernate-OGM的版本要和你使用的Spring Boot、Hibernate版本匹配，避免出现依赖冲突导致的隐性问题。

5. 可选：用方法命名规则替代@Query #

如果不想手动修改查询语句，也可以利用Spring Data MongoDB的方法命名自动生成查询功能，比如：

// 不需要写@Query，Spring Data会自动解析生成Mongo查询
User findByEmail(String email);
List<User> findByAgeGreaterThan(int age);

这种方式更简洁，也不容易出错，Spring Data会根据方法名自动生成对应的MongoDB查询条件。

总结来说：问题根源就是原来的JPA Repository和@Query语法不适配MongoDB生态，切换到Spring Data MongoDB的Repository并调整查询逻辑，就能解决@Query失效的问题。

内容的提问来源于stack exchange，提问作者vidarshana