企业官网建设流程全解析

1. 问题现场：注解加了，索引却迟迟没生效

先说说我遇到的实际问题。当时在做一个订单相关的模拟项目，订单集合数据量涨得很快，按照用户ID加创建时间的组合查询越来越慢。于是很自然地在实体类上加了@CompoundIndexes，想搞一个复合索引来加速查询。代码写完之后，重启了应用，满心以为索引自动建好，查询就会飞起来。结果一跑慢查询日志，执行计划还是全集合扫描，@CompoundIndexes就跟没写一样。

如果你也碰到过类似的情况——明明加上了注解，MongoDB 里却没有生成索引，或者索引存在但查询压根用不上，那这篇文章就是为你准备的。我会把这个注解的用法拆开揉碎讲清楚，同时把“不起作用”的常见原因逐个过一遍，顺便给出我自己实测有效的排查思路。不管你是刚接触 Spring Data MongoDB，还是已经踩过几个坑，按照这里面的步骤走一遍，基本都能找到症结所在。

先说结论：绝大多数情况下，索引“没效果”不是注解本身失效，而是它背后的触发机制、字段命名、查询条件和我们预想的不一致。搞清楚这两张表——注解怎么用，索引怎么走，问题就解决了一半。

2. @CompoundIndexes 到底是什么，为什么需要它

2.1 索引与复合索引的基础逻辑

MongoDB 的索引机制，可以粗暴地理解成书的目录。没有目录的时候，你想找某个词，只能一页一页翻（集合扫描）；有了目录，直接查页码再翻到对应页（索引查找）。单字段索引只对一个字段排序，复合索引则同时对多个字段建立排序结构，它的核心价值在于“同时作为多个查询条件的加速器”。

举个例子。订单集合里的查询经常是：

db.order.find({ userId: "U10086", createTime: { $gte: ISODate("2024-01-01") } })

如果只有 userId 上的单字段索引，MongoDB 可以先通过 userId 缩小范围，再在结果集里过滤 createTime，这个过程叫 index scan + fetch，整体效率还不错。但如果只有 createTime 索引，那就只能先扫某段时间的所有订单，再逐一匹配 userId，效率就差多了。复合索引{ userId: 1, createTime: -1 }直接让这两个字段的匹配都在索引树里完成，回表次数大幅减少。

2.2 注解的定位：Spring Data 的领域模型映射

@CompoundIndexes是 Spring Data MongoDB 提供的一个注解，它可以放在@Document实体类上，用来声明复合索引。Java 代码里不写原生脚本，就能在应用启动时自动为对应的集合创建索引。它本质上是一种“声明式索引管理”，让索引定义和实体模型放在一起，便于维护。

基本写法如下：

