必须使用 Spring Data Couchbase 5.7.x 及以上版本，适配 Jakarta EE 9+ 和 Java 17+，正确配置 starter 依赖、连接参数与无 Schema 实体，并通过 N1QL 实现动态查询。
要在 Spring Boot 5.7 中集成 Couchbase 实现面向文档的灵活 Schema 存储，必须使用与 Spring Boot 5.7 兼容的 Spring Data Couchbase 版本（需 ≥ 5.7.x），否则启动时会因 Bean 注入失败或类型不匹配直接报错退出；Spring Boot 5.7 已全面基于 Jakarta EE 9+，所有 javax.* 包已被移除，旧版 couchbase-client 2.x 或 spring-data-couchbase 4.x 将无法编译通过。
确认环境与依赖版本
第一步：检查 Java 版本是否为 【Java 17 或更高版本】。Spring Boot 5.7 不再支持 Java 8/11，使用低版本 JDK 会导致 maven 编译失败且错误提示模糊（如 “class file has wrong version”）。
第二步：在 pom.xml 中声明正确坐标。Spring Boot 5.7 使用 spring-boot-starter-data-couchbase 5.7.0（对应 spring-data-couchbase 5.7.0，底层绑定 couchbase-java-client 3.4.6）：
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-data-couchbase</artifactId>
<version>5.7.0</version>
</dependency>
注意：不要手动引入 com.couchbase.client:java-client，starter 内已传递依赖，重复引入易引发 NoClassDefFoundError（如 Missing class: com.couchbase.client.core.deps.io.netty.buffer.ByteBuf）。
配置连接参数
在 application.yml 中写入集群连接信息：
spring:
couchbase:
bootstrap-hosts: localhost
bucket:
name: default
password: ""
env:
timeouts:
connect: 5000
kv: 2500
这一步必须确保 bootstrap-hosts 指向正在运行的 Couchbase Server 7.6+ 实例；若填错地址或端口未开放，应用将在启动阶段卡在 Cluster.connect() 并超时抛出 TimeoutException，不会进入后续 Bean 初始化流程。
定义无 Schema 约束的实体
方法一：使用 @Document + @Id，字段完全自由
@Document
public class Product {
@Id
private String sku;
private String name;
private BigDecimal price;
private Map<String, Object> attributes; // 支持任意嵌套 JSON 字段
private List<String> tags;
// 构造函数、getter/setter 省略
}
方法二：彻底放弃注解，用 Map<String, Object> 直接存档
Map<String, Object> doc = new HashMap<>();
doc.put("id", "prod-1001");
doc.put("type", "product");
doc.put("spec", Map.of("cpu", "M3", "ram", 16));
doc.put("launch_date", LocalDate.now());
couchbaseTemplate.upsertById("default")
.withId("prod-1001")
.withDocument(EncodedDocument.from(doc))
.execute();
这一步的关键在于：Couchbase 不校验字段名、类型或必填性，Product 类中新增字段无需改表结构或执行迁移脚本，直接写入即可生效。
启用动态字段查询（N1QL）
① 在实体类上添加 @Field 注解可选标记索引字段（非必需，但大幅提升查询性能）：
private String category;
@Field(index = IndexMode.TRUE)
private String brand;
② 创建自定义 N1QL 查询仓库方法：
public interface ProductRepository extends CrudRepository<Product, String> {
List<Product> findByBrandAndPriceBetween(String brand, BigDecimal min, BigDecimal max);
@Query("SELECT * FROM `default` WHERE type = 'product' AND attributes.color = $1")
List<Product> findByColor(String color);
}
③ 启动时自动创建 primary index（仅开发环境）：
spring.couchbase.auto-index=true
生产环境禁止开启此配置，必须由 DBA 手动创建覆盖索引，否则全扫描将拖垮集群响应。
