Spring Boot+MongoDB-Reactive+WebFlux通过UUID查询文档的问题

MongoDB中UUID的存储格式 #

MongoDB默认不会把UUID存成纯字符串，而是存储为Binary(Subtype 3)（旧版UUID格式）或Binary(Subtype 4)（RFC 4122标准格式），具体取决于驱动配置。直接传入UUID的字符串形式（如"550e8400-e29b-41d4-a716-446655440000"），MongoDB会将其当作普通字符串匹配，自然找不到二进制存储的UUID数据。

无需自定义方法的字符串查询方案 #

方案1：配置MongoDB以字符串格式存储UUID #

如果允许修改存储规则，在Spring Boot配置文件中添加以下配置，让MongoDB直接将UUID存为标准字符串：

# application.properties
spring.data.mongodb.uuid-representation=STANDARD

# application.yml
spring:
  data:
    mongodb:
      uuid-representation: STANDARD

配置后新存入的UUID会以字符串格式存储，此时直接调用findById(id.toString())即可正常匹配。注意：已存在的旧数据需手动转换格式，否则仍无法通过字符串查询到。

方案2：将字符串UUID转换为Binary类型查询 #

若不能修改存储格式，可把传入的字符串UUID转为MongoDB的Binary对象，再通过Query执行查询：

import org.bson.types.Binary;
import org.springframework.data.mongodb.core.ReactiveMongoTemplate;
import org.springframework.data.mongodb.core.query.Criteria;
import org.springframework.data.mongodb.core.query.Query;
import reactor.core.publisher.Mono;
import java.nio.ByteBuffer;
import java.util.UUID;

// 注入ReactiveMongoTemplate
private final ReactiveMongoTemplate mongoTemplate;

public Mono<YourEntity> findByUuidString(String uuidStr) {
    UUID uuid = UUID.fromString(uuidStr);
    // 将UUID转为16字节数组（匹配Binary存储格式）
    byte[] uuidBytes = ByteBuffer.allocate(16)
            .putLong(uuid.getMostSignificantBits())
            .putLong(uuid.getLeastSignificantBits())
            .array();
    // 根据现有数据的Subtype选择对应值（通常为3或4，可通过MongoDB Compass查看）
    Binary binaryUuid = new Binary((byte) 4, uuidBytes);
    
    Query query = Query.query(Criteria.where("_id").is(binaryUuid));
    return mongoTemplate.findOne(query, YourEntity.class);
}

方案3：利用SpEL自动转换字符串到UUID #

在Repository接口中，通过SpEL表达式自动完成字符串到UUID的转换，无需额外编写转换逻辑：

import org.springframework.data.mongodb.repository.ReactiveMongoRepository;
import org.springframework.data.mongodb.repository.Query;
import reactor.core.publisher.Mono;
import java.util.UUID;

public interface YourEntityRepository extends ReactiveMongoRepository<YourEntity, UUID> {
    @Query("{ '_id' : ?#{T(java.util.UUID).fromString(#uuidStr)} }")
    Mono<YourEntity> findById(String uuidStr);
}

Spring Data MongoDB会自动将字符串参数转为UUID类型，再匹配二进制存储的UUID数据。

自定义UUID参数方法生效的原因 #

当Repository方法参数为UUID类型时，Spring Data MongoDB会自动将其转换为对应的Binary类型执行查询，与MongoDB的存储格式完全匹配，因此能正常找到数据。

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