SpringDataCouchbase 5.X无法保存值为集合的Map问题求助

1. 自定义Map类型的序列化逻辑 #

Spring Data Couchbase 5.X默认序列化机制对嵌套Map、带Version类型的Map处理存在兼容问题，可通过配置MappingCouchbaseConverter添加自定义转换器规避反射访问私有字段的问题：

@Configuration
public class CouchbaseConfig extends AbstractCouchbaseConfiguration {
    // 基础Couchbase配置（略）

    @Override
    public MappingCouchbaseConverter mappingCouchbaseConverter() throws Exception {
        MappingCouchbaseConverter converter = super.mappingCouchbaseConverter();
        // 注册Version类型为简单类型，避免深层反射
        SimpleTypeHolder typeHolder = new SimpleTypeHolder(Collections.singleton(Version.class), true);
        converter.setSimpleTypeHolder(typeHolder);
        
        // 添加Version与String的双向转换器
        ConversionService conversionService = converter.getConversionService();
        conversionService.addConverter(new VersionToStringConverter());
        conversionService.addConverter(new StringToVersionConverter());
        
        return converter;
    }

    static class VersionToStringConverter implements Converter<Version, String> {
        @Override
        public String convert(Version source) {
            return source.toString(); // 按实际Version的字符串规则调整
        }
    }

    static class StringToVersionConverter implements Converter<String, Version> {
        @Override
        public Version convert(String source) {
            return Version.parse(source); // 按实际Version的解析规则调整
        }
    }
}

2. 指定字段的访问方式 #

在实体类的Map字段上添加@AccessType注解，强制框架通过getter/setter方法访问属性，避免触发不必要的字段反射：

public class Person {
    @AccessType(AccessType.Type.PROPERTY)
    private Map<String, Version> versionMap;

    @AccessType(AccessType.Type.PROPERTY)
    private Map<String, Map<String, String>> nestedMap;

    // 必须提供对应的getter/setter方法
    public Map<String, Version> getVersionMap() {
        return versionMap;
    }

    public void setVersionMap(Map<String, Version> versionMap) {
        this.versionMap = versionMap;
    }

    public Map<String, Map<String, String>> getNestedMap() {
        return nestedMap;
    }

    public void setNestedMap(Map<String, Map<String, String>> nestedMap) {
        this.nestedMap = nestedMap;
    }
}

3. 升级Spring Data Couchbase版本 #

该问题属于Spring Data Couchbase 5.X的已知bug，官方在后续补丁版本中修复了writeMapInternal方法中不必要的getPropertyAccessor调用逻辑，直接升级到5.X系列的最新小版本（如5.1.2及以上）即可解决。

4. 显式指定Map的实现类 #

如果实体中隐式使用了HashSet关联的Map实现，显式将Map初始化为HashMap，避免框架反射访问HashSet的私有map字段：

public class Person {
    private Map<String, Version> versionMap = new HashMap<>();
    private Map<String, Map<String, String>> nestedMap = new HashMap<>();
}

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