此版本仍在开发中，尚未被视为稳定版本。对于最新的稳定版本，请使用 Spring Data MongoDB 4.4.0！spring-doc.cn

模板 API

位于包中的MongoTemplate及其反应式对应类是 Spring 的 MongoDB 支持的中心类，并为与数据库交互提供了丰富的功能集。该模板提供了创建、更新、删除和查询 MongoDB 文档的便捷操作，并提供了域对象和 MongoDB 文档之间的映射。org.springframework.data.mongodb.corespring-doc.cn

配置后，它是线程安全的，并且可以在多个实例之间重复使用。MongoTemplate

便捷方法

MongoTemplate 类实现接口 MongoOperations。在尽可能多的情况下，on 方法以 MongoDB 驱动程序对象上可用的方法命名，以使习惯于驱动程序 API 的现有 MongoDB 开发人员熟悉 API。例如，您可以找到、、、和等方法。设计目标是尽可能轻松地在基本 MongoDB 驱动程序和 . 这两个 API 之间的主要区别是可以传递域对象，而不是 . 此外，具有用于、和操作的 Fluent API，而不是填充来指定这些操作的参数。MongoOperationsCollectionfindfindAndModifyfindAndReplacefindOneinsertremovesaveupdateupdateMultiMongoOperationsMongoOperationsDocumentMongoOperationsQueryCriteriaUpdateDocumentspring-doc.cn

有关更多信息，请参阅文档的 CRUD 和 Query 部分。spring-doc.cn

引用实例上的操作的首选方法是通过其接口 .MongoTemplateMongoOperations

执行回调

MongoTemplate提供了许多便捷的方法来帮助您轻松执行常见任务。但是，如果您需要直接访问 MongoDB 驱动程序 API，则可以使用多种回调方法之一。回调为您提供对 a 或 a 对象的引用。ExecuteexecuteMongoCollectionMongoDatabasespring-doc.cn

<T> T execute ：为指定类的实体集合运行给定的(Class<?> entityClass, CollectionCallback<T> action)CollectionCallbackspring-doc.cn
<T> T execute ：在给定名称的集合上运行给定的。(String collectionName, CollectionCallback<T> action)CollectionCallbackspring-doc.cn
<T> T execute ：运行 DbCallback，根据需要转换任何异常。 Spring Data MongoDB 为版本 2.2 中引入 MongoDB 的聚合框架提供支持。(DbCallback<T> action)spring-doc.cn
<T> T execute ：对给定名称的集合运行，根据需要翻译任何异常。(String collectionName, DbCallback<T> action)DbCallbackspring-doc.cn
<T> T executeInSession ：在与数据库的同一连接中运行给定的，以确保在写入密集型环境中的一致性，您可以在其中读取您编写的数据。(DbCallback<T> action)DbCallbackspring-doc.cn

以下示例使用 CollectionCallback 返回有关索引的信息：spring-doc.cn

Imperativespring-doc.cn
Reactivespring-doc.cn

boolean hasIndex = template.execute("geolocation", collection ->
    Streamable.of(collection.listIndexes(org.bson.Document.class))
        .stream()
        .map(document -> document.get("name"))
        .anyMatch("location_2d"::equals)
);

Mono<Boolean> hasIndex = template.execute("geolocation", collection ->
    Flux.from(collection.listIndexes(org.bson.Document.class))
        .map(document -> document.get("name"))
        .filterWhen(name -> Mono.just("location_2d".equals(name)))
        .map(it -> Boolean.TRUE)
        .single(Boolean.FALSE)
    ).next();

Fluent API

作为与 MongoDB 进行更多底层交互的中心组件，它提供了广泛的方法，涵盖了从集合创建、索引创建和 CRUD 操作到更高级功能（如 Map-Reduce 和聚合）的需求。您可以找到每个方法的多个重载。它们中的大多数涵盖了 API 的可选或可为 null 的部分。MongoTemplatespring-doc.cn

FluentMongoOperations为的常用方法提供了更窄的接口，并提供了更具可读性、更流畅的 API。入口点（、、、和其他）遵循基于要运行的操作的自然命名架构。从入口点开始，API 旨在仅提供依赖于上下文的方法，这些方法会导致调用实际对应项的终止方法 — 以下示例中的方法：MongoOperationsinsert(…)find(…)update(…)MongoOperationsallspring-doc.cn

