我是老李，上个月接了一个多租户商品中心的查询需求。起初我觉得 Spring Data MongoDB 的 Repository 太省事了，findByTenantIdAndCategory 一写，分页排序全都有。结果需求从两个条件变成五个，还出现可选区间，方法名差点写成一行作文。后来团队停下来重新划了条线：简单查询留在 Repository，动态查询切到 MongoTemplate。今天把这条线完整梳理出来。

## 01、痛点

商品中心首先是一个多租户系统，所有查询必须带 tenantId。最初商品列表只需要租户、类目、状态三个条件，我写了一个方法：

```java
Page<Product> findByTenantIdAndCategoryAndStatus(String tenantId, String category, String status, Pageable pageable);
```

看起来还好。但很快需求变了：前端要支持按品牌筛选、按价格区间筛选，而且有些条件可选。按照方法名推导的思路，下一步就是：

```java
Page<Product> findByTenantIdAndCategoryAndStatusAndBrandAndPriceBetween(...);
```

这已经长得离谱。更麻烦的是，category 可能为空，status 可能是多选，brand 也可能不传，价格区间上下限也可能只填一边。方法名推导本质上只适合“所有条件都必须出现”的固定查询，一旦条件变成可选，就完全没有办法。

如果为每种组合写一个方法，5 个条件最多会有 32 种组合，代码量直接爆炸。更糟的是，团队 review 开始出现分歧：有人继续用长方法名，有人开始往 Service 里塞 MongoTemplate，接口和实现越来越混乱。

## 02、是什么

MongoRepository 是 Spring Data MongoDB 提供给开发者的仓库接口。我们定义一个接口继承 `MongoRepository<Product, String>`，它就能自动获得基础的 CRUD、分页排序、方法名推导、自定义 `@Query` 和 Projection 投影能力。例如：

```java
public interface ProductRepository extends MongoRepository<Product, String> {
    Page<Product> findByTenantIdAndStatus(String tenantId, String status, Pageable pageable);
}
```

这里的 `findByTenantIdAndStatus` 就是 Derived Query，Spring 会解析方法名，生成查询条件。你还可以用 `@Query` 写更明确的查询，也可以定义投影接口只返回部分字段。

但要记住：Repository 背后仍然依赖 MongoTemplate 和 Mapping 层。Repository 方法最终会被转换成 `Query` 对象，交给 MongoTemplate 执行；Mapping 层负责把 MongoDB 文档转换成 Java 实体。所以 Repository 并不是一个新的执行引擎，它只是更高层的抽象。它的价值在于把稳定的查询契约固定下来，让调用方通过方法名就能理解业务语义。

## 03、为什么

为什么 Repository 适合稳定、简单、业务语义明确的数据访问？

第一，约定优于配置。方法名直接表达业务意图，比如 `findByTenantIdAndStatus`，任何人一看就知道是“按租户和状态查商品”。第二，编译期检查。方法名拼错或参数类型不匹配，编译阶段就能暴露，而不是等运行时才报错。第三，减少样板代码。你不用手写 Query 对象、Criteria 条件、分页组装，Spring Data 都会帮你完成。

但这些优势在复杂动态查询面前会变成负担。条件一多，方法名会迅速超出人脑短时记忆范围，可读性急剧下降。可选条件无法用方法名表达，因为 Derived Query 的前提是每个参数都必须参与条件拼接；多选、区间、模糊匹配等场景也会让方法名变得非常别扭。最后，业务规则被埋在长方法名里，团队需要额外注释才能说清逻辑，这本身就说明抽象选错了位置。

简单说：Repository 擅长“固定契约”，不擅长“动态装配”。

## 04、架构

要把 Repository 和 MongoTemplate 配合好，首先要摆正它们的角色。我建议的分层如下：

```text
Controller
   ↓
ProductQueryService
   ├── ProductRepository        ← 稳定查询契约
   └── ProductDynamicQueryDao   ← 注入 MongoTemplate
                 ↓
            MongoTemplate + Mapping
```

Repository 只承担固定、简单、语义明确的查询，比如按租户和状态查列表。MongoTemplate 封装在独立的 DAO 或 QueryService 中，负责组合可选条件、多选、区间、排序和投影。Service 层同时依赖两者，但对调用方而言，只需要知道自己要的是稳定查询还是动态查询。

