Spring Boot RestController传String类型ID查询MongoDB报500错误

我搭建了仅用于学习的Spring Boot + MongoDB联合开发环境，无复杂业务逻辑，开发中遇到如下问题：

• 实体类主键id定义为String类型
• 传入数据库中已存在条目的id调用按id查询接口时，会触发500内部服务器错误
• 全量查询songinfo集合数据的功能运行完全正常

涉及的代码实现 #

领域实体类 #

@Data
@NoArgsConstructor
@AllArgsConstructor
@Builder
@Document(collection = "songinfo")
public class SongInfo {

    @Id
    private String id;

    private int songId;

    private String songName;

    private String description;
}

控制层接口 #

@RequiredArgsConstructor
@RestController
@RequestMapping("/songsinfo")
public class SongsInfoController {

    private final SongInfoService songInfoService;

    @GetMapping(value = "/{id}", headers = "Accept=application/json", 
        produces = {MediaType.APPLICATION_JSON_VALUE})
    public ResponseEntity<SongInfo> getSongInfoById(@PathVariable(value = "id") String id) {
        SongInfo songInfo = songInfoService.getSongInfoById(id);
        if (songInfo == null)
            return new ResponseEntity<>(HttpStatus.NOT_FOUND);
        return new ResponseEntity<>(songInfo, HttpStatus.OK);
    }
}

业务层实现 #

@Override
public SongInfo getSongInfoById(String id) {
    return songInfoRepository.findById(id).orElseThrow(NotFoundException::new);
}

仓储接口 #

public interface SongInfoRepository extends MongoRepository<SongInfo, String> {

}

测试现象 #

• 全量查询接口可以正常返回songinfo集合下的所有条目数据
• 从全量返回结果中复制某条数据的id作为路径参数，调用按id查询接口时，直接返回500内部服务器错误

问题根因与解决方案 #

这个问题是Spring Data MongoDB的默认类型转换规则触发的常见开发坑：

• 为什么全量查询功能正常？因为全量查询不需要手动传入id构建查询条件，Spring会直接读取Mongo文档中的_id值，映射为实体类的String类型id，不涉及入参的反向转换，所以不会触发报错。
• 单条按id查询时，Spring Data MongoDB 在实现findById方法的逻辑中，默认会将传入的String类型id，自动转换为MongoDB原生的ObjectId类型来构建查询条件。
• 转换过程要求传入的String必须是符合24位十六进制格式的合法ObjectId字符串，一旦格式不匹配，就会抛出类型转换异常，最终触发500内部服务器错误。
• 常见的触发场景包括：
  1. 数据库中_id字段存储的是普通字符串（非ObjectId类型），Spring依然会强制尝试将传入的String转成ObjectId做查询，格式不匹配直接报错
  2. 传入的id字符串存在截断、首尾空格、多余引号等问题，不符合24位十六进制的ObjectId格式，转换失败

对应解决方法 #

1. 如果数据库的_id是MongoDB默认生成的ObjectId类型
   • 先从服务端日志定位具体的异常堆栈，确认是否是id格式不匹配的转换错误
   • 检查传入的路径参数是否为完整的24位字符串，没有截断、空格、多余字符的问题
2. 如果数据库的_id是自定义的普通字符串（非ObjectId格式）
   • 在实体类的id字段上补充注解，明确指定id的存储类型，禁止Spring自动做ObjectId转换：

     @Id
     @MongoId(targetType = FieldType.STRING)
     private String id;
     

   • 注解@MongoId是Spring Data MongoDB 3.0+版本提供的配置项，配置后Spring会直接用传入的字符串值匹配_id字段，不再强制做类型转换
3. 如果使用的是较低版本的Spring Data MongoDB（无@MongoId注解支持）
   • 可以在仓储层手动声明查询语句，绕过默认的类型转换逻辑：

     public interface SongInfoRepository extends MongoRepository<SongInfo, String> {
         @Query("{_id: ?0}")
         Optional<SongInfo> findByIdCustom(String id);
     }
     

   • 之后业务层调用自定义的查询方法即可，该方法会直接用字符串值匹配_id字段，不会触发自动的ObjectId转换

冗余逻辑提示 #

当前业务层代码中，如果findById查询不到数据，会直接抛出NotFoundException，所以控制层里的if (songInfo == null)判断永远不会被执行，属于冗余逻辑，可以根据实际异常处理规则调整。

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