SpringBoot3 CouchbaseTemplate插入失败：泛型T嵌套属性无法存储

Spring Data Couchbase 5.x（适配Spring Boot 3.x）在处理参数化泛型类型的序列化逻辑上做了调整，旧版本4.x对泛型字段的类型推断兼容性更好，新版本下自定义类型作为泛型字段时，默认序列化器无法自动识别类型，导致抛出转换错误。而自定义类型作为普通字段时，序列化器能直接识别类型，所以可以正常工作。

1. 为参数化实体显式声明泛型类型 #

在SampleDoc实体的泛型字段上添加@GenericType注解，明确指定实际类型：

@Document
@TypeAlias("sampleDoc")
public class SampleDoc<T> {
    @Id
    private String id;
    @GenericType(Address.class)
    private T data;

    // getter、setter方法
}

如果泛型支持多种类型，可以在实例化时动态设置类型信息：

SampleDoc<Address> doc = new SampleDoc<>();
doc.setData(new Address());
GenericTypeHolder.set(doc, Address.class);

2. 自定义类型转换器 #

创建双向转换器处理Address与Couchbase的JsonObject互转，注册到Spring容器：

@Component
public class AddressConverter implements Converter<Address, JsonObject>, Converter<JsonObject, Address> {

    @Override
    public JsonObject convert(Address source) {
        return JsonObject.create()
                .put("street", source.getStreet())
                .put("city", source.getCity())
                // 映射其他字段
                ;
    }

    @Override
    public Address convert(JsonObject source) {
        Address address = new Address();
        address.setStreet(source.getString("street"));
        address.setCity(source.getString("city"));
        // 映射其他字段
        return address;
    }
}

然后在Couchbase配置类中注册转换器：

@Configuration
public class CouchbaseConfig extends AbstractCouchbaseConfiguration {

    // 配置bootstrapHosts、bucketName、username、password等基础信息

    @Override
    public CustomConversions customConversions() {
        return new CustomConversions(List.of(new AddressConverter()));
    }
}

3. 确保自定义类符合序列化要求 #

检查Address类是否具备Jackson序列化的必要条件：

• 提供无参构造函数
• 所有需要序列化的字段都有对应的getter/setter方法（或用@JsonProperty直接标注字段）

示例：

public class Address {
    private String street;
    private String city;

    public Address() {} // 必须保留无参构造

    // getter和setter
    public String getStreet() { return street; }
    public void setStreet(String street) { this.street = street; }
    public String getCity() { return city; }
    public void setCity(String city) { this.city = city; }
}

4. 临时兼容配置（不推荐长期使用） #

如果需要快速恢复旧版本行为，可以在application.properties中开启兼容模式：

spring.data.couchbase.use-compatible-type-mapping=true

注意：该配置可能在后续版本中被移除，仅建议作为临时过渡方案。

完成配置后重启服务，调用目标API，检查Couchbase中的文档是否成功存储，且Address字段的结构与预期一致。

内容的提问来源于stack exchange，提问作者ER.Silwal