Spring Cloud Datastore中@Unindexed注解在集合类型上失效问题

此前使用Objectify时，@Unindex注解能正常作用于所有值类型，但迁移到Spring Cloud GCP Data Datastore后，发现@Unindexed注解在Map<String, Set<String>>和带@LazyReference的List<Book>字段上未生效，而简单集合类型（如Set<Integer>）能正常取消索引。

环境详情 #

• Java 17
• Spring Boot 3.2.3
• Gradle 8.5
• Spring Cloud GCP版本：5.0.4

相关代码 #

build.gradle #

ext {
    set('springCloudGcpVersion', "5.0.4")
}

dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-web'
    implementation 'com.google.cloud:spring-cloud-gcp-starter'
    implementation 'com.google.cloud:spring-cloud-gcp-starter-data-datastore'
}

dependencyManagement {
    imports {
        mavenBom "com.google.cloud:spring-cloud-gcp-dependencies:${springCloudGcpVersion}"
    }
}

实体类 #

import com.google.cloud.spring.data.datastore.core.mapping.*;
import org.springframework.data.annotation.Id;
import java.util.Map;
import java.util.Set;
import java.util.List;
import java.util.UUID;

@Entity(name = "Library")
public class Library {
  @Id private String id = UUID.randomUUID().toString();
  @Unindexed private Map<String, Set<String>> attributes; // 未成功取消索引
  @Unindexed private Set<Integer> sets; // 已成功取消索引
  @Unindexed @LazyReference private List<Book> bookRefs; // 未成功取消索引
}

import com.google.cloud.datastore.Key;
import com.google.cloud.spring.data.datastore.core.mapping.*;
import org.springframework.data.annotation.Id;

@Entity
public class Book {
  @Id Key id;
  private String title;
}

解决方案 #

1. 升级Spring Cloud GCP版本 #

该问题可能是Spring Cloud GCP 5.0.x版本的已知bug，建议升级到最新稳定版本（如5.1.x及以上），新版本已修复部分复杂类型的@Unindexed注解处理逻辑。

2. 针对Map嵌套集合类型的处理 #

对于Map<String, Set<String>>这类嵌套复杂类型，直接在Map字段上标记@Unindexed无法覆盖内部集合的索引配置，可以将内部集合包装为自定义类，并在类的字段上标记@Unindexed：

// 自定义包装类
public class AttributeValues {
    @Unindexed
    private Set<String> values;

    // 构造器、getter、setter
}

// 修改Library实体的attributes字段
@Unindexed
private Map<String, AttributeValues> attributes;

3. 针对引用列表类型的处理 #

对于带@LazyReference的List<Book>，改用@Reference(lazy = true)替代@LazyReference，并确保@Unindexed注解正确应用：

@Unindexed
@Reference(lazy = true)
private List<Book> bookRefs;

4. 手动控制实体字段索引（兜底方案） #

如果上述方法无效，可以通过DatastoreTemplate手动构建实体并标记字段为未索引：

import com.google.cloud.spring.data.datastore.core.DatastoreTemplate;
import com.google.cloud.datastore.MutableEntity;
import org.springframework.stereotype.Service;

@Service
public class LibraryService {
    private final DatastoreTemplate datastoreTemplate;

    public LibraryService(DatastoreTemplate datastoreTemplate) {
        this.datastoreTemplate = datastoreTemplate;
    }

    public void saveLibrary(Library library) {
        MutableEntity entity = datastoreTemplate.createMutableEntity(library);
        // 标记attributes字段为未索引
        entity.set("attributes", library.getAttributes(), false);
        // 标记bookRefs字段为未索引（需转换为Key集合）
        entity.set("bookRefs", library.getBookRefs().stream().map(Book::getId).toList(), false);
        datastoreTemplate.save(entity);
    }
}

5. 检查Datastore索引配置 #

确认GCP Datastore控制台中没有针对这些字段的自动创建的复合索引，若存在需手动删除不必要的索引。

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