Redis OM Spring 索引注解完全指南：@Indexed/@Searchable/@GeoIndexed 一文掌握

Redis OM Spring 索引注解完全指南：@Indexed/@Searchable/@GeoIndexed 一文掌握

【免费下载链接】redis-om-springSpring Data Redis extensions for better search, documents models, and more项目地址: https://gitcode.com/gh_mirrors/re/redis-om-spring

你是否在 Spring Boot 项目里用过 Redis，却只能靠手动拼 Key、自己写搜索逻辑？Redis OM Spring正是为解决这个问题而生的开源框架——它是 Spring Data Redis 的扩展，让你像写 JPA 一样，用注解轻松完成全文搜索、文档模型、地理检索、向量相似度搜索。而这一切的起点，就是本文要讲的三大核心索引注解：@Indexed、@Searchable和@GeoIndexed。掌握它们，你就能用几行注解换来 Redis 查询引擎（原 RediSearch）的完整能力。🚀

什么是 Redis OM Spring 索引注解？一文看懂原理

在 Redis OM Spring 中，实体类字段默认是不建立索引的。只有给字段加上索引注解，Redis 查询引擎才会为该字段创建索引结构，之后你的 Repository 方法（如findByName）才能被翻译成高效的查询命令。

框架会根据你选择的注解，自动在应用启动时生成对应的索引，全程零手写命令。索引注解的源码位于 annotations 包，你可以在 Indexed.java、Searchable.java 中查看它们的完整配置项。

@Indexed：自动检测的万能索引注解

@Indexed是使用频率最高的注解，它的杀手锏是类型自动检测（AUTODETECT）：你只需要标注字段，框架会根据 Java 类型自动选择索引方式，一个注解通吃绝大多数场景。

@Document public class Company { @Id private String id; @Indexed // String 字段 → TAG 索引 private String email; @Indexed // Integer 字段 → NUMERIC 索引 private Integer yearFounded; @Indexed // Point 字段 → GEO 索引 private Point location; @Indexed // Set<String> → TAG 索引（多值） private Set<String> tags; }

@Indexed 支持的字段类型速查表

💡 真实案例：官方演示项目 roms-documents 的 Company.java 就同时使用了@Indexed处理地理位置、员工人数、成立年份和标签集合。

@Indexed 高频配置项

其中lexicographic = true值得一提：开启后框架会额外维护一个有序集合，让你可以用findBySkuGreaterThan("ABC123")、findBySkuBetween("A","Z")这样的方法对字符串做字典序范围查询，非常适合 SKU、版本号、ID 区间等场景。

@Searchable：全文搜索的利器

如果说@Indexed解决"找得到"，那@Searchable就是解决"搜得好"。它把字段建成TEXT 索引，支持分词、词干提取（Stemming）、加权打分等全文搜索能力。

@Document("games") public class Game { @Id private String asin; @Searchable(sortable = true, weight = 2.0) private String title; // 权重更高，标题命中排序更靠前 @Searchable(nostem = true) private String brand; // 品牌名不做词干处理，避免误匹配 }

@Searchable 核心配置项

• weight：字段权重（默认 1.0），调高可让该字段的命中在结果排序中更靠前
• sortable：开启后可按该字段排序
• nostem：关闭词干提取，适合专有名词、品牌、代码
• phonetic：开启语音匹配（如 Double Metaphone），可模糊匹配发音相似的词
• indexMissing/indexEmpty：支持对 null 和空字符串的查询

全文搜索与普通字段过滤配合使用，就是经典的**混合搜索（Hybrid Search）**方案。参考演示项目 roms-hybrid 的 Product.java，它用@Searchable做描述全文检索，同时用@Indexed做分类过滤和价格区间，还叠加了向量字段做语义搜索。

@GeoIndexed：地理位置的精确检索

做外卖、出行、门店导航类应用？@GeoIndexed就是为你准备的。它专门针对地理位置字段（org.springframework.data.geo.Point）建立GEO 索引，让"找附近"变成一条查询。

import org.springframework.data.geo.Point; @Document public class Company { @Id private String id; @GeoIndexed private Point location; // 经度、纬度 }

之后在 Repository 中就能直接写findByLocationNear(Point, Distance)这样的方法，实现"方圆 5 公里内的公司"之类的需求。需要注意：@GeoIndexed只提供fieldName、alias、noindex三个简单配置项，更复杂的 GEO 场景（如距离排序）由查询层配合完成。实际上，用@Indexed标注Point字段效果完全等价，@GeoIndexed胜在语义清晰、代码自解释。

其他索引注解速查：一张表掌握全家桶

除了三大主角，Redis OM Spring 还提供了一批专用注解，帮你更精确地表达意图：

官方对这些注解的完整说明，参见文档 index-annotations.adoc。

进阶技巧：索引注解的 3 个实战经验

1. 用 indexMissing 精确处理 null 值

默认情况下 null 值不会被索引，导致findByTitleIsNull()查询不到记录。在字段上加上indexMissing = true（需 Redis Stack 2.10+），即可让 null 值参与索引，从而精确区分"字段缺失"和"字段为 null"。

2. 控制索引创建时机

索引默认在应用启动时自动创建（CREATE_IF_NOT_EXIST）。你可以在@Document上通过indexCreationMode切换模式：RECREATE_INDEXES（每次启动重建）或NO_CREATE_NO_DROP（完全手动管理）。详见文档 index-creation.adoc。

3. 只索引需要查询的字段

每个索引都要消耗内存和写入开销。请克制地使用sortable = true（会显著增加内存），只给真正参与查询、排序的字段加索引——这是性能优化的第一原则。

最佳实践：如何选择索引注解？

一句话总结选型策略：

• 通用场景→@Indexed（自动检测，够用且简单）
• 全文搜索→@Searchable（分词、加权、语音匹配）
• 分类精确过滤→@TagIndexed
• 价格等数值范围→@NumericIndexed
• 地理位置→@GeoIndexed
• AI 语义检索→@VectorIndexed或@Indexed的 VECTOR 配置

索引注解只是第一步，配上框架自动生成的 Repository 与元模型（Metamodel），你就能以类型安全的方式写出所有查询——这就是 Redis OM Spring 让 Java 开发者告别"手写 Redis 命令"的底气。建议你克隆官方仓库git clone https://gitcode.com/gh_mirrors/re/redis-om-spring，在demos/目录下对照本文跑一遍 roms-documents、roms-hybrid 等示例，亲手感受注解带来的开发效率提升！✨

【免费下载链接】redis-om-springSpring Data Redis extensions for better search, documents models, and more项目地址: https://gitcode.com/gh_mirrors/re/redis-om-spring