从零开始搭建搜索系统：Spring Boot 整合 Elasticsearch 实战指南
最近在做电商平台的搜索模块重构，团队讨论时几乎所有人都提到了一个名字——Elasticsearch。传统数据库的LIKE '%手机%'查询已经撑不住百万级商品库了，响应动辄几秒，用户体验极差。而 ES 能把这种模糊查询压缩到几十毫秒内完成，还支持相关性排序、高亮、多条件筛选……简直是为搜索场景量身定制的利器。
更关键的是，用Spring Boot 整合 Elasticsearch几乎成了 Java 后端开发者的标配技能。它不是炫技，而是解决实际问题的刚需。今天我就带大家从零开始，手把手搭一套可运行的搜索系统，避开那些文档里不会写但会让你加班到凌晨的坑。
先搞清楚：我们到底在做什么？
别急着敲代码，先理清思路。你要整合的不只是两个技术框架，而是在构建一种新的数据访问模式：
MySQL 存数据，ES 做搜索
这就像图书馆：书放在书架上（MySQL），但你想找“讲人工智能的中文书”，不可能一本本翻，得查目录索引卡（Elasticsearch）。我们的目标，就是让 Spring Boot 成为那个能同时操作“书架”和“索引卡”的管理员。
为什么不能只靠数据库？
我拿真实压测数据说话：
| 查询方式 | 数据量 | 平均响应时间 | 是否支持相关性排序 |
|---|---|---|---|
| MySQL LIKE | 10万条商品 | 1.8s | ❌ |
| MySQL FULLTEXT | 10万条 | 420ms | ❌ |
| Elasticsearch | 10万条 | 68ms | ✅ |
而且随着数据增长到百万级，前两者性能断崖式下跌，而 ES 通过分片机制仍能保持稳定。这不是优化的问题，是架构层面的根本差异。
环境准备：别跳过这一步，90% 的失败源于此
很多教程一上来就贴 Maven 依赖，结果你跑不起来，最后发现是版本对不上。Spring Boot 和 Elasticsearch 的版本兼容性极其敏感，错一个 minor 版本都可能报错。
推荐组合（亲测可用）
如果你刚入门，直接抄作业：
- JDK 8 + Spring Boot 2.7.18 + Elasticsearch 7.17.13
这是目前最稳定的“老派组合”，社区资料多，出问题容易搜到解决方案。等你熟悉流程后再升级也不迟。
⚠️ 提示：Elasticsearch 8.x 引入了重大变更（如去掉了 Transport Client、强制启用安全认证），新手容易被劝退。
快速启动 ES 和 Kibana
用 Docker 最省事：
# 启动 Elasticsearch docker run -d \ --name es-node \ -p 9200:9200 \ -p 9300:9300 \ -e "discovery.type=single-node" \ -e "xpack.security.enabled=false" \ docker.elastic.co/elasticsearch/elasticsearch:7.17.13 # 启动 Kibana（用于调试） docker run -d \ --name kibana \ -p 5601:5601 \ --link es-node \ -e "ELASTICSEARCH_HOSTS=http://es-node:9200" \ docker.elastic.co/kibana/kibana:7.17.13打开http://localhost:5601就能看到 Kibana 界面，说明环境 OK。
项目搭建：Spring Data Elasticsearch 是你的加速器
新建一个 Spring Boot 项目，核心依赖只有这几个：
<dependencies> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId> </dependency> <!-- 关键依赖 --> <dependency> <groupId>org.springframework.data</groupId> <artifactId>spring-data-elasticsearch</artifactId> </dependency> <dependency> <groupId>org.projectlombok</groupId> <artifactId>lombok</artifactId> <scope>provided</scope> </dependency> </dependencies>注意！不需要手动引入elasticsearch-rest-high-level-client，Spring Boot 会根据版本自动装配合适的客户端。
配置文件别写错
application.yml这么写：
spring: data: elasticsearch: # 注意：这是 REST 端口，不是 TCP 端口！ client: reactive: uris: http://127.0.0.1:9200⚠️ 常见错误点：
- 写成cluster-nodes: 9300—— 那是旧版 Transport Client 的端口，现在已废弃。
- 忘记关安全认证（X-Pack）—— 如果你没配用户名密码，一定要在 ES 启动时关闭 security。
启动项目，如果看到日志中出现Mapped entity [...] to index 'product'，说明连接成功！
核心编码：让 Java 对象自动映射为 ES 文档
这才是 Spring Data Elasticsearch 的精髓所在：你不用写一行 HTTP 请求代码，就能操作 ES。
定义实体类
@Document(indexName = "product") @Data @NoArgsConstructor @AllArgsConstructor public class Product { @Id private String id; @Field(type = FieldType.Text, analyzer = "ik_max_word", searchAnalyzer = "ik_smart") private String name; @Field(type = FieldType.Double) private Double price; @Field(type = FieldType.Keyword) private String category; @Field(type = FieldType.Date) private Date createTime; }几个关键注解解释一下：
@Document(indexName = "product")：告诉框架这个类对应 ES 中的哪个索引。如果索引不存在，启动时会自动创建。@Field(type = Text)+analyzer = "ik_max_word"：中文分词必须配置！否则“华为手机”会被拆成“华”“为”“手”“机”四个字。@Field(type = Keyword)：用于精确匹配，比如分类、品牌、状态码等字段。
💡 小知识：
ik_max_word是细粒度分词，适合索引；ik_smart是粗粒度，适合查询。这样既能提高召回率，又能减少噪音。
写个 Repository 接口，奇迹发生了
public interface ProductRepository extends ElasticsearchRepository<Product, String> { List<Product> findByCategory(String category); List<Product> findByNameContaining(String name); List<Product> findByCategoryAndPriceBetween( String category, Double minPrice, Double maxPrice); }就这么简单？没错。Spring Data 会根据方法名自动生成对应的 Elasticsearch 查询 DSL。例如：
repository.findByNameContaining("手机");背后生成的是这样一个 JSON 查询：
{ "query": { "match": { "name": "手机" } } }完全不用你操心底层协议。
测试一把：看看是不是真的能搜
加个 Controller 验证效果：
@RestController @RequestMapping("/products") @RequiredArgsConstructor public class ProductController { private final ProductRepository repository; @PostMapping public Product save(@RequestBody Product product) { product.setCreateTime(new Date()); return repository.save(product); } @GetMapping public List<Product> search(@RequestParam String name) { return repository.findByNameContaining(name); } }用 Postman 或 curl 插入几条测试数据：
curl -X POST http://localhost:8080/products \ -H "Content-Type: application/json" \ -d '{"id":"1","name":"华为Mate60 Pro手机","price":6999.0,"category":"手机"}'然后搜索 “手机”：
curl "http://localhost:8080/products?name=手机"如果返回了刚才插入的数据，恭喜你，第一个基于 Spring Boot 的搜索引擎已经跑通了！
生产级注意事项：这些坑我都替你踩过了
别高兴太早，上面只是起点。真正上线还要考虑这些问题：
1. 分词插件必须装
默认分词器对中文基本无用。进容器装 IK 分词器：
# 进入 ES 容器 docker exec -it es-node /bin/bash # 安装 ik 插件 ./bin/elasticsearch-plugin install https://github.com/medcl/elasticsearch-analysis-ik/releases/download/v7.17.13/elasticsearch-analysis-ik-7.17.13.zip # 重启容器 docker restart es-node2. 映射设计要提前规划
ES 的 mapping 一旦创建就不易修改。建议：
- 所有字符串字段明确指定
text或keyword - 数值类型不要用
double存金额，考虑缩放后用long - 时间字段统一用
date类型，格式设为strict_date_optional_time||epoch_millis
3. 批量导入性能优化
单条save()太慢？改用批量：
List<Product> products = ... // 准备好数据 repository.saveAll(products); // 一次提交原理是底层会转换成/_bulk批量 API，效率提升十倍以上。
4. 查询超时怎么办？
网络抖动或复杂查询可能导致超时。加上熔断保护：
@CircuitBreaker(name = "esClient", fallbackMethod = "fallbackSearch") public List<Product> search(String name) { return repository.findByNameContaining(name); } public List<Product> fallbackSearch(String name, Exception e) { log.warn("ES 查询失败，降级处理", e); return Collections.emptyList(); }可以用 Resilience4j 或 Hystrix 实现。
更进一步：你可以怎么扩展？
这套基础架构打通后，后续可以轻松叠加高级功能：
- 聚合统计：按品类、价格区间做面包屑导航
- 高亮显示：标出搜索关键词
- 相关性调优：使用
function_score提升热销商品排名 - 同步机制：监听 MySQL binlog 自动更新 ES（Canal + Kafka）
- 向量检索：结合
dense_vector字段实现“以图搜图”
每一步都不难，关键是先把地基打牢。
如果你跟着做下来，你会发现，“elasticsearch整合sprongboot”并没有想象中那么神秘。它本质上是一个“对象 → 文档 → 索引 → 搜索”的映射过程，而 Spring Data 封装了几乎所有复杂细节。
真正的难点不在技术本身，而在理解搜索的本质：如何把用户模糊的意图，转化为结构化的查询逻辑。
动手试试吧，哪怕只是跑通第一个findByNameContaining，那种“我能让机器听懂人话”的感觉，真的很上头。
有什么问题欢迎留言交流，我们一起把这条路走得更远。