祈使的

List<Jedi> all = template.query(SWCharacter.class) (1)
  .inCollection("star-wars") (2)
  .as(Jedi.class) (3)
  .matching(query(where("jedi").is(true))) (4)
  .all();

1	用于将查询中使用的字段映射到的类型。
2	如果未在域类型上定义，则要使用的集合名称。
3	Result 类型（如果不使用原始域类型）。
4	查找查询。反应性的 `Flux<Jedi> all = template.query(SWCharacter.class) .inCollection("star-wars") .as(Jedi.class) .matching(query(where("jedi").is(true))) .all();`

使用投影允许通过将实际响应限制为投影目标类型所需的字段来优化结果映射。只要 Query 本身不包含任何字段限制，并且目标类型是封闭接口或 DTO 投影，这就适用。MongoTemplate

投影不得应用于 DBRefs。

您可以通过以下终止方法在检索单个实体和将多个实体检索为 a 或 a 之间切换：、、或。ListStreamfirst()one()all()stream()spring-doc.cn

使用编写地理空间查询时，终止方法的数量将更改为仅包含对在 MongoDB 中运行命令有效的方法（将实体作为 within 获取），如下例所示：near(NearQuery)geoNearGeoResultGeoResultsspring-doc.cn

Imperativespring-doc.cn
Reactivespring-doc.cn

GeoResults<Jedi> results = template.query(SWCharacter.class)
  .as(Jedi.class)
  .near(alderaan) // NearQuery.near(-73.9667, 40.78).maxDis…
  .all();

Flux<GeoResult<Jedi>> results = template.query(SWCharacter.class)
  .as(Jedi.class)
  .near(alderaan) // NearQuery.near(-73.9667, 40.78).maxDis…
  .all();

异常转换

Spring 框架为各种数据库和 Map 技术提供了异常转换。传统上，这是 JDBC 和 JPA 的专利。 Spring 对 MongoDB 的支持通过提供接口的实现将此功能扩展到 MongoDB 数据库。org.springframework.dao.support.PersistenceExceptionTranslatorspring-doc.cn

映射到 Spring 的一致数据访问异常层次结构的动机是，您能够编写可移植的描述性异常处理代码，而无需针对 MongoDB 错误代码进行编码。 Spring 的所有数据访问异常都是从根类继承的，因此您可以确保在单个 try-catch 块中捕获所有与数据库相关的异常。请注意，并非 MongoDB 驱动程序引发的所有异常都继承自该类。内部异常和消息被保留，因此不会丢失任何信息。DataAccessExceptionMongoExceptionspring-doc.cn

MongoExceptionTranslator 执行的一些映射是 to，错误代码 1003、12001、12010、12011 和 12012 到。有关映射的更多详细信息，请查看 implementation 。com.mongodb.NetworkDataAccessResourceFailureExceptionMongoExceptionInvalidDataAccessApiUsageExceptionspring-doc.cn

可以通过在你或其反应式变体上设置自定义的 MongoExceptionTranslator 来配置异常转换。您可能还希望在相应的 .MongoDatabaseFactoryMongoClientFactoryBeanspring-doc.cn

示例 1.配置MongoExceptionTranslator

ConnectionString uri = new ConnectionString("mongodb://username:password@localhost/database");
SimpleMongoClientDatabaseFactory mongoDbFactory = new SimpleMongoClientDatabaseFactory(uri);
mongoDbFactory.setExceptionTranslator(myCustomExceptionTranslator);

自定义异常的动机可能是 MongoDB 在事务期间的行为，其中某些故障（例如写入冲突）可能会成为暂时性的，并且重试可能会导致操作成功。在这种情况下，您可以使用特定的 MongoDB 标签包装异常，并应用不同的异常转换策略。spring-doc.cn

域类型映射

MongoDB 文档和域类之间的映射是通过委托给 MongoConverter 接口的实现来完成的。 Spring 提供了MappingMongoConverter，但你也可以编写自己的转换器。虽然可以使用其他元数据来指定对象到文档的映射，但它也可以通过对 ID 和集合名称的映射使用一些约定来转换不包含其他元数据的对象。这些约定以及 Mapping 注释的使用将在 Mapping 一章中解释。MappingMongoConverterspring-doc.cn