这里有一个容易踩的坑：不要试图把所有能力都塞进 Repository 接口。Repository 接口本身会随着方法增多而膨胀，最后变成一个巨大的“查询清单”，方法名越来越长，注释越来越多，反而失去了契约表达的意义。

Projection 可以在读场景中减少返回字段，但它和动态查询并不冲突。你可以在 Template 查询中指定返回 DTO，也可以在 Repository 中定义投影接口，关键看字段范围是否稳定。

## 05、实战

回到商品查询。我们按租户、类目、状态、品牌、价格区间五个条件实现一个可维护的查询。

实体大概是这样：

```java
@Document("product")
public class Product {
    @Id
    private String id;
    private String tenantId;
    private String category;
    private String status;
    private String brand;
    private BigDecimal price;
    private String name;
    // 省略 getter/setter
}
```

Repository 只保留稳定查询：

```java
public interface ProductRepository extends MongoRepository<Product, String> {
    Page<Product> findByTenantIdAndStatus(String tenantId, String status, Pageable pageable);

    @Query(value = "{ 'tenantId': ?0, 'category': ?1 }", fields = "{ 'name': 1, 'price': 1, 'brand': 1 }")
    List<ProductSummary> findProductCards(String tenantId, String category);
}
```

投影接口：

```java
public interface ProductSummary {
    String getId();
    String getName();
    BigDecimal getPrice();
    String getBrand();
}
```

动态查询放到独立服务，用 MongoTemplate 组装 Criteria：

```java
@Service
public class ProductDynamicQueryService {
    private final MongoTemplate mongoTemplate;

    public ProductDynamicQueryService(MongoTemplate mongoTemplate) {
        this.mongoTemplate = mongoTemplate;
    }

    public Page<Product> queryProducts(ProductQueryParam param, Pageable pageable) {
        Criteria criteria = Criteria.where("tenantId").is(param.getTenantId());
        if (StringUtils.hasText(param.getCategory())) {
            criteria.and("category").is(param.getCategory());
        }
        if (param.getStatuses() != null && !param.getStatuses().isEmpty()) {
            criteria.and("status").in(param.getStatuses());
        }
        if (StringUtils.hasText(param.getBrand())) {
            criteria.and("brand").is(param.getBrand());
        }
        if (param.getMinPrice() != null) {
            criteria.and("price").gte(param.getMinPrice());
        }
        if (param.getMaxPrice() != null) {
            criteria.and("price").lte(param.getMaxPrice());
        }

        Query query = Query.query(criteria).with(pageable);
        long total = mongoTemplate.count(Query.query(criteria), Product.class);
        List<Product> items = mongoTemplate.find(query, Product.class);
        return new PageImpl<>(items, pageable, total);
    }
}
```

这样，无论前端传多少个条件，我们都能用同一套逻辑组合。分页和排序通过 `Pageable` 统一处理，不需要为每种组合写一个方法。

## 06、洞见

什么时候方法名已经长到应该停止继续拼接？我总结了几条信号：

1. 条件数量超过 3 个，并且不是所有条件都稳定出现。
2. 方法名超过 40 到 50 个字符，读起来需要断句。
3. 条件里出现可选、多选、区间、模糊匹配，方法名推导表达不了或很别扭。
4. 同一个查询要服务多个业务场景，业务规则开始复杂。
5. 你发现团队 review 时，需要在方法名旁写注释才能解释清楚条件组合。

出现任何一条，都应该考虑切到 MongoTemplate。

更核心的洞见是：Repository 的价值是表达稳定查询契约，不是承载数据库全部能力。数据库能力包括聚合、地理位置查询、批量更新、复杂条件组装等，这些本来就是 MongoTemplate 的主场。硬把 Template 的能力塞进 Repository，只会破坏契约清晰度，最后两个都维护不好。

## 07、行动

基于这个认知，我们的行动方案可以分四步：

第一步，梳理现有 Repository 方法。把条件固定、参数稳定、业务语义明确的方法留下；把那些已经开始拼接长方法名、条件可选、逻辑复杂的方法标记出来。

