【Spring连载】使用Spring Data访问 MongoDB（二）----Template API

MongoTemplate及其反应式(reactive)对应类位于org.springframework.data.mongodb.core包中，是Spring MongoDB支持的中心类，为与数据库交互提供了丰富的功能集。该template提供了创建、更新、删除和查询MongoDB文档的方便操作，并提供了域对象和MongoDB documents之间的映射。
配置后，MongoTemplate是线程安全的，可以在多个实例中重用。

一、方便的方法

MongoTemplate类实现了MongoOperations接口。在尽可能多的情况下，MongoOperations上的方法以MongoDB driver Collection对象上可用的方法命名，以便让现有使用driver API的MongoDB开发人员熟悉。例如，你可以找到find, findAndModify, findAndReplace, findOne, insert, remove, save, update, 和 updateMulti等方法。设计目标是尽可能容易地在使用基础MongoDB driver和MongoOperations之间进行转换。这两个API之间的主要区别在于，MongoOperations可以传递域对象，而不是Document。此外，MongoOperations为Query, Criteria, 和 Update操作提供了流畅的API，而不是填充Document来指定这些操作的参数。
有关更多信息，请参阅文档的CRUD（章节八、九）部分。
引用MongoTemplate实例上的操作的首选方式是通过其接口MongoOperations。

二、执行回调函数Execute Callbacks

MongoTemplate提供了许多方便的方法来帮助你轻松执行常见任务。但是，如果你需要直接访问MongoDB driver API，可以使用几种Execute回调方法之一。execute回调为你提供了对MongoCollection或MongoDatabase对象的引用。

• < T> T execute (Class<?> entityClass, CollectionCallback< T> action)：为指定类的实体集合运行给定的CollectionCallback。
• < T> T execute (String collectionName, CollectionCallback action)：在给定名称的集合上运行给定的CollectionCallback。
• < T> T execute (DbCallback action)：运行DbCallback，根据需要转换任何异常。Spring Data MongoDB为MongoDB 2.2版引入的聚合（Aggregation）框架提供了支持。
• < T> T execute (String collectionName, DbCallback< T> action)：在给定名称的集合上运行DbCallback，根据需要转换任何异常。
• < T> T executeInSession (DbCallback< T> action)：在与数据库的同一连接中运行给定的DbCallback，以确保写操作繁重的环境中的一致性，在这里你可能读取你所写的数据。
  以下示例使用CollectionCallback返回有关索引的信息：

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

三、Fluent API

作为与MongoDB进行更低级交互的核心组件，MongoTemplate提供了广泛的方法，涵盖了从集合创建、索引创建和CRUD操作到更高级的功能（如Map Reduce和聚合）的需求。你可以为每个方法找到多个重载。其中大多数涉及API的可选的或可为null的部分。
FluentMongoOperations为MongoOperations的常见方法提供了一个更窄的接口，并提供了更易读、更流畅的API。入口点（insert(…), find(…), update(…), 和其他）遵循基于要运行的操作的自然命名模式。从入口点（entry point）来看，API设计为仅提供依赖于上下文的方法，这些方法会导致调用实际MongoOperations对应方的终止方法 — 在以下示例的情况下使用all方法：

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. 如果未使用原始域类型，则用此结果类型。
4. 查找查询。

使用投影（projections）允许MongoTemplate通过将实际响应限制在投影目标类型所需的字段来优化结果映射。只要查询本身不包含任何字段限制，并且目标类型是closed接口或DTO投影，这一点就适用。
投影不得应用于DBRefs。
你可以通过终止（terminating）方法在检索单个实体和检索多个实体之间切换，作为List或Stream ：first(), one(), all(), 或 stream()。
当使用near(NearQuery)编写地理空间查询时，终止（terminating）方法的数量会更改为仅包括对在MongoDB中运行geoNear命令有效的方法（在GeoResults中获取GeoResult实体），如下例所示：

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

四、异常转换

Spring框架为各种各样的数据库和映射技术提供了异常转换。这在传统上是JDBC和JPA的功能。Spring对MongoDB的支持通过提供“org.springframework.dao.support.PersistenceExceptionTranslator”接口的实现，将此功能扩展到MongoDB数据库。
映射到与Spring一致的数据访问异常层次结构背后的动机是，你可以编写可移植的描述性异常处理代码，而无需针对MongoDB错误代码进行编码。Spring的所有数据访问异常都是从根DataAccessException类继承的，因此你可以确保在单个try-catch块中捕获所有与数据库相关的异常。请注意，并不是所有由MongoDB driver抛出的异常都继承自MongoException类。内部异常和消息将被保留，因此不会丢失任何信息。
MongoExceptionTranslator执行的一些映射是“com.mongodb.Network”到DataAccessResourceFailureException，以及MongoException错误代码1003、12001、12010、12011和12012到InvalidDataAccessApiUsageException。查看实现以获取有关映射的更多详细信息。

五、域类型映射

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

六、配置

你可以使用以下配置来创建和注册MongoTemplate的实例，如下例所示：
基于Java的注册MongoClient对象并启用Spring的异常转换支持

@Configuration
class ApplicationConfiguration {@BeanMongoClient mongoClient() {return MongoClients.create("mongodb://localhost:27017");}@BeanMongoOperations mongoTemplate(MongoClient mongoClient) {return new MongoTemplate(mongoClient, "geospatial");}
}

基于XML的注册MongoClient对象

<mongo:mongo-client host="localhost" port="27017" /><bean id="mongoTemplate" class="org.springframework.data.mongodb.core.MongoTemplate"><constructor-arg ref="mongoClient" /><constructor-arg name="databaseName" value="geospatial" />
</bean>

MongoTemplate和ReactiveMongoTemplate有几个重载构造函数：

• MongoTemplate(MongoClient mongo, String databaseName)：使用MongoClient对象和默认的数据库名称进行操作。
• MongoTemplate(MongoDatabaseFactory mongoDbFactory)：采用一个mongoDbFactory对象，该对象封装了MongoClient对象、数据库名称以及用户名和密码。
• MongoTemplate(MongoDatabaseFactory mongoDbFactory, MongoConverter mongoConverter)：添加一个MongoConverter用于映射。

在创建MongoTemplate/ReactiveMongoTemplate时，你可能希望设置的其他可选属性包括默认的WriteResultCheckingPolicy、WriteConcern、ReadPreference和下面列出的其他属性。

6.1 默认读取首选项Read Preference

如果没有通过查询定义其他首选项（9.3.4 读取首选项Read Preference），则将使用默认读取首选项用于读取操作。

6.2 WriteResultChecking策略

6.3 默认写安全WriteConcern

6.4 WriteConcernResolver

6.5 发布实体生命周期事件

6.6 配置EntityCallbacks

6.7 Document count配置

七、索引及集合管理

八、保存、更新和删除Documents

九、查询Documents

9.1 查询集合中的Documents

9.2 选择字段

9.3 其他查询选项

9.3.1 Hints

9.3.2 游标批大小Cursor Batch Size

9.3.3 Collations

9.3.4 读取首选项Read Preference

9.3.5 Comments

十、Counting Documents

十一、聚合（Aggregation）框架支持