Spring Boot 1.5.10迁移至2.0：Spring Data Mongo @Query查询失效问题

嘿，我之前帮好几个开发者解决过Spring Boot 2.0迁移时MongoDB @Query注解失效的问题，结合你给出的Credentials实体类片段，大概率是下面几个常见原因导致的，咱们一步步排查解决：

Spring Boot 1.5.10对应的是Spring Data MongoDB 1.10.x，而2.0版本升级到了Spring Data MongoDB 2.0.x，两者搭配的MongoDB驱动版本差异很大（1.5用的是3.4.x驱动，2.0推荐3.8+）。如果你的项目手动指定了MongoDB驱动版本，很容易出现解析逻辑不兼容的问题。

解决方法：
优先通过Spring Boot的starter来管理依赖，避免手动指定版本冲突。比如Maven中直接引入：

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-data-mongodb</artifactId>
</dependency>

Gradle则是：

implementation 'org.springframework.boot:spring-boot-starter-data-mongodb'

Spring Data MongoDB 2.0对@Query的字段解析逻辑更严格了：在1.5.x版本中，框架会自动适配实体类上的@Field注解映射，但2.0版本默认优先匹配实体类的属性名，而非MongoDB集合中的实际字段名（除非你显式指定）。

比如你的实体类中用了@Field("userId")映射数据库字段，但如果你的@Query写的是@Query("{userId: ?0}")，看起来字段名一致，但如果实体属性名和数据库字段名不一致（比如实体是userId，数据库是user_id），就会出现匹配失败。

解决方法：

• 确保@Query中使用的字段名与MongoDB集合中的实际字段完全一致（注意引号包裹，比如@Query("{'userId': ?0}")）；
• 如果你习惯用实体属性名，也可以通过SpEL表达式让框架自动映射：@Query("{'#{#entityName.userId}': ?0}")，这里#entityName会自动关联实体类的字段映射配置。

你在实体类中用了@Indexed注解，Spring Boot 2.0中MongoDB自动索引的创建逻辑有调整：虽然默认还是开启的，但如果你的配置中手动关闭了auto-index-creation，或者索引创建失败，可能导致查询无法命中索引（表现为查询无结果，看起来像@Query失效）。

解决方法：

• 检查MongoDB的credentials集合，确认userId字段的索引是否存在；
• 在application.properties中显式开启自动索引创建：

  spring.data.mongodb.auto-index-creation=true
  

Spring Data MongoDB 2.0对MongoDB查询语法的校验更严格了，尤其是针对数组、嵌套字段的查询。比如你实体类中的List<Access> access字段，如果@Query涉及数组元素的查询（比如@Query("{'access.permission': ?0}")），需要确保语法符合MongoDB 3.6+的规范（Spring Boot 2.0对应的驱动支持更高版本的MongoDB语法）。

解决方法：
先把你的查询语句拿到MongoDB Shell中执行一遍，确认能得到预期结果，再把正确的语法移植到@Query注解中。比如Shell中能查到数据，说明语句没问题，那就是框架映射的问题，回到前面的步骤排查。

你实现了Serializable和Comparable接口，Spring Boot 2.0升级了Jackson版本，序列化/反序列化的规则有变化。如果你的实体类缺少无参构造函数，或者嵌套类（比如Access）的字段映射有问题，会导致查询结果无法正确转化为实体对象，看起来像是@Query没生效。

解决方法：

• 给Credentials和Access类添加上无参构造函数（Spring Data需要通过无参构造来实例化对象）；
• 检查Access类的字段是否正确使用了@Field注解，确保和数据库字段一一对应。

可以先写一个简单的@Query测试，比如：

@Query("{'userId': ?0}")
Credentials findFirstByUserId(UUID userId);

调用这个方法，打印日志看实际执行的MongoDB语句（可以开启logging.level.org.springframework.data.mongodb.core.MongoTemplate=DEBUG），对比语句和你手动在Shell中执行的是否一致，这样能快速定位是语法问题还是映射问题。

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