第二步，统一迁移原则。固定条件查询保留在 Repository，参数不超过 3 个是相对舒服的范围；超过 3 个但语义非常固定，可以用 `@Query` 自定义；可选条件、多选、区间统一迁移到 `ProductDynamicQueryService`。

第三步，动态查询用 Criteria 组装。不要在一个方法里堆砌大量 if-else 后还试图保留 Repository 方法名，那样只会更乱。把接口参数封装成 `ProductQueryParam`，内部拼 Criteria，返回 `Page<Product>`。

第四步，分页、排序、投影统一管理。分页排序通过 `Pageable` 或 `Sort` 传入，不要在每个查询里重新写一遍。投影根据列表和详情场景分别处理。

拆分后大致是这样：

| 查询类型 | 实现位置 |
| 固定条件查询 | Repository 方法名或 @Query |
| 少数字段投影 | Repository + Projection |
| 可选条件/区间/多选 | MongoTemplate + Criteria |
| 聚合、批量写入 | MongoTemplate |

新需求优先用 Template，再逐步把库存里的长方法名重构掉。Repository 中的方法名最终应该能直接表达业务，而不是让人去查注释。

## 08、小结

MongoRepository 不是万能钥匙，它是稳定查询契约的表达；MongoTemplate 是灵活的执行引擎。商品查询拆分后，Repository 里只留下了 `findByTenantIdAndStatus` 这类一眼能懂的方法，动态筛选全部走 Template，方法名不再失控，边界清晰，代码也好维护。

## 09、链接与概念说明

概念说明：

- MongoRepository：Spring Data MongoDB 提供的仓库接口，提供 CRUD、分页排序、方法名推导、自定义 @Query 和投影能力。
- MongoTemplate：Spring Data MongoDB 的模板类，提供更细粒度的查询、更新、聚合、批量操作。
- Derived Query：根据方法名推导查询条件，如 findByTenantIdAndStatus。
- Projection：投影查询，只返回指定字段，适合列表卡片场景。
- Criteria：MongoTemplate 中用于构建查询条件的链式对象，支持等值、范围、in、正则等。
- 多租户：通过 tenantId 隔离不同租户数据，所有查询都应带上租户条件。

链接：

- Spring Data MongoDB 官方文档：https://docs.spring.io/spring-data/mongodb/docs/current/reference/html/
- MongoRepository API：https://docs.spring.io/spring-data/mongodb/docs/current/api/org/springframework/data/mongodb/repository/MongoRepository.html
- MongoTemplate API：https://docs.spring.io/spring-data/mongodb/docs/current/api/org/springframework/data/mongodb/core/MongoTemplate.html

我是老李，上个月接了一个多租户商品中心的查询需求。起初我觉得 Spring Data MongoDB 的 Repository 太省事了，findByTenantIdAndCategory 一写，分页排序全都有。结果需求从两个条件变成五个，还出现可选区间，方法名差点写成一行作文。后来团队停下来重新划了条线：简单查询留在 Repository，动态查询切到 MongoTemplate。今天把这条线完整梳理出来。

《Spring Mongo实战》第6招 Repository先够用

从商品列表查询切入，梳理 Repository 的稳定查询契约与 MongoTemplate 的动态查询边界，给出一条可落地的拆分路径。

架构师

后端

数据库

编程语言

多租户商品中心查询优化：Spring Data MongoDB中Repository适合固定条件查询，MongoTemplate擅长动态条件组装。当查询条件超过3个或出现可选、多选、区间时，建议从Repository迁移至Template+Criteria实现，避免长方法名失控，提升代码可维护性。文中提供完整分层方案与实战代码示例。

代码解释

MongoDB

Java

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

多租户商品中心查询优化：Spring Data MongoDB中Repository适合固定条件查询，MongoTemplate擅长动态条件组装。当查询条件超过3个或出现可选、多选、区间时，建议从Repository迁移至Template+Criteria实现，避免长方法名失控，提升代码可维护性。文中提供完整分层方案与...

《Spring Mongo实战》第6招 Repository先够用-腾讯云开发者社区-腾讯云

《Spring Mongo实战》第6招 Repository先够用

《Spring Mongo实战》第6招 Repository先够用

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