@Document(collection = "order") @CompoundIndexes({ @CompoundIndex(name = "user_time_idx", def = "{'userId': 1, 'createTime': -1}"), @CompoundIndex(name = "order_status_time_idx", def = "{'status': 1, 'createTime': -1}") }) public class OrderEntity { private String userId; private String status; private Date createTime; // 其他字段... }

注意一个细节：@CompoundIndex里的def是一个 JSON 字符串，字段名必须是 MongoDB 文档里存的字段名，而不仅仅是 Java 属性名。如果实体类里 Java 属性是userId，但通过@Field("user_id")映射到了user_id，那么def里就必须写'user_id': 1，写'userId': 1创建出来的索引字段根本不存在，查询照样用不上。

2.3 注解的完整属性清单

@CompoundIndex注解包含以下属性，逐一说明：

这里最常见的一个理解偏差就是expireAfterSeconds。很多人以为复合索引加了这个参数就能自动删旧数据，其实不行。MongoDB 的 TTL 索引必须建立在单个日期字段上，复合索引的 TTL 行为未定义。真要做过期数据清理，单独在 createTime 字段上一个@Indexed(expireAfterSeconds = 3600)才是正道。

2.4 Spring Data 的索引创建机制：为什么要为“不起作用”背锅

要理解“不起作用”，必须先搞清楚 Spring Data MongoDB 在什么时机创建索引。

应用启动时，Spring Data 会通过MongoPersistentEntityIndexResolver扫描所有的@Document实体类，解析其中的索引注解，再调用MongoTemplate的indexOps()对每个集合执行索引创建。这个流程是自动的，默认在实体映射初始化阶段触发。

问题来了：这个自动创建依赖两个条件。第一，你的实体类被 Spring 容器扫描到，也就是必须处于组件扫描路径下，并且被@Document标注。第二，应用启动时 MongoDB 必须能连接上，如果连接失败，索引创建自然不会执行。

更隐蔽的是：如果集合已经存在，且索引名与已存在的索引同名，Spring Data 不会主动去修改它。比如你在某个实体类上定义了一个名为user_time_idx的索引，线上集合里恰好已经有一个同名但字段顺序不同的user_time_idx，Spring Data 调用ensureIndex可能不会报错，但实际上新索引并没有被创建。这种情况下，注解“看起来”还在，实际主导查询的仍然是旧索引。

所以，我现在的习惯是：每次修改索引定义之后，不光重启应用，还会连到 MongoDB 里确认索引到底建没建、字段方向对不对，而不是默认“注解加了就万事大吉”。

3. 正确使用 @CompoundIndexes 的完整姿势

3.1 基本用法与字段顺序的黄金法则

复合索引的大忌：字段顺序乱写。

@CompoundIndexes里的def字段声明顺序，就是索引键的优先级顺序。MongoDB 查询要想命中复合索引，查询条件里必须包含索引前缀字段。所谓前缀字段，就是索引定义里排在最前面的字段。

比如索引是{userId: 1, createTime: -1}，下面的查询可以用上索引：

db.order.find({ userId: "U10086", createTime: { $gte: ISODate("2024-01-01") } }) db.order.find({ userId: "U10086" })

但下面的查询用不上：

// 没有 userId，只有 createTime db.order.find({ createTime: { $gte: ISODate("2024-01-01") } })

这就意味着：你的查询条件里最高频、最具区分度的等值匹配字段，要放在复合索引的最前面。

以订单场景为例，{userId: 1, status: 1, createTime: -1}和{status: 1, userId: 1, createTime: -1}看起来都是三个字段，但适用场景完全不同。如果我们的查询模式总是“先按用户查，再按状态过滤”，前者就是对的。如果经常是“平台运营查所有某个状态的订单”，后者反而更好。没有全局最优，只有针对具体业务查询模式的局部最优。

3.2 代码示例：一个可复用的标准写法

假设我们要做一个订单查询接口，常见的入参是先按用户ID、再按订单状态、最后按创建时间倒序。那么索引可以这样定义：

@Document(collection = "order") @CompoundIndexes({ @CompoundIndex( name = "idx_user_status_time", def = "{'userId': 1, 'status': 1, 'createTime': -1}", background = true ) }) public class OrderEntity { @Id private String id; @Field("user_id") private String userId; @Field("status") private String status; @Field("create_time") private Date createTime; // getter / setter 省略 }

注意我这里用了@Field("user_id")把 Java 属性映射成了数据库字段名。那么在def中必须写'user_id': 1，而不是'userId': 1。这是我见过最容易踩的坑，后面会重点讲。

对应的查询代码：

Query query = new Query(); query.addCriteria(Criteria.where("user_id").is("U10086")); query.addCriteria(Criteria.where("status").is("PAID")); query.addCriteria(Criteria.where("create_time").gte(startTime).lte(endTime)); query.with(Sort.by(Sort.Direction.DESC, "create_time")); List<OrderEntity> orders = mongoTemplate.find(query, OrderEntity.class);

这个查询的等值字段（user_id、status）都在索引前缀里，排序字段（create_time）也和索引定义的方向一致，可以完整命中idx_user_status_time。

3.3 索引方向、排序与查询的匹配关系

很多人忽略排序方向。MongoDB 的复合索引在匹配查询条件之后，如果结果的排序顺序恰好和索引顺序一致，就可以直接按索引顺序返回，省掉一次排序开销。如果索引定义是createTime: -1，查询里排序也是createTime DESC，那就是最佳的。如果你在代码里用Sort.by(Sort.Direction.ASC, "create_time")，那索引方向反过来，MongoDB 有可能会做 in-memory sort，严重时甚至会放弃索引。

再强调一个细节：复合索引的“方向”在不同字段间其实是可以灵活搭配的。对于{a: 1, b: -1}，等值查询a时，b的方向对最终排序影响很大。如果你无法确定查询的排序方向，一个通用的妥协方案是让索引方向跟随最常用排序方向。不允许来回改，尽量一次定好。

3.4 后台创建与唯一约束的收尾细节

对于订单量很大的集合，创建索引会阻塞数据库操作相当长时间。background = true可以让索引在后台构建，业务读写不被完全卡死。注意，在 MongoDB 4.2 及以后的版本里，创建索引本身已经有更细的构建选项，但 Spring Data 注解层面依然支持background配置。大数据量场景实测下来，这个参数值得开。

unique = true则要小心。如果集合里已经存在重复键，索引创建会直接失败，应用启动时可能会抛DuplicateKeyException或者索引创建失败的错误。如果你要加唯一约束，先确认旧数据是否有重复。

3.5 部分索引与稀疏索引怎么选

sparse = true说的是索引只对包含该字段的文档生效。比如订单实体新增了一个可选字段promotionId，大部分订单没有这个字段，你想查某个促销活动的订单时可以用普通索引，但让所有订单都进索引树会浪费空间，此时用稀疏索引就比较合适。

partialFilter比sparse更灵活，它支持写过滤条件，类似：

@CompoundIndex( name = "idx_status_time_partial", def = "{'status': 1, 'createTime': -1}", partialFilter = "{'status': {'$in': ['PAID', 'REFUND']}}" )

只有status是PAID或REFUND的文档才会进入索引。这在一些数据冷热分明的场景特别有用——只给活跃数据建索引，索引体积和更新成本会明显下降。

4. 排查实录：让“不起作用”的索引真正跑起来

4.1 第一步：先确认索引到底建没建

这是最基础但很多人跳过的步骤。直接用 MongoDB Shell 或者可视化工具查看集合索引：

db.order.getIndexes()

输出里会列出这个集合所有索引。你要找的是通过@CompoundIndexes定义的那个名称。如果压根没有，说明 Spring Data 没有执行索引创建，或者执行失败被吞掉。

再检查应用启动日志。Spring Data 在创建索引时通常会输出类似下面的日志：

Ensuring index idx_user_status_time on collection order

如果连这行日志都没有，大概率是实体类没有被扫描到。看看你的实体类是否在@SpringBootApplication所在的包或者其子包下，是否确实标注了@Document。如果实体类被随便放在一个没有扫描到的包里，注解自然不会被解析。

如果日志显示索引创建出错，比如字段名非法、重复键冲突，也会给出异常栈。逐个解决就好。

4.2 第二步：直接手动创建索引，对比查询计划

为了快速定位是不是注解本身的问题，可以先手动在 MongoDB 里创建同名字的索引：

db.order.createIndex({ user_id: 1, status: 1, create_time: -1 }, { name: "idx_user_status_time", background: true })

然后跑一次查询，用explain看执行计划：

db.order.find({ user_id: "U10086", status: "PAID", create_time: { $gte: ISODate("2024-01-01"), $lte: ISODate("2024-01-31") } }).sort({ create_time: -1 }).explain("executionStats")

在返回的executionStats里看totalDocsExamined和totalKeysExamined。如果totalDocsExamined等于命中文档数，说明走了索引；如果totalDocsExamined等于全集合文档数，说明全集合扫描。同时看winningPlan里的stage是FETCH加IXSCAN还是COLLSCAN。IXSCAN才是走了索引。

手动创建后如果查询能走索引，而注解方式不行，那么问题基本锁定在 Spring Data 解析或自动创建环节。如果手动创建也走不了索引，那就是查询条件或者索引定义本身不匹配。

4.3 第三步：检查索引字段名与实际文档字段名是否一致

我遇到最多的“不起作用”，归根结底是字段名映射不一致。

Java 属性是userId，但 Spring Data 默认会把属性名当作字段名存到 MongoDB。如果你没有加@Field，那 MongoDB 里的字段就是userId。但订单表很可能通过@Field("user_id")映射，或者数据库里本身是user_id。你却在def里写了'userId': 1。索引建出来了，但索引里的字段在文档里根本不存在。

判断方法很简单：随便查一条文档看看真实字段名。

db.order.findOne()

把文档里的实际 key 和索引def里的字段名逐字对比，大小写、下划线都不能错。注意def里的字段顺序也必须是查询条件依赖的前缀顺序。这一步排查成本最低，收益最高。

4.4 第四步：检查查询条件是否满足复合索引的最左前缀

即使索引建好了，查询也不一定命中。

假设索引是{user_id: 1, status: 1, create_time: -1}，如果你查询条件里只给了status和create_time，没有user_id，索引直接失效。这是复合索引规则决定的，Spring Data 和 MongoDB 不会有任何报错，只有执行计划告诉你真相。

还有一种情况是查询条件里第一个字段是范围查询而不是等值查询：

db.order.find({ create_time: { $gte: ... }, status: "PAID" })

如果索引的第一个字段是create_time，那么范围查询之后，后续字段的索引利用效率就很有限，甚至完全用不上。MongoDB 的复合索引在范围查询之后，后续字段的定位能力会大打折扣。所以设计复合索引时，要把等值过滤字段放在前面，范围字段放在后面。

4.5 第五步：排除排序方向与类型不一致

查询排序和索引顺序相反，也会造成索引失效后的内存排序。前面已经说过，这里再补充一个真实案例。某同学定义索引是{user_id: 1, create_time: -1}，查询里写Sort.by(Sort.Direction.ASC, "create_time")，结果执行计划出现了SORT阶段，而且是在FETCH之后。也就是说，索引虽然被用来定位了，但排序还得另做。如果排序数据量大，这个额外的排序代价可能抵消索引带来的收益。

另一个容易忽略的是类型不一致。比如文档里某个字段存的是字符串"2024-01-01"，查询条件用Date类型比较，索引查找会退化成低效的多次扫描。保持 Java 类型和 MongoDB 类型严格一致，是索引生效的前提。

4.6 第六步：注意 Spring Data 版本差异与索引自动创建开关

有些版本里，@CompoundIndexes自动创建索引的行为可能受spring.data.mongodb.auto-index-creation配置影响。默认情况下这个开关是 true 的，但如果项目里有人把它设成了 false，索引就不会自动创建。检查一下配置文件：

spring: data: mongodb: auto-index-creation: true

如果你用的 Spring Boot 版本比较旧，配置项名称可能会有所不同，但原理一样。另外，如果你引入了多数据源配置，或者自定义了MongoTemplate，索引自动创建也有可能被影响，需要在自定义配置里手动触发。

4.7 附一个典型的排查速查表

5. 实战案例：从注解到执行计划的完整验证

5.1 场景还原

用我前面提到的模拟订单系统来说明。实体类里加了这样的注解：

@Document(collection = "orders") @CompoundIndexes({ @CompoundIndex( name = "idx_user_time", def = "{'userId': 1, 'createTime': -1}", background = true ) }) public class Order { private String userId; private Date createTime; }

查询代码：

Query query = new Query( Criteria.where("userId").is("U10086") .and("createTime").gte(start) ); List<Order> list = mongoTemplate.find(query, Order.class);

这个案例中，索引看起来应该起作用。但实际排查时发现索引确实建出来了，查询却依旧慢。手动看getIndexes()返回的数据：

{ "v" : 2, "key" : { "userId" : 1, "createTime" : -1 }, "name" : "idx_user_time" }

索引没问题。再手动执行查询的explain：

db.orders.find({ userId: "U10086", createTime: { $gte: ISODate("2024-01-01") } })

返回的 winningPlan 是IXSCAN。那为什么应用里查询慢？

最终发现：应用查询里除了这两个条件，还多了一个Criteria.where("status").is("PAID")。因为status不在索引字段中，MongoDB 先走索引把某个用户某个时间段的所有订单都读出来，再过滤status。如果这个用户在时间段内订单很多，那FETCH数量依然很大。解决方式是追加索引字段，把索引改成了{ userId: 1, status: 1, createTime: -1 }，查询立刻快了一个量级。

5.2 命中索引与执行计划验证

在 Spring Data 中，想直接拿到explain结果可以使用：

Document explainDocument = mongoTemplate.getCollection("orders") .find(Filters.and( Filters.eq("userId", "U10086"), Filters.gte("createTime", start), Filters.eq("status", "PAID") )) .sort(Sorts.descending("createTime")) .explain();

或者用Query.explain()也可以。拿到结果后，重点检查queryPlanner.winningPlan中是否有IXSCAN节点。这是最直接的证据，比看日志、看时间都靠谱。

5.3 索引修改之后旧索引怎么处理

改索引定义之后，集合里很可能同时存在旧索引和新索引。Spring Data 的机制是不会帮你删旧索引的。也就是说，如果你把索引从idx_user_time改成了另一个定义，但idx_user_time还在，那么查询时优化器可能根据统计信息选择旧索引，新索引依然不被使用。

所以每次改了索引，我建议手动清理：

db.orders.dropIndex("idx_user_time")

再确认：

db.orders.getIndexes()

让集合里只保留真正需要的索引。索引不是越多越好，每个索引都会拖慢写入性能。无用的索引早删早好。

5.4 一个隐蔽的坑：equals 条件和正则条件混用

在 Spring Data 里，如果某个查询条件用了Regex，比如按订单号模糊查询：

Criteria.where("orderNo").regex("^ORD2024")

这种非精确匹配在复合索引里的表现，取决于正则是否锚定前缀。如果正则没有前缀锚定，MongoDB 基本无法用索引加速。同样，如果查询条件里用了$or，$or的每个分支需要分别命中索引，才能整体高效。这些都会让人觉得“索引不起作用”，其实是查询操作符本身限制了索引发挥空间。

5.5 关于索引统计信息的维护

MongoDB 的查询优化器会基于索引统计信息选择执行计划。如果数据出现剧烈变化，比如某字段的值分布发生了很大变化，旧的统计信息会让优化器选错索引。这时候可以用db.orders.aggregate([{ $indexStats: {} }])查看每个索引的被使用情况，如果某个索引长期没有命中记录，就要考虑删除或者调整。

6. 经验总结与几个值得记住的实操技巧

6.1 彩蛋技巧：启动时主动校验索引

为了不让“注解不生效”的问题拖到线上才发现，我现在的做法是在应用启动后的一个ApplicationRunner里主动校验关键集合的索引是否存在：

@Component public class IndexValidationRunner implements ApplicationRunner { @Autowired private MongoTemplate mongoTemplate; @Override public void run(ApplicationArguments args) { String collectionName = "orders"; Document requiredIndex = new Document("userId", 1).append("status", 1).append("createTime", -1); ListIndexesIterable<Document> indexes = mongoTemplate.getCollection(collectionName).listIndexes(); boolean found = false; for (Document index : indexes) { if (requiredIndex.equals(index.get("key"))) { found = true; break; } } if (!found) { throw new IllegalStateException("关键索引缺失，请检查 @CompoundIndexes 配置"); } } }

这样一旦索引没建成功，应用启动阶段就会直接报错，而不是等到查询变慢了才发现。

6.2 给新手的五条建议

第一，def字符串里的字段名，先查一遍 MongoDB 里文档的真实 key，不要想当然用 Java 属性名。第二，索引字段顺序以查询条件里的等值字段优先，范围字段放后面。第三，排序方向写进索引定义里，查询排序保持和索引一致。第四，修改索引后手动删除旧索引，避免优化器做出错误选择。第五，开启应用日志，观察启动时有没有Ensuring index日志，这是第一个信号。

6.3 扩展思考：除了复合索引，查询性能还能怎么优化

如果确认复合索引已经生效，但查询仍然不够快，可以从这几个方向继续优化。第一是数据模型设计，是否可以把经常一起查的大字段拆出去，减少单个文档的体积。第二是分页方式，深分页用skip会越来越慢，改用基于游标或_id分页会好很多。第三是定期使用db.collection.compact()或者重建索引，解决索引碎片问题。第四是考虑引入读写分离，把读请求分散到从节点。核心思想仍然是：先确认索引真正用上了，再去考虑其他优化手段。

根据我个人经验，@CompoundIndexes本身并不复杂，复杂的是它背后“索引何时生效、查询如何命中”的规则。只要把字段名、字段顺序、查询条件这三件事对齐，绝大多数问题都能在一小时之内搞定。你要是按上面的步骤排查完还是没生效，那基本可以看看是不是 MongoDB 版本和 Spring Data 版本之间的兼容性问题，升级驱动或者调整注解写法，多半就能解决。