尧图网页设计 
1. 从零搭一个 SpringBoot 整合 Elasticsearch 的 Java 案例为什么我选 CursorSpringBoot 整合 Elasticsearch 这件事说难不难说简单也容易踩坑。核心检索词就三个SpringBoot 提供 Web 层和依赖管理Elasticsearch 负责全文检索和聚合分析Cursor 负责把这两者之间的胶水代码快速生成出来。适合谁适合已经会写 Java、但没怎么碰过 ES 8.x 新客户端 API 的同学也适合想用 AI 编辑器把 CRUD 接口一次性铺完的后端。我这次的目标很明确用 Cursor 从零生成一个能跑起来的工程包含依赖引入、客户端配置、索引与文档 CRUD、条件查询接口最后用 HTTP 请求把每个接口都验证一遍。整个过程里Cursor 负责生成骨架和排错我负责判断它给的代码对不对、版本对不对。先说一个关键背景Elasticsearch 8.x 之后官方 Java 客户端从RestHighLevelClient换成了新的ElasticsearchClient包名是co.elastic.clients。很多老教程还在用RestHighLevelClient你如果直接抄编译能过但方法签名对不上或者干脆提示类找不到。Cursor 生成代码时如果没指定版本它可能给你混着写这就是后面报错的根源之一。所以这篇的路线是先让 Cursor 生成一版工程然后我逐段检查 pom、application.yml、Config、Service、Controller把版本对齐到 ES 8.x 的新客户端再启动验证。中间会遇到连接超时、认证失败、reading choices解析异常这几类典型问题我都会给出具体报错和修法。环境我用的是一台内网的 Elasticsearch 8.x监听 9200开了安全认证管理员账号是elastic。你如果本地用 Docker 起一个也行只要保证 SpringBoot 能访问到 9200 端口即可。下面开始动手。2. 用 Cursor 生成 SpringBoot 整合 Elasticsearch 工程的前置准备与依赖对齐2.1 给 Cursor 的提示词要写清楚版本和连接信息打开 Cursor新建一个空目录然后在 Chat 里输入提示词。提示词里必须包含三样东西SpringBoot 版本、Elasticsearch 版本、连接参数。我当时的提示词大意是使用 SpringBoot 3.2 整合 Elasticsearch 8.11Elasticsearch 服务器地址 192.168.236.134端口 9200启用 HTTPS管理员用户名 elastic密码 xxxxxx。生成完整的 Maven 工程包含索引创建、文档增删改查、关键词搜索接口。这里有个细节ES 8.x 默认开启 HTTPS 和认证如果你写http://而服务端是https://连接会直接失败。Cursor 有时候会默认给你生成 http所以提示词里要明确写 HTTPS。生成完之后Cursor 会给你一堆文件。别急着mvn spring-boot:run先看 pom.xml。2.2 pom.xml 依赖必须锁定 ES 8.x 新客户端Cursor 生成的 pom 里SpringBoot 的spring-boot-starter-data-elasticsearch会自动带一个 ES 客户端版本但这个版本不一定和你服务端的 8.11 对齐。更稳的做法是显式引入elasticsearch-java并锁定版本。我最终用的依赖片段如下properties java.version17/java.version elasticsearch.version8.11.4/elasticsearch.version /properties dependencies dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependency dependency groupIdco.elastic.clients/groupId artifactIdelasticsearch-java/artifactId version${elasticsearch.version}/version /dependency dependency groupIdcom.fasterxml.jackson.core/groupId artifactIdjackson-databind/artifactId /dependency dependency groupIdjakarta.json/groupId artifactIdjakarta.json-api/artifactId version2.1.3/version /dependency dependency groupIdorg.projectlombok/groupId artifactIdlombok/artifactId optionaltrue/optional /dependency /dependencies注意jakarta.json-api这个依赖ES 8.x 新客户端内部用 Jakarta JSON 做序列化缺了它会报NoClassDefFoundError: jakarta/json/JsonValue。Cursor 第一版没给我加是我 install 报错后补上的。2.3 application.yml 的连接参数配置文件我放在src/main/resources/application.yml内容如下server: port: 8080 elasticsearch: host: 192.168.236.134 port: 9200 username: elastic password: PdQy_xfR2yLhpok*MK_ scheme: https密码里有特殊字符YAML 里必须加引号否则*和会被解析出问题。这一点 Cursor 有时会漏导致启动时密码读进来是错的然后报 401。2.4 客户端配置类 ElasticsearchConfig这是整个工程的核心。ES 8.x 新客户端的构建方式和老版本完全不同需要先建RestClient再包一层ElasticsearchTransport最后生成ElasticsearchClient。代码如下Configuration public class ElasticsearchConfig { Value(${elasticsearch.host}) private String host; Value(${elasticsearch.port}) private int port; Value(${elasticsearch.username}) private String username; Value(${elasticsearch.password}) private String password; Value(${elasticsearch.scheme}) private String scheme; Bean public ElasticsearchClient elasticsearchClient() { String address scheme :// host : port; RestClient restClient RestClient.builder(HttpHost.create(address)) .setHttpClientConfigCallback(httpClientBuilder - { httpClientBuilder.setDefaultCredentialsProvider( new BasicCredentialsProvider() {{ setCredentials(AuthScope.ANY, new UsernamePasswordCredentials(username, password)); }} ); try { SSLContext sslContext SSLContextBuilder.create() .loadTrustMaterial((chain, authType) - true) .build(); httpClientBuilder.setSSLContext(sslContext); } catch (Exception e) { throw new RuntimeException(SSL 初始化失败, e); } return httpClientBuilder; }) .build(); ElasticsearchTransport transport new RestClientTransport( restClient, new JacksonJsonpMapper()); return new ElasticsearchClient(transport); } }这里loadTrustMaterial((chain, authType) - true)是信任所有证书仅用于内网自签证书场景。生产环境要换成正式证书校验这点后面最佳实践里会提。2.5 实体类 ProductData NoArgsConstructor AllArgsConstructor public class Product { private String id; private String name; private String description; private Double price; private String category; }字段和 ES 索引 mapping 对应id用 String 是为了和接口传参一致。3. 可复制的索引与文档 CRUD 配置Service 与 Controller 完整代码3.1 ElasticsearchService 的索引操作索引名我定为products。创建索引前先判断是否存在避免重复创建报错Service RequiredArgsConstructor public class ElasticsearchService { private final ElasticsearchClient client; private static final String INDEX products; public String createIndex() throws IOException { boolean exists client.indices().exists(e - e.index(INDEX)).value(); if (exists) { return 索引已存在; } client.indices().create(c - c .index(INDEX) .mappings(m - m .properties(id, p - p.keyword(k - k)) .properties(name, p - p.text(t - t)) .properties(description, p - p.text(t - t)) .properties(price, p - p.double_(d - d)) .properties(category, p - p.keyword(k - k)) ) ); return 索引创建成功; } }name和description用text类型才能被分词搜索category用keyword适合精确过滤和聚合。3.2 文档增删改查public String addProduct(Product product) throws IOException { client.index(i - i .index(INDEX) .id(product.getId()) .document(product) ); return 产品添加成功ID: product.getId(); } public Product getProduct(String id) throws IOException { GetResponseProduct response client.get(g - g .index(INDEX) .id(id), Product.class); return response.found() ? response.source() : null; } public String updateProduct(Product product) throws IOException { client.update(u - u .index(INDEX) .id(product.getId()) .doc(product), Product.class); return 产品更新成功ID: product.getId(); } public String deleteProduct(String id) throws IOException { client.delete(d - d.index(INDEX).id(id)); return 产品删除成功ID: id; }3.3 关键词搜索接口搜索用multiMatch同时匹配name和descriptionpublic ListProduct searchProducts(String keyword) throws IOException { SearchResponseProduct response client.search(s - s .index(INDEX) .query(q - q .multiMatch(m - m .query(keyword) .fields(name, description) ) ), Product.class); ListProduct result new ArrayList(); for (HitProduct hit : response.hits().hits()) { result.add(hit.source()); } return result; }3.4 Controller 暴露 REST 接口RestController RequestMapping(/api/products) RequiredArgsConstructor public class ProductController { private final ElasticsearchService service; PostMapping(/index) public String createIndex() throws IOException { return service.createIndex(); } PostMapping public String add(RequestBody Product product) throws IOException { return service.addProduct(product); } GetMapping(/{id}) public Product get(PathVariable String id) throws IOException { return service.getProduct(id); } PutMapping public String update(RequestBody Product product) throws IOException { return service.updateProduct(product); } GetMapping(/search) public ListProduct search(RequestParam String keyword) throws IOException { return service.searchProducts(keyword); } DeleteMapping(/{id}) public String delete(PathVariable String id) throws IOException { return service.deleteProduct(id); } }到这里工程骨架就齐了。你可以把这几段直接复制进对应文件包名按自己的改。接下来启动验证。4. 启动后调用接口验证搜索结果从创建索引到关键词查询4.1 启动应用mvn clean install mvn spring-boot:run看到Started Application in x.x seconds就说明起来了。如果启动阶段就报连接错误先别慌看第 5 节的排错。4.2 创建索引curl -X POST http://localhost:8080/api/products/index预期返回索引创建成功。再调一次会返回索引已存在说明幂等判断生效。4.3 添加产品curl -X POST http://localhost:8080/api/products \ -H Content-Type: application/json \ -d { id: 1, name: iPhone 13, description: 苹果最新款手机性能强劲, price: 6999.0, category: 手机 }返回产品添加成功ID: 1。再补几条数据方便搜索验证curl -X POST http://localhost:8080/api/products \ -H Content-Type: application/json \ -d {id:2,name:华为 Mate 50,description:华为旗舰手机拍照性能出色,price:5999.0,category:手机} curl -X POST http://localhost:8080/api/products \ -H Content-Type: application/json \ -d {id:3,name:MacBook Pro,description:苹果专业笔记本电脑适合开发人员,price:12999.0,category:笔记本电脑}4.4 获取与更新curl http://localhost:8080/api/products/1 curl -X PUT http://localhost:8080/api/products \ -H Content-Type: application/json \ -d {id:1,name:iPhone 13 Pro,description:苹果最新款专业版手机,price:8999.0,category:手机}4.5 关键词搜索curl http://localhost:8080/api/products/search?keyword苹果预期返回 iPhone 13 Pro 和 MacBook Pro 两条因为它们的name或description里含「苹果」。再试curl http://localhost:8080/api/products/search?keyword华为 curl http://localhost:8080/api/products/search?keyword电脑华为命中 Mate 50电脑命中 MacBook Pro。这说明multiMatch对中英文都做了分词匹配。4.6 删除curl -X DELETE http://localhost:8080/api/products/1返回产品删除成功ID: 1再 GET 一次会返回空。整个链路跑通说明 SpringBoot 整合 Elasticsearch 的 CRUD 和搜索都正常。下面是我踩过的几个坑。5. 本篇常见错排查连接超时、401 认证失败与 reading choices 解析异常5.1 连接超时 ConnectTimeoutException第一次启动时报的是java.net.ConnectException: Timeout connecting to [192.168.236.134/192.168.236.134:9200]我一开始以为是防火墙关了防火墙还是不通。后来发现两个原因叠加一是 ES 服务端配了 HTTPS我客户端写的是 http二是 ES 的network.host没绑定到外部网卡只监听了 127.0.0.1。改法服务端elasticsearch.yml里设network.host: 0.0.0.0客户端 scheme 改成https。改完重启连接正常。5.2 401 Unauthorized连接通了之后报co.elastic.clients.elasticsearch._types.ElasticsearchException: [es/index] failed: [security_exception] unable to authenticate user这是认证没带上。检查两点BasicCredentialsProvider有没有真正 set 进去以及密码里的特殊字符在 YAML 里有没有被截断。我那次是密码没加引号*被当成 YAML 别名符号读进来少了一段。加引号后解决。5.3 reading choices 解析异常搜索接口报com.fasterxml.jackson.databind.exc.MismatchedInputException: Cannot deserialize value of type ... from Object value (token JsonToken.START_OBJECT)或者日志里出现reading choices相关字样。这是JacksonJsonpMapper和 ES 返回的 JSON 结构对不上常见于客户端版本和服务端版本差太多。把elasticsearch-java版本对齐到服务端的 8.11.4 后消失。如果你用的是 SpringBoot 自带的 ES starter记得排除它自带的旧客户端显式引elasticsearch-java。5.4 OAuth / 证书校验失败如果服务端开了 HTTPS 但证书是自签的客户端会报PKIX path building failed。我在 Config 里用loadTrustMaterial((chain, authType) - true)跳过校验仅限内网。生产环境请导入正式 CA 证书。5.5 索引 mapping 冲突如果你先创建了索引后来又改了字段类型再写入会报mapper_parsing_exception。解决方式是删掉索引重建或者用索引别名做平滑迁移。开发阶段直接DELETE /products再重建最快。5.6 关于模型调用与 Key 管理排错过程中如果你想让 Cursor 帮你分析日志或者把报错喂给模型需要稳定的 API 通道。我这边统一用 TaoToken 的 API 入口https://taotoken.net/api来管理 Key模型对话在https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite接入文档在https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite。Key 的创建在https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite。把 Base URL、Key、Model ID 三件套配好Cursor 里分析报错会顺很多。6. 继续扩展用 Cursor 生成复杂查询与聚合把案例做深基础 CRUD 跑通后我让 Cursor 在此基础上加了两个进阶接口带分类和价格区间的组合查询以及按分类统计数量。这两个是 ES 实战里最常用的。组合查询用bool查询must放关键词filter放分类和价格范围public ListProduct searchAdvanced(String keyword, String category, Double minPrice, Double maxPrice) throws IOException { SearchResponseProduct response client.search(s - s .index(INDEX) .query(q - q.bool(b - { if (keyword ! null !keyword.isEmpty()) { b.must(m - m.multiMatch(mm - mm .query(keyword).fields(name, description))); } if (category ! null !category.isEmpty()) { b.filter(f - f.term(t - t.field(category).value(category))); } if (minPrice ! null || maxPrice ! null) { b.filter(f - f.range(r - { r.field(price); if (minPrice ! null) r.gte(JsonData.of(minPrice)); if (maxPrice ! null) r.lte(JsonData.of(maxPrice)); return r; })); } return b; })), Product.class); ListProduct list new ArrayList(); response.hits().hits().forEach(h - list.add(h.source())); return list; }聚合统计按分类分组public MapString, Long countByCategory() throws IOException { SearchResponseVoid response client.search(s - s .index(INDEX) .size(0) .aggregations(categories, a - a .terms(t - t.field(category).size(100))), Void.class); MapString, Long result new HashMap(); response.aggregations().get(categories).sterms().buckets().array() .forEach(b - result.put(b.key(), b.docCount())); return result; }对应 Controller 加两个端点重启后用 curl 验证curl http://localhost:8080/api/products/search/advanced?keyword手机category手机minPrice5000maxPrice8000 curl http://localhost:8080/api/products/stats/category聚合返回类似{手机:2,笔记本电脑:1}说明分组统计生效。如果你要长期用 Cursor 做这类 Java ES 的工程建议把常用的提示词模板和排错记录沉淀下来配合 Coding Plan 的额度做批量生成会更省心入口在https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite。控制台在https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewriteClaude Code 相关配置在https://taotoken.net/claude-code?utm_sourcetaotoken_aicg_blog_endutm_contentclaude_codeutm_campaignrewrite。最后留一个我自己的习惯每次让 Cursor 生成 ES 代码后先跑一遍mvn dependency:tree | grep elasticsearch确认客户端版本只有一个、且和服务端一致。这一步能省掉后面一大半的玄学报错。索引 mapping 一旦定下来就别频繁改字段类型开发期用DELETE /products重建比修 mapping 快得多。 使用 Cursor 开发 Java 案例——SpringBoot 整合 Elasticsearch 实战
1. 从零搭一个 SpringBoot 整合 Elasticsearch 的 Java 案例为什么我选 CursorSpringBoot 整合 Elasticsearch 这件事说难不难说简单也容易踩坑。核心检索词就三个SpringBoot 提供 Web 层和依赖管理Elasticsearch 负责全文检索和聚合分析Cursor 负责把这两者之间的胶水代码快速生成出来。适合谁适合已经会写 Java、但没怎么碰过 ES 8.x 新客户端 API 的同学也适合想用 AI 编辑器把 CRUD 接口一次性铺完的后端。我这次的目标很明确用 Cursor 从零生成一个能跑起来的工程包含依赖引入、客户端配置、索引与文档 CRUD、条件查询接口最后用 HTTP 请求把每个接口都验证一遍。整个过程里Cursor 负责生成骨架和排错我负责判断它给的代码对不对、版本对不对。先说一个关键背景Elasticsearch 8.x 之后官方 Java 客户端从RestHighLevelClient换成了新的ElasticsearchClient包名是co.elastic.clients。很多老教程还在用RestHighLevelClient你如果直接抄编译能过但方法签名对不上或者干脆提示类找不到。Cursor 生成代码时如果没指定版本它可能给你混着写这就是后面报错的根源之一。所以这篇的路线是先让 Cursor 生成一版工程然后我逐段检查 pom、application.yml、Config、Service、Controller把版本对齐到 ES 8.x 的新客户端再启动验证。中间会遇到连接超时、认证失败、reading choices解析异常这几类典型问题我都会给出具体报错和修法。环境我用的是一台内网的 Elasticsearch 8.x监听 9200开了安全认证管理员账号是elastic。你如果本地用 Docker 起一个也行只要保证 SpringBoot 能访问到 9200 端口即可。下面开始动手。2. 用 Cursor 生成 SpringBoot 整合 Elasticsearch 工程的前置准备与依赖对齐2.1 给 Cursor 的提示词要写清楚版本和连接信息打开 Cursor新建一个空目录然后在 Chat 里输入提示词。提示词里必须包含三样东西SpringBoot 版本、Elasticsearch 版本、连接参数。我当时的提示词大意是使用 SpringBoot 3.2 整合 Elasticsearch 8.11Elasticsearch 服务器地址 192.168.236.134端口 9200启用 HTTPS管理员用户名 elastic密码 xxxxxx。生成完整的 Maven 工程包含索引创建、文档增删改查、关键词搜索接口。这里有个细节ES 8.x 默认开启 HTTPS 和认证如果你写http://而服务端是https://连接会直接失败。Cursor 有时候会默认给你生成 http所以提示词里要明确写 HTTPS。生成完之后Cursor 会给你一堆文件。别急着mvn spring-boot:run先看 pom.xml。2.2 pom.xml 依赖必须锁定 ES 8.x 新客户端Cursor 生成的 pom 里SpringBoot 的spring-boot-starter-data-elasticsearch会自动带一个 ES 客户端版本但这个版本不一定和你服务端的 8.11 对齐。更稳的做法是显式引入elasticsearch-java并锁定版本。我最终用的依赖片段如下properties java.version17/java.version elasticsearch.version8.11.4/elasticsearch.version /properties dependencies dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependency dependency groupIdco.elastic.clients/groupId artifactIdelasticsearch-java/artifactId version${elasticsearch.version}/version /dependency dependency groupIdcom.fasterxml.jackson.core/groupId artifactIdjackson-databind/artifactId /dependency dependency groupIdjakarta.json/groupId artifactIdjakarta.json-api/artifactId version2.1.3/version /dependency dependency groupIdorg.projectlombok/groupId artifactIdlombok/artifactId optionaltrue/optional /dependency /dependencies注意jakarta.json-api这个依赖ES 8.x 新客户端内部用 Jakarta JSON 做序列化缺了它会报NoClassDefFoundError: jakarta/json/JsonValue。Cursor 第一版没给我加是我 install 报错后补上的。2.3 application.yml 的连接参数配置文件我放在src/main/resources/application.yml内容如下server: port: 8080 elasticsearch: host: 192.168.236.134 port: 9200 username: elastic password: PdQy_xfR2yLhpok*MK_ scheme: https密码里有特殊字符YAML 里必须加引号否则*和会被解析出问题。这一点 Cursor 有时会漏导致启动时密码读进来是错的然后报 401。2.4 客户端配置类 ElasticsearchConfig这是整个工程的核心。ES 8.x 新客户端的构建方式和老版本完全不同需要先建RestClient再包一层ElasticsearchTransport最后生成ElasticsearchClient。代码如下Configuration public class ElasticsearchConfig { Value(${elasticsearch.host}) private String host; Value(${elasticsearch.port}) private int port; Value(${elasticsearch.username}) private String username; Value(${elasticsearch.password}) private String password; Value(${elasticsearch.scheme}) private String scheme; Bean public ElasticsearchClient elasticsearchClient() { String address scheme :// host : port; RestClient restClient RestClient.builder(HttpHost.create(address)) .setHttpClientConfigCallback(httpClientBuilder - { httpClientBuilder.setDefaultCredentialsProvider( new BasicCredentialsProvider() {{ setCredentials(AuthScope.ANY, new UsernamePasswordCredentials(username, password)); }} ); try { SSLContext sslContext SSLContextBuilder.create() .loadTrustMaterial((chain, authType) - true) .build(); httpClientBuilder.setSSLContext(sslContext); } catch (Exception e) { throw new RuntimeException(SSL 初始化失败, e); } return httpClientBuilder; }) .build(); ElasticsearchTransport transport new RestClientTransport( restClient, new JacksonJsonpMapper()); return new ElasticsearchClient(transport); } }这里loadTrustMaterial((chain, authType) - true)是信任所有证书仅用于内网自签证书场景。生产环境要换成正式证书校验这点后面最佳实践里会提。2.5 实体类 ProductData NoArgsConstructor AllArgsConstructor public class Product { private String id; private String name; private String description; private Double price; private String category; }字段和 ES 索引 mapping 对应id用 String 是为了和接口传参一致。3. 可复制的索引与文档 CRUD 配置Service 与 Controller 完整代码3.1 ElasticsearchService 的索引操作索引名我定为products。创建索引前先判断是否存在避免重复创建报错Service RequiredArgsConstructor public class ElasticsearchService { private final ElasticsearchClient client; private static final String INDEX products; public String createIndex() throws IOException { boolean exists client.indices().exists(e - e.index(INDEX)).value(); if (exists) { return 索引已存在; } client.indices().create(c - c .index(INDEX) .mappings(m - m .properties(id, p - p.keyword(k - k)) .properties(name, p - p.text(t - t)) .properties(description, p - p.text(t - t)) .properties(price, p - p.double_(d - d)) .properties(category, p - p.keyword(k - k)) ) ); return 索引创建成功; } }name和description用text类型才能被分词搜索category用keyword适合精确过滤和聚合。3.2 文档增删改查public String addProduct(Product product) throws IOException { client.index(i - i .index(INDEX) .id(product.getId()) .document(product) ); return 产品添加成功ID: product.getId(); } public Product getProduct(String id) throws IOException { GetResponseProduct response client.get(g - g .index(INDEX) .id(id), Product.class); return response.found() ? response.source() : null; } public String updateProduct(Product product) throws IOException { client.update(u - u .index(INDEX) .id(product.getId()) .doc(product), Product.class); return 产品更新成功ID: product.getId(); } public String deleteProduct(String id) throws IOException { client.delete(d - d.index(INDEX).id(id)); return 产品删除成功ID: id; }3.3 关键词搜索接口搜索用multiMatch同时匹配name和descriptionpublic ListProduct searchProducts(String keyword) throws IOException { SearchResponseProduct response client.search(s - s .index(INDEX) .query(q - q .multiMatch(m - m .query(keyword) .fields(name, description) ) ), Product.class); ListProduct result new ArrayList(); for (HitProduct hit : response.hits().hits()) { result.add(hit.source()); } return result; }3.4 Controller 暴露 REST 接口RestController RequestMapping(/api/products) RequiredArgsConstructor public class ProductController { private final ElasticsearchService service; PostMapping(/index) public String createIndex() throws IOException { return service.createIndex(); } PostMapping public String add(RequestBody Product product) throws IOException { return service.addProduct(product); } GetMapping(/{id}) public Product get(PathVariable String id) throws IOException { return service.getProduct(id); } PutMapping public String update(RequestBody Product product) throws IOException { return service.updateProduct(product); } GetMapping(/search) public ListProduct search(RequestParam String keyword) throws IOException { return service.searchProducts(keyword); } DeleteMapping(/{id}) public String delete(PathVariable String id) throws IOException { return service.deleteProduct(id); } }到这里工程骨架就齐了。你可以把这几段直接复制进对应文件包名按自己的改。接下来启动验证。4. 启动后调用接口验证搜索结果从创建索引到关键词查询4.1 启动应用mvn clean install mvn spring-boot:run看到Started Application in x.x seconds就说明起来了。如果启动阶段就报连接错误先别慌看第 5 节的排错。4.2 创建索引curl -X POST http://localhost:8080/api/products/index预期返回索引创建成功。再调一次会返回索引已存在说明幂等判断生效。4.3 添加产品curl -X POST http://localhost:8080/api/products \ -H Content-Type: application/json \ -d { id: 1, name: iPhone 13, description: 苹果最新款手机性能强劲, price: 6999.0, category: 手机 }返回产品添加成功ID: 1。再补几条数据方便搜索验证curl -X POST http://localhost:8080/api/products \ -H Content-Type: application/json \ -d {id:2,name:华为 Mate 50,description:华为旗舰手机拍照性能出色,price:5999.0,category:手机} curl -X POST http://localhost:8080/api/products \ -H Content-Type: application/json \ -d {id:3,name:MacBook Pro,description:苹果专业笔记本电脑适合开发人员,price:12999.0,category:笔记本电脑}4.4 获取与更新curl http://localhost:8080/api/products/1 curl -X PUT http://localhost:8080/api/products \ -H Content-Type: application/json \ -d {id:1,name:iPhone 13 Pro,description:苹果最新款专业版手机,price:8999.0,category:手机}4.5 关键词搜索curl http://localhost:8080/api/products/search?keyword苹果预期返回 iPhone 13 Pro 和 MacBook Pro 两条因为它们的name或description里含「苹果」。再试curl http://localhost:8080/api/products/search?keyword华为 curl http://localhost:8080/api/products/search?keyword电脑华为命中 Mate 50电脑命中 MacBook Pro。这说明multiMatch对中英文都做了分词匹配。4.6 删除curl -X DELETE http://localhost:8080/api/products/1返回产品删除成功ID: 1再 GET 一次会返回空。整个链路跑通说明 SpringBoot 整合 Elasticsearch 的 CRUD 和搜索都正常。下面是我踩过的几个坑。5. 本篇常见错排查连接超时、401 认证失败与 reading choices 解析异常5.1 连接超时 ConnectTimeoutException第一次启动时报的是java.net.ConnectException: Timeout connecting to [192.168.236.134/192.168.236.134:9200]我一开始以为是防火墙关了防火墙还是不通。后来发现两个原因叠加一是 ES 服务端配了 HTTPS我客户端写的是 http二是 ES 的network.host没绑定到外部网卡只监听了 127.0.0.1。改法服务端elasticsearch.yml里设network.host: 0.0.0.0客户端 scheme 改成https。改完重启连接正常。5.2 401 Unauthorized连接通了之后报co.elastic.clients.elasticsearch._types.ElasticsearchException: [es/index] failed: [security_exception] unable to authenticate user这是认证没带上。检查两点BasicCredentialsProvider有没有真正 set 进去以及密码里的特殊字符在 YAML 里有没有被截断。我那次是密码没加引号*被当成 YAML 别名符号读进来少了一段。加引号后解决。5.3 reading choices 解析异常搜索接口报com.fasterxml.jackson.databind.exc.MismatchedInputException: Cannot deserialize value of type ... from Object value (token JsonToken.START_OBJECT)或者日志里出现reading choices相关字样。这是JacksonJsonpMapper和 ES 返回的 JSON 结构对不上常见于客户端版本和服务端版本差太多。把elasticsearch-java版本对齐到服务端的 8.11.4 后消失。如果你用的是 SpringBoot 自带的 ES starter记得排除它自带的旧客户端显式引elasticsearch-java。5.4 OAuth / 证书校验失败如果服务端开了 HTTPS 但证书是自签的客户端会报PKIX path building failed。我在 Config 里用loadTrustMaterial((chain, authType) - true)跳过校验仅限内网。生产环境请导入正式 CA 证书。5.5 索引 mapping 冲突如果你先创建了索引后来又改了字段类型再写入会报mapper_parsing_exception。解决方式是删掉索引重建或者用索引别名做平滑迁移。开发阶段直接DELETE /products再重建最快。5.6 关于模型调用与 Key 管理排错过程中如果你想让 Cursor 帮你分析日志或者把报错喂给模型需要稳定的 API 通道。我这边统一用 TaoToken 的 API 入口https://taotoken.net/api来管理 Key模型对话在https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite接入文档在https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite。Key 的创建在https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite。把 Base URL、Key、Model ID 三件套配好Cursor 里分析报错会顺很多。6. 继续扩展用 Cursor 生成复杂查询与聚合把案例做深基础 CRUD 跑通后我让 Cursor 在此基础上加了两个进阶接口带分类和价格区间的组合查询以及按分类统计数量。这两个是 ES 实战里最常用的。组合查询用bool查询must放关键词filter放分类和价格范围public ListProduct searchAdvanced(String keyword, String category, Double minPrice, Double maxPrice) throws IOException { SearchResponseProduct response client.search(s - s .index(INDEX) .query(q - q.bool(b - { if (keyword ! null !keyword.isEmpty()) { b.must(m - m.multiMatch(mm - mm .query(keyword).fields(name, description))); } if (category ! null !category.isEmpty()) { b.filter(f - f.term(t - t.field(category).value(category))); } if (minPrice ! null || maxPrice ! null) { b.filter(f - f.range(r - { r.field(price); if (minPrice ! null) r.gte(JsonData.of(minPrice)); if (maxPrice ! null) r.lte(JsonData.of(maxPrice)); return r; })); } return b; })), Product.class); ListProduct list new ArrayList(); response.hits().hits().forEach(h - list.add(h.source())); return list; }聚合统计按分类分组public MapString, Long countByCategory() throws IOException { SearchResponseVoid response client.search(s - s .index(INDEX) .size(0) .aggregations(categories, a - a .terms(t - t.field(category).size(100))), Void.class); MapString, Long result new HashMap(); response.aggregations().get(categories).sterms().buckets().array() .forEach(b - result.put(b.key(), b.docCount())); return result; }对应 Controller 加两个端点重启后用 curl 验证curl http://localhost:8080/api/products/search/advanced?keyword手机category手机minPrice5000maxPrice8000 curl http://localhost:8080/api/products/stats/category聚合返回类似{手机:2,笔记本电脑:1}说明分组统计生效。如果你要长期用 Cursor 做这类 Java ES 的工程建议把常用的提示词模板和排错记录沉淀下来配合 Coding Plan 的额度做批量生成会更省心入口在https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite。控制台在https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewriteClaude Code 相关配置在https://taotoken.net/claude-code?utm_sourcetaotoken_aicg_blog_endutm_contentclaude_codeutm_campaignrewrite。最后留一个我自己的习惯每次让 Cursor 生成 ES 代码后先跑一遍mvn dependency:tree | grep elasticsearch确认客户端版本只有一个、且和服务端一致。这一步能省掉后面一大半的玄学报错。索引 mapping 一旦定下来就别频繁改字段类型开发期用DELETE /products重建比修 mapping 快得